Field a synthetic research study
from a single API call.

Three steps to field your first study:

curl -X POST https://crowdai.up.railway.app/api/v1/developer/keys \
  -H "Content-Type: application/json" \
  -d '{"user_id": "YOUR_USER_ID", "name": "My App"}'

curl -X POST https://crowdai.up.railway.app/api/v1/developer/simulations \
  -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Should companies mandate return-to-office?",
    "mode": "voting",
    "demographic_preset": "us_general_population",
    "population_size": 50
  }'

All endpoints (except key creation) require a Bearer token in the Authorization header:

Authorization: Bearer crowd_aBcDeFgH1234...

Keys are prefixed with crowd_ and stored as SHA-256 hashes on our infrastructure. The raw key is returned only at creation.

import requests

API_KEY = "crowd_YOUR_API_KEY"
BASE = "https://crowdai.up.railway.app/api/v1/developer"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Run a simulation
response = requests.post(f"{BASE}/simulations", headers=headers, json={
    "topic": "Is remote work better for productivity?",
    "mode": "voting",
    "demographic_preset": "tech_early_adopters",
    "population_size": 100,
    "stance_statement": "Remote work improves employee productivity",
})

result = response.json()
print(f"Status: {result['status']}")
print(f"Results: {result['results']['summary']}")

# List available presets
presets = requests.get(f"{BASE}/presets", headers=headers).json()
print(f"{presets['count']} presets available")

# Launch in background (returns immediately)
curl -X POST https://crowdai.up.railway.app/api/v1/developer/simulations/async \
  -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Should companies mandate return-to-office?",
    "mode": "voting",
    "demographic_preset": "us_general_population",
    "population_size": 500
  }'

# Response: { "id": "sim-abc", "status": "pending",
#   "poll_url": "/api/v1/developer/simulations/sim-abc/status",
#   "results_url": "/api/v1/developer/simulations/sim-abc" }

# Poll until complete
curl -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  https://crowdai.up.railway.app/api/v1/developer/simulations/SIM_ID/status

# Fetch full results once status is "complete"
curl -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  https://crowdai.up.railway.app/api/v1/developer/simulations/SIM_ID

const API_KEY = "crowd_YOUR_API_KEY";
const BASE = "https://crowdai.up.railway.app/api/v1/developer";

// Run a simulation
const response = await fetch(`${BASE}/simulations`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    topic: "What do consumers think about subscription fatigue?",
    mode: "voting",
    demographic_preset: "millennials",
    population_size: 200,
  }),
});

const { id, status, results } = await response.json();
console.log(`Simulation ${id}: ${status}`);
console.log("Summary:", results.summary);

// Each agent's response includes their persona + reasoning
for (const agent of results.agents.slice(0, 3)) {
  console.log(`${agent.name} (${agent.sentiment}): ${agent.reasoning}`);
}

Every study targets a demographic preset — a statistically grounded population model calibrated against published distributions (US ACS 2023, UK ONS 2021, AU ABS 2021) with OCEAN trait distributions from Rentfrow 2008 and Schmitt 2007.

Forty-two presets ship by default across six categories. Enumerate via GET /developer/presets or reference this selection:

Fielding duration:A 20-respondent Pulse study typically completes in 5–15 seconds. Panels at scale (200+ respondents) typically field in 30–120 seconds. For large populations, use POST /simulations/async which returns immediately, then poll GET /simulations/{id}/status until complete. Rate-limited requests receive a 429 with a Retry-After header.