API v1

API Reference

Stable as of v1. All endpoints are versioned in the path; breaking changes ship as a new prefix with a deprecation window.

Endpoints

POST	/v1/simulations	Create a simulation with an explicit workflow_id. Returns 202 with poll URL. See /docs/simulations.
POST	/v1/simulations/auto	Auto-route a natural-language question to the best calibrated workflow. Returns 202 + meta.routed_via; falls back to 422 routing_low_confidence with alternatives.
GET	/v1/simulations	List your organization's simulations. Cursor-paginated.
GET	/v1/simulations/:id	Get simulation status. Honors Retry-After while running.
GET	/v1/simulations/:id/results	Get full per-agent results. 409 if simulation not yet complete.
POST	/v1/api-keys/{key_id}/rotate	Rotate an API key. See /docs/api-keys for full lifecycle.
GET	/v1/status	Public health probe: API + DB + Redis components, plus link-outs for Stripe + Resend. 30s Redis cache.
GET	/v1/usage	Current-period consumption + plan-tier caps. Returns simulations-this-period, lifetime count, agent-count ceiling, and per-minute rate limit. No scope required — the data is the caller's own.
POST	/v1/auth/password/signup	Create a new organization + user with a chosen password and start a session. Public; per-IP rate-limited (5 req/min). Body: {email, password (10-200 chars), name, organization_name}. Returns 201 + SessionResponse with Set-Cookie.

POST/v1/simulations

Create a new simulation. The response is asynchronous (per ADR-006): all simulations are queued and delivered via webhook on completion. See /docs/simulations for the full endpoint family + webhook signature verification.

Body

workflow_idstringrequired

Workflow slug identifying which calibrated YAML aggregator to run.

agent_countintegerrequired

Number of agents to simulate. 1—10,000.

scenario_contextobjectrequired

Workflow-specific parameters. See workflow docs.

seedinteger

Optional deterministic seed.

webhook_urlstring

Override default webhook for this sim.

Example request

POST /v1/simulations HTTP/1.1
Authorization: Bearer sk_test_...
Idempotency-Key: 01HXZ...

{
  "workflow_id": "cdc_nhis_smoking",
  "agent_count": 200,
  "scenario_context": { "region": "US" },
  "seed": 7
}

Response — 201

{
  "id": "sim_01HXA6QC2F",
  "status": "queued",
  "created_at": "2026-04-22T18:34:12Z"
}

POST/v1/simulations/auto

Take a natural-language question and route it to the best calibrated workflow, then create the simulation. Same async contract as /v1/simulations (202 + poll URL), with meta.routed_via describing the chosen workflow + confidence. When confidence is below the routing floor (default 0.65), responds 422 routing_low_confidence with the top alternatives in meta.alternatives so you can pick explicitly and re-submit against /v1/simulations with an explicit workflow_id.

Body

questionstringrequired

Natural-language question. 10—2,000 chars. The auto-router scores every published workflow against this text.

agent_countinteger

Optional. Defaults to the matched workflow's recommended sample size. Subject to your plan tier's ceiling.

scenario_contextobject

Optional. Workflow-specific overrides applied after routing.

Example request

POST /v1/simulations/auto HTTP/1.1
Authorization: Bearer sk_test_...
Idempotency-Key: 01HXZ...

{
  "question": "Will families take a summer vacation this year despite high prices?",
  "agent_count": 500
}

Response — 202 (routed)

{
  "data": {
    "id": "sim_01HXA6QC2F",
    "status": "queued"
  },
  "meta": {
    "routed_via": {
      "workflow_id": "aaa_summer_travel",
      "workflow_name": "AAA Summer Travel — At Least One Overnight Trip",
      "confidence": 0.84
    }
  }
}

Response — 422 (routing_low_confidence)

{
  "error": "routing_low_confidence",
  "meta": {
    "alternatives": [
      { "workflow_id": "cdc_nhis_smoking", "confidence": 0.42 },
      { "workflow_id": "aaa_summer_travel", "confidence": 0.38 }
    ]
  }
}

Errors

Code	Type	Description
400	invalid_workflow	Workflow slug does not exist or is deprecated.
402	insufficient_quota	Account has reached its monthly simulation limit.
429	rate_limited	Too many requests. Back off per Retry-After.