Simulations

Simulations are the core resource of the Kairos API. You can create them from pre-built scenarios or custom configurations, advance them tick-by-tick or in bulk, retrieve their full execution trace, and control agent policies and playback in real time.

All simulation endpoints require authentication. Write operations require the simulation:write scope; read operations require simulation:read.

Create Simulation

POST /v1/simulations

Creates a new simulation instance. Provide either a scenarioId (to use a pre-built scenario) or an inline scenario object — not both.

Request Body

Field	Type	Required	Description
scenarioId	string	One of	ID of a pre-built scenario
scenario	object	One of	Inline scenario configuration
scenario.seed	number	Yes	Random seed
scenario.agents	Agent[]	Yes	Agent configurations
scenario.initialState	object	Yes	Starting state
organizationId	uuid	No	Organization to bill against
engineVersion	string	No	Pin a specific engine version

Response 201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scenarioId": "capability-divergence",
  "engineVersion": "1.4.4",
  "state": { }
}

Example

curl -X POST https://api.anankelabs.ai/v1/simulations \
  -H "X-Api-Key: krs_..." \
  -H "Content-Type: application/json" \
  -d '{"scenarioId": "capability-divergence"}'

Create Simulation from Domain

POST /v1/simulations/from-domain

Creates a simulation using a domain adapter. Domain adapters translate domain-specific input (e.g., AI Safety vocabulary) into the engine’s native scenario format.

Request Body

Field	Type	Required	Description
domain	string	Yes	Domain adapter identifier (e.g., "ai-safety")
input	object	Yes	Domain-specific input payload
organizationId	uuid	No	Organization to bill against
engineVersion	string	No	Pin a specific engine version

Response 201

Same shape as Create Simulation.

Errors

Status	Code	When
404	NOT_FOUND	Unknown domain adapter

Run Simulation

POST /v1/simulations/run

Creates and executes a simulation in a single request, returning the complete trace. This is the most convenient endpoint for batch workloads.

Request Body

Field	Type	Required	Description
scenarioId	string	One of	Pre-built scenario ID
domain	string	One of	Domain adapter identifier
input	object	With domain	Domain-specific input payload
ticks	number	Yes	Number of ticks to simulate (1–10,000)
organizationId	uuid	No	Organization to bill against
engineVersion	string	No	Pin a specific engine version

Streaming Response

Set Accept: application/x-ndjson to receive the trace as newline-delimited JSON, where each line is a trace step. This is useful for large simulations that would be expensive to buffer in memory.

Response 200 (JSON)

{
  "simulationId": "a1b2c3d4-...",
  "engineVersion": "1.4.4",
  "trace": {
    "metadata": { },
    "initialState": { },
    "steps": [
      {
        "tick": 0,
        "move": "idle",
        "state": { },
        "warning": null,
        "loss": null,
        "agents": [
          {
            "id": "frontier_model",
            "state": { },
            "policy": { "lambda": 0.5, "gamma": 0.3 }
          }
        ]
      }
    ]
  }
}

Example — JSON

curl -X POST https://api.anankelabs.ai/v1/simulations/run \
  -H "X-Api-Key: krs_..." \
  -H "Content-Type: application/json" \
  -d '{"scenarioId": "capability-divergence", "ticks": 500}'

Example — Streaming NDJSON

curl -X POST https://api.anankelabs.ai/v1/simulations/run \
  -H "X-Api-Key: krs_..." \
  -H "Accept: application/x-ndjson" \
  -H "Content-Type: application/json" \
  -d '{"scenarioId": "capability-divergence", "ticks": 500}'

List Simulations

GET /v1/simulations

Returns a paginated list of simulations accessible to the authenticated identity.

Query Parameters

Parameter	Type	Default	Description
organizationId	uuid	—	Filter by organization (JWT users only; API keys use their own org)
limit	integer	50	Results per page (1–200)
offset	integer	0	Pagination offset

Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "scenarioId": "capability-divergence",
      "organizationId": "org-uuid",
      "createdAt": "2025-06-15T10:30:00.000Z",
      "state": { }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 142
  }
}

Example

curl "https://api.anankelabs.ai/v1/simulations?limit=10" \
  -H "X-Api-Key: krs_..."

Get Simulation

GET /v1/simulations/{id}

Returns the current state of a single simulation.

Path Parameters

Parameter	Type	Description
id	uuid	Simulation ID

Response

{
  "id": "a1b2c3d4-...",
  "scenarioId": "capability-divergence",
  "organizationId": "org-uuid",
  "state": { },
  "createdAt": "2025-06-15T10:30:00.000Z"
}

Errors

Status	Code	When
401	UNAUTHORIZED	Not authorized to access this simulation
404	NOT_FOUND	Simulation does not exist

Step Simulation

POST /v1/simulations/{id}/step

Advances an existing simulation by a given number of ticks.

Path Parameters

Parameter	Type	Description
id	uuid	Simulation ID

Request Body

Field	Type	Required	Description
ticks	number	Yes	Number of ticks to advance (1–10,000)

Response

{
  "state": { },
  "ticks": 100
}

Example

curl -X POST https://api.anankelabs.ai/v1/simulations/a1b2c3d4-.../step \
  -H "X-Api-Key: krs_..." \
  -H "Content-Type: application/json" \
  -d '{"ticks": 100}'

Get Trace

GET /v1/simulations/{id}/trace

Returns the full execution trace for a simulation that has been run. Supports both JSON and NDJSON streaming via the Accept header.

Path Parameters

Parameter	Type	Description
id	uuid	Simulation ID

Response (JSON)

{
  "metadata": { },
  "initialState": { },
  "steps": [
    {
      "tick": 0,
      "move": "idle",
      "state": { },
      "warning": null,
      "loss": null,
      "agents": [
        {
          "id": "frontier_model",
          "state": { },
          "policy": { "lambda": 0.5, "gamma": 0.3 }
        }
      ]
    }
  ]
}

Trace Step Fields

Field	Type	Description
tick	number	The simulation tick number
move	string	The move that was applied
state	object	Full simulation state at this tick
warning	object | null	Warning if stability threshold was crossed
loss	object | null	Basin loss event, if one occurred
agents	Agent[]	Per-agent state and policy snapshot

Errors

Status	Code	When
404	NOT_FOUND	Simulation not found or trace not yet available

Example — Streaming

curl https://api.anankelabs.ai/v1/simulations/a1b2c3d4-.../trace \
  -H "X-Api-Key: krs_..." \
  -H "Accept: application/x-ndjson"

Update Agent Policy

PUT /v1/simulations/{id}/agent-policy

Updates the policy parameters for a specific agent within a running simulation.

Path Parameters

Parameter	Type	Description
id	uuid	Simulation ID

Request Body

Field	Type	Required	Description
agentId	string	Yes	The agent to update
policy.lambda	number	No	New lambda (latency/chaos) parameter
policy.gamma	number	No	New gamma (capacity/order) parameter

Response

{ "ok": true }

Example

curl -X PUT https://api.anankelabs.ai/v1/simulations/a1b2c3d4-.../agent-policy \
  -H "X-Api-Key: krs_..." \
  -H "Content-Type: application/json" \
  -d '{"agentId": "frontier_model", "policy": {"lambda": 0.7}}'

Time Control

PUT /v1/simulations/{id}/time-control

Controls playback of a running simulation — play, pause, or single-step.

Path Parameters

Parameter	Type	Description
id	uuid	Simulation ID

Request Body

Field	Type	Required	Description
action	string	Yes	One of "play", "pause", or "step"
speed	number	No	Playback speed multiplier (0.1–10)

Response

{ "ok": true }

Example

curl -X PUT https://api.anankelabs.ai/v1/simulations/a1b2c3d4-.../time-control \
  -H "X-Api-Key: krs_..." \
  -H "Content-Type: application/json" \
  -d '{"action": "play", "speed": 2.0}'