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

All API requests require a Bearer token. Obtain your token from the dashboard under Settings > API Keys.

Authorization: Bearer your_api_key_here

Magic Link Authentication

Request Body

{
  "email": "user@example.com"
}

Response

{
  "success": true,
  "message": "Magic link sent to user@example.com"
}

Example

curl -X POST https://crowdproof.xyz/api/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Auth Callback

Query Parameters

Response

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "plan": "pro"
  },
  "session_token": "sess_xyz789"
}

Create Simulation

Request Body

{
  "seed": "We are raising prices by 15% starting next month.",
  "seed_type": "text",
  "audience": "general",
  "agent_count": 250,
  "rounds": 10
}

Response

{
  "id": "sim_abc123",
  "status": "running",
  "seed": "We are raising prices by 15% starting next month.",
  "audience": "general",
  "agent_count": 250,
  "rounds": 10,
  "created_at": "2024-01-15T10:30:00Z"
}

Example

curl -X POST https://crowdproof.xyz/api/simulations \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "seed": "We are raising prices by 15% starting next month.",
    "seed_type": "text",
    "audience": "general",
    "agent_count": 250,
    "rounds": 10
  }'

Get Simulation

Response

{
  "id": "sim_abc123",
  "status": "completed",
  "seed": "We are raising prices by 15% starting next month.",
  "audience": "general",
  "agent_count": 250,
  "rounds": 10,
  "current_round": 10,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:33:45Z",
  "summary": {
    "overall_sentiment": "mixed",
    "positive_pct": 32,
    "negative_pct": 45,
    "neutral_pct": 23
  }
}

Example

curl https://crowdproof.xyz/api/simulations/sim_abc123 \
  -H "Authorization: Bearer your_api_key"

Stream Simulation

Event Types

Example

curl -N https://crowdproof.xyz/api/simulations/sim_abc123/stream \
  -H "Authorization: Bearer your_api_key" \
  -H "Accept: text/event-stream"

Event Data

event: agent_post
data: {"agent_id": "agt_123", "content": "This price increase is ridiculous!", "faction": "negative"}

event: faction_update
data: {"positive": 32, "negative": 45, "curious": 15, "viral": 3, "pragmatic": 5}

event: simulation_complete
data: {"status": "completed", "duration_ms": 185000}

Inject Event

Request Body

{
  "content": "BREAKING: Company releases statement clarifying the price change only affects enterprise customers.",
  "type": "breaking_news"
}

Response

{
  "success": true,
  "injected_at_round": 5
}

Example

curl -X POST https://crowdproof.xyz/api/simulations/sim_abc123/inject \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "BREAKING: Company releases clarification.",
    "type": "breaking_news"
  }'

Pause Simulation

Response

{
  "success": true,
  "status": "paused",
  "paused_at_round": 5
}

Example

curl -X POST https://crowdproof.xyz/api/simulations/sim_abc123/pause \
  -H "Authorization: Bearer your_api_key"

Resume Simulation

Response

{
  "success": true,
  "status": "running"
}

Example

curl -X POST https://crowdproof.xyz/api/simulations/sim_abc123/resume \
  -H "Authorization: Bearer your_api_key"

Get Report

Response

{
  "id": "sim_abc123",
  "summary": {
    "overall_sentiment": "mixed",
    "one_liner": "Price increase met with significant pushback, especially from long-term customers."
  },
  "factions": [
    {"name": "negative", "percentage": 45, "trend": "stable"},
    {"name": "positive", "percentage": 32, "trend": "declining"},
    {"name": "curious", "percentage": 15, "trend": "growing"},
    {"name": "pragmatic", "percentage": 5, "trend": "stable"},
    {"name": "viral", "percentage": 3, "trend": "stable"}
  ],
  "key_arguments": {
    "positive": ["Value still exceeds competitors", "Improvements justify cost"],
    "negative": ["No warning given", "Loyal customers feel betrayed"]
  },
  "viral_moments": [
    {"content": "15% increase with 0% improvement?", "shares": 47}
  ],
  "notable_quotes": [
    {"agent": "Sarah, Budget Conscious", "quote": "I need to start looking at alternatives."}
  ]
}

Example

curl https://crowdproof.xyz/api/simulations/sim_abc123/report \
  -H "Authorization: Bearer your_api_key"

List Audience Presets

Response

{
  "presets": [
    {
      "id": "general",
      "name": "General Public",
      "description": "Diverse cross-section of the population",
      "archetype_count": 15
    },
    {
      "id": "tech-twitter",
      "name": "Tech Twitter",
      "description": "Startup and developer community",
      "archetype_count": 12
    },
    {
      "id": "small-business",
      "name": "Small Business Owners",
      "description": "Entrepreneurs and local business operators",
      "archetype_count": 11
    }
  ]
}

Example

curl https://crowdproof.xyz/api/presets \
  -H "Authorization: Bearer your_api_key"

Create Checkout Session

Request Body

{
  "plan": "pro",
  "billing_cycle": "monthly"
}

Response

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_abc123"
}

Example

curl -X POST https://crowdproof.xyz/api/billing/checkout \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro", "billing_cycle": "monthly"}'

Rate Limits

API requests are rate limited based on your plan:

Error Codes

Next Steps

• Getting Started - Learn the basics first
• Simulations - Understand simulation configuration