API Reference

The CrowdProof API lets you create and manage simulations programmatically. Integrate social simulation into your workflow, CI/CD pipeline, or custom applications.

Authentication

API requests accept two authentication methods:

• Session cookie (all plans) - set automatically when you log in via the browser.
• Bearer token (Enterprise plan) - pass an API key in the Authorization header. Keys are created and managed at /dashboard/keys.

Authorization: Bearer cp_live_...

Keys carry a scope: full (read and write) or read (read-only). Read-only keys work on list, get, report, sentiment, factions, and validation routes but receive a 403 on anything that creates or mutates data.

Create Simulation

Request Body

{
  "seed_text": "We are raising prices by 15% starting next month.",
  "audience_preset": "general_public",
  "agent_count": 100,
  "rounds": 10,
  "platforms": ["pulse", "forum", "circle", "network", "board"],
  "industry": "saas",
  "webhook_url": "https://example.com/hooks/crowdproof"
}

Response

{
  "id": "a1b2c3d4-...",
  "title": "Simulation 2026-07-13 21:05",
  "status": "seeding",
  "share_token": "abc123...",
  "stream_url": "/api/sim/a1b2c3d4-.../stream"
}

share_token is the public share-link token; build the read-only spectator/report URL as https://crowdproof.xyz/sim/{share_token}/share without a follow-up request.

Example

curl -X POST https://api.crowdproof.xyz/api/sim/create \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "seed_text": "We are raising prices by 15% starting next month.",
    "audience_preset": "general_public",
    "agent_count": 100,
    "rounds": 10
  }'

Create A/B Experiment

Request Body

{
  "seed_a": "We are raising prices by 15% starting next month.",
  "seed_b": "We are introducing a new premium tier with additional features.",
  "audience_preset": "general_public",
  "agent_count": 100,
  "rounds": 10
}

Consumes two monthly sim credits. Returns both simulation IDs.

List Simulations

Response

[
  {
    "id": "a1b2c3d4-...",
    "title": "Price increase test",
    "status": "completed",
    "agent_count": 100,
    "rounds": 10,
    "current_round": 10,
    "audience_preset": "general_public",
    "topic_summary": "The crowd debated whether a 15% price hike is justified.",
    "final_sentiment": -0.18,
    "alignment_pct": 82,
    "cost_usd": 0.45,
    "created_at": "2026-07-01T10:30:00Z",
    "completed_at": "2026-07-01T10:33:45Z"
  }
]

Get Simulation

Response

{
  "id": "a1b2c3d4-...",
  "title": "Price increase test",
  "status": "completed",
  "seed_content": "We are raising prices by 15% starting next month.",
  "audience_preset": "general_public",
  "agent_count": 100,
  "rounds": 10,
  "current_round": 10,
  "platforms": ["pulse", "forum", "circle", "network", "board"],
  "industry": "saas",
  "topic_summary": "The crowd debated whether a 15% price hike is justified.",
  "cost_usd": 0.45,
  "share_token": "abc123...",
  "created_at": "2026-07-01T10:30:00Z",
  "completed_at": "2026-07-01T10:33:45Z"
}

Example

curl https://api.crowdproof.xyz/api/sim/a1b2c3d4-... \
  -H "Authorization: Bearer cp_live_..."

Rename or Archive

Request Body

{
  "title": "Updated title",
  "archived": false
}

Send title, archived, or both.

Delete Simulation

Get Report

Response

{
  "summary": "Price increase met with significant pushback...",
  "stats": {
    "total_agents": 100,
    "total_posts": 620,
    "total_actions": 2408,
    "virality_index": 3.2
  },
  "outcome": {
    "stance": { "positive_pct": 32, "neutral_pct": 23, "negative_pct": 45 },
    "intent": { "likely_pct": 28, "maybe_pct": 35, "unlikely_pct": 37 }
  },
  "sentiment": {
    "summary": { "start": 0.0, "end": -0.18, "min": -0.31, "max": 0.08, "total_change": -0.18, "volatility": 0.06 },
    "history": [{ "round": 1, "overall": 0.02, "by_faction": {} }],
    "shifts": [{ "round": 6, "direction": "negative", "change": -0.21 }]
  },
  "factions": {
    "final": [{ "id": "faction_0", "name": "Loyal but Wary", "agent_count": 44, "avg_sentiment": -0.31, "trend": "stable" }],
    "history": [{ "round": 5, "factions": [...] }]
  },
  "viral_content": {
    "top_posts": [{ "id": "post_1", "agent_name": "Sarah", "content": "15% increase with 0% improvement?", "engagement": 47, "faction_id": "faction_0", "stance": -0.6, "platform": "pulse", "round": 3 }],
    "viral_moments": [{ "round": 4, "content": "...", "engagement": 47, "std_devs": 2.8 }]
  },
  "key_arguments": [{ "faction": "Loyal but Wary", "argument": "No warning given.", "support_count": 44, "sentiment": -0.31, "agent_name": "Sarah" }],
  "platforms": [{ "platform": "pulse", "posts": 310, "engagement": 1415, "avg_stance": -0.22 }],
  "hashtags": [{ "tag": "PriceHike", "uses": 34, "engagement": 890, "avg_stance": -0.4, "first_round": 2 }],
  "influencers": [{ "agent_name": "Sarah", "agent_handle": "sarah_m", "followers": 47, "posts": 12, "engagement": 234, "stance": -0.45 }],
  "insights": ["..."],
  "recommendations": ["..."]
}

Example

curl https://api.crowdproof.xyz/api/sim/a1b2c3d4-.../report \
  -H "Authorization: Bearer cp_live_..."

Export Report as Markdown

Example

curl -O -J https://api.crowdproof.xyz/api/sim/a1b2c3d4-.../report/export \
  -H "Authorization: Bearer cp_live_..."

Export Feed as CSV

Example

curl -O -J https://api.crowdproof.xyz/api/sim/a1b2c3d4-.../feed.csv \
  -H "Authorization: Bearer cp_live_..."

Get Sentiment

Get Factions

Inject Event

Request Body

{
  "content": "BREAKING: Company releases statement clarifying the price change.",
  "injection_type": "news",
  "platform": "pulse",
  "at_round": 8
}

Response (immediate)

{
  "post_id": "inject_abc12345",
  "round": 5,
  "platform": "pulse"
}

Response (scheduled)

{
  "scheduled": true,
  "round": 8,
  "injection_id": "..."
}

Scheduled injections can be listed or cancelled:

Pause and Resume

Stream Simulation (SSE)

Event Types

Completion Webhook

Pass a webhook_url when creating a simulation. CrowdProof will POST a JSON payload the moment the run finishes, so pipelines can react without polling. The URL must be a publicly reachable https endpoint; private and localhost hosts are rejected at creation time.

Payload

{
  "event": "simulation.completed",
  "simulation_id": "a1b2c3d4-...",
  "title": "Price increase test",
  "status": "completed",
  "report_url": "https://crowdproof.xyz/sim/a1b2c3d4-.../report"
}

Failed runs deliver "event": "simulation.failed" and "status": "failed". Failed runs also refund the consumed sim credit automatically.

Real-World Validation

{
  "positive_pct": 35,
  "neutral_pct": 25,
  "negative_pct": 40,
  "source": "Post-launch survey, n=200",
  "respondents": 200
}

API Key Management

Enterprise plan only. Requires session-cookie authentication.

{
  "name": "CI Pipeline",
  "scopes": "full"
}

scopes is "full" (default) or "read".

Rate Limits

API requests are subject to plan-based limits:

Error Codes

Next Steps

• Getting Started - Learn the basics
• Simulations - Understand simulation configuration
• Audiences - Explore audience presets and custom audiences
• Accuracy - See real-world validation results