REFERENCE

Canonical REST & WebSocket API.

Actae is API-first: the server exposes a complete, language-agnostic REST and WebSocket interface for events, transitions, state, exact-boundary forks, tool ledgers, and multi-agent coordination.

The API is the product

Every feature in Actae is available directly over HTTP and WebSocket. SDKs in Python, Go, and TypeScript are thin, typed clients over this canonical interface. Any language with an HTTP client and WebSocket support can integrate with Actae without an SDK.

ResourceProtocolKey operations
EventsHTTP + WSrecord, transition, replay, query
StateHTTPsave_state, load_state, versions, version
ForksHTTPfork, receipt, steps
Lineage & experimentsHTTPtree, diff, compare, trail, rank, promote
CoordinationHTTPclaims, consumer groups, wakeups
Execution GroupsHTTP + WSmessages, leases, group forks
Live StreamWebSocketsubscribe, publish, cursor_sync

Authentication & headers

Authenticate requests by passing your API key in the X-API-Key header (or Authorization: Bearer <jwt> for dashboard sessions).

HeaderDescription
X-API-KeyAPI key credential (e.g. sk-... or sk-dev-...)
Idempotency-KeyOptional UUID header for mutation idempotency; mapped to operation_id
Content-Typeapplication/json for JSON request bodies

Event store routes

POST /api/v1/events/record

Persists a single immutable event and assigns a gapless, per-channel sequential cursor.

POST /api/v1/events/record
Content-Type: application/json
X-API-Key: sk-...

{
  "channel_id": "agent-session-1",
  "event_type": "tool.completed",
  "payload": {"result": "success", "duration_ms": 120},
  "actor": "agent-worker",
  "operation_id": "01918a10-0000-7000-8000-000000000001"
}

POST /api/v1/events/transition

Atomically records an event and a state snapshot in a single database transaction. Supports optimistic concurrency guards (expected_version, expected_cursor).

POST /api/v1/events/transition
Content-Type: application/json
X-API-Key: sk-...

{
  "channel_id": "agent-session-1",
  "event_type": "agent.stepped",
  "payload": {"step": 3},
  "state": {"memory": ["item1", "item2"], "step_count": 3},
  "actor": "agent-worker",
  "expected_version": 2
}

GET /api/v1/events/replay/{channel_id}

Returns ordered events for a channel starting after the given cursor (exclusive semantics: ?cursor=0 reads all events from cursor 1).

GET /api/v1/events/replay/agent-session-1?cursor=0&limit=100
X-API-Key: sk-...

POST /api/v1/events/query

Cross-channel filtered query with keyset pagination. Supply an optional signed page_token to advance pages stably under concurrent writes.

POST /api/v1/events/query
Content-Type: application/json
X-API-Key: sk-...

{
  "channel_ids": ["agent-session-1", "agent-session-2"],
  "event_type": "tool.completed",
  "limit": 50,
  "page_token": null
}

State snapshots

EndpointMethodDescription
/api/v1/state/{channel_id}POSTSaves a versioned state snapshot at a cursor
/api/v1/state/{channel_id}GETLoads the latest state snapshot
/api/v1/state/{channel_id}/versionsGETLists state versions for a channel
/api/v1/state/{channel_id}/version/{version}GETLoads a specific historical state version

Exact-boundary forking

POST /api/v1/channels/fork

Creates a child fork inheriting exact parent state at a cursor boundary, writing fork.started and recording an immutable receipt.

POST /api/v1/channels/fork
Content-Type: application/json
X-API-Key: sk-...

{
  "source_channel_id": "session-prod",
  "new_channel_id": "session-experiment-1",
  "at_cursor": 5,
  "display_name": "Prompt refinement variant A"
}

GET /api/v1/channels/{channel_id}/receipt

Retrieves the immutable ForkReceipt describing requested/resolved boundary cursors, source state version, SHA-256 fingerprint, and reproducibility grade.

Tool execution ledger & coordination

Idempotent tool execution coordination guarantees that ambiguous network retries never cause duplicate tool runs:

  • POST /api/v1/executions/claim — Claims exclusive ownership of a tool execution with a lease and parameter fingerprint.
  • POST /api/v1/executions/{id}/complete — Stores the result; subsequent retries with the same operation key return the recorded result.
  • POST /api/v1/executions/{id}/fail — Records a structured failure.
  • POST /api/v1/executions/{id}/heartbeat — Renews an in-progress execution lease.
  • POST /api/v1/executions/{id}/cancel — Cancels the claimed execution.

WebSocket wire protocol (/ws)

Connect to /ws (or wss://.../ws when TLS is enabled) for real-time catch-up and event streaming without an application-built replay-to-live handoff.

// 1. Authenticate immediately upon connection
{"type": "auth", "token": "sk-dev-0000000000000000000000"}

// 2. Subscribe to a topic with catch-up cursor
{"type": "subscribe", "topic": "my-channel", "cursor": 0}

// 3. Publish an event directly via WebSocket
{"type": "broadcast", "topic": "my-channel", "event_type": "agent.action", "payload": {"status": "ok"}}

The server streams ordered events and handles catch-up replay. To explore ready-made clients, visit the Python, Go, and TypeScript SDK guides.