REST API Overview

The Kairos REST API provides programmatic access to the Kairos Recursive Causality Simulator. All endpoints are served under the /v1 prefix and follow standard REST conventions.

Base URL

https://api.anankelabs.ai/v1

An interactive API reference powered by Scalar is available at /v1/docs, and the raw OpenAPI 3.1 specification is served at /v1/openapi.json.

Authentication

The API supports two authentication methods. Protected endpoints require exactly one of these.

API Key

Pass your organization’s API key in the X-Api-Key header. Keys are prefixed with krs_.

curl https://api.anankelabs.ai/v1/simulations \
  -H "X-Api-Key: krs_your_api_key_here"

API keys are scoped. When you create a key you assign it one or more of the following scopes:

Scope	Grants access to
simulation:read	List and retrieve simulations, traces, prophecies
simulation:write	Create simulations, run steps, submit decrees, update policies
org:read	Read organization details and license info
usage:read	Read usage and billing metrics

Bearer JWT

Pass a JWT token in the Authorization header. This method is primarily used by the Kairos web application.

curl https://api.anankelabs.ai/v1/simulations \
  -H "Authorization: Bearer eyJhbGciOi..."

Public Endpoints

The following endpoints require no authentication:

• GET /v1/health
• GET /v1/openapi.json
• GET /v1/docs
• GET /v1/scenarios
• GET /v1/scenarios/{id}

Error Handling

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Simulation not found.",
    "details": null,
    "requestId": "req_abc123"
  }
}

For validation errors, the details field contains an issues array describing each field-level problem:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "issues": [
        { "path": "ticks", "message": "Number must be less than or equal to 10000" }
      ]
    },
    "requestId": "req_abc123"
  }
}

HTTP Status Codes

Status	Meaning
200	Success
201	Resource created
400	Validation error
401	Missing or invalid authentication
403	Insufficient scope or not authorized for the resource
404	Resource not found
409	Idempotency key reused with a different request body
429	Rate limit exceeded
500	Internal server error

Rate Limiting

Rate limits are enforced per identity (API key, user, or IP address). Limits scale with your organization’s license tier and are surfaced in the response headers below.

Route classifications:

• Create — POST /simulations*, POST /simulations/{id}/decrees
• Step — POST /simulations/{id}/step
• Read — all GET requests
• SSE — GET /simulations/{id}/events (concurrent connection limit)

Rate Limit Headers

Every response includes rate limit metadata:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (only on 429)

Idempotency

For POST (create/mutate) endpoints, you can pass an Idempotency-Key header to safely retry requests without creating duplicate resources.

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

Behavior:

• Same key + same body — replays the cached response (response includes Idempotency-Replayed: true header)
• Same key + different body — returns 409 IDEMPOTENCY_KEY_REUSE
• New key — executes normally and caches the response

Idempotency keys expire after 24 hours. The key is scoped to your identity, the HTTP method, and the request path.

Common Request Headers

Header	Required	Description
X-Api-Key	One of	API key authentication
Authorization	One of	Bearer JWT authentication
Content-Type	For request bodies	application/json
Accept	Optional	application/json (default) or application/x-ndjson for streaming
X-Request-Id	Optional	Custom request ID for tracing; auto-generated if omitted
Idempotency-Key	Optional	Idempotent retry key for POST requests

Common Response Headers

Header	Description
X-Request-Id	Request identifier (echo or auto-generated)
X-RateLimit-Limit	Rate limit ceiling
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	Window reset timestamp
Retry-After	Seconds to wait (only on 429)
Idempotency-Replayed	true if the response was replayed from cache