HTTP API

The agent server's inbound HTTP surface: auth, health, autonomous trigger, webhooks, tool-event injection, routine graph, and the conversation API.

Context — The agent server's complete inbound HTTP surface for runtime version 0.8.14. Conversation traffic is normally driven through the SDK (Integrating the SDK); this page is the wire-level contract. The machine-readable OpenAPI spec for this surface is published per version — see Versioning & compatibility.

Authentication

Paths	Auth
/health/*, /health	none
/webhooks/{name}	HMAC signature over the raw body (per-webhook config)
/auth/login, /auth/logout	none (the login flow itself)
everything else	Authorization: Bearer <agent api key> (constant-time compared against the manifest's runtime.api_key), or the agent_auth cookie (below)

Failed bearer auth returns 401. Failed HMAC verification returns 401 with no detail; unknown webhook names return 404 indistinguishable from unconfigured ones.

Browser cookie login — for the built-in chat UI (GET /chat), where a browser can't attach an Authorization header to the UI's own requests: an unauthenticated browser navigation redirects to GET /auth/login; POST /auth/login validates the typed-in agent api key and sets an HttpOnly agent_auth cookie carrying the same key, which the browser replays on every same-origin call; POST /auth/logout clears it. Server-to-server integrations should keep using the bearer header.

Health

Method & path	Response
GET /health/live	always 200 {"status": "ok", "service": "agent-server"} — liveness
GET /health/ready	200 once configuration is applied, 503 {"status": ...} while booting — readiness
GET /health	alias of /health/ready

Readiness intentionally precedes boot-time routine evaluation — see the boot sequence.

Trigger an autonomous routine

POST /routines/{routine_id}/trigger
Authorization: Bearer <agent api key>
Content-Type: application/json

Runs the routine asynchronously; the typed result is delivered later to callback_url — see Autonomous routines.

Request body — TriggerRequest

Body of POST /routines/{routine_id}/trigger.

Field	Type	Required	Default	Description
input	dict[string, JsonValue]	no	—	Validated against the routine's input_schema.
callback_url	string	yes	—	URL that receives the AutonomousCallbackPayload when the run settles.
session_id	string	no	null	Reuse an existing session. If omitted an ephemeral session + customer are created and deleted after the callback settles.
idempotency_key	string	no	null	Replay-safe key — duplicates return the prior run.
metadata	dict[string, JsonValue]	no	—	Opaque caller metadata echoed back in the callback payload.

input must satisfy the routine's input_schema; callback_url's hostname must match an entry of the routine's callback_url_allowlist when one is set.

Response 202 — run accepted:

{
  "run_id": "run_9f8e7d6c5b4a3f2e1d0c9b8a",
  "routine_id": "kyc-decision",
  "status": "accepted",
  "session_id": "sess_abc123",
  "created_at": "2026-06-04T10:15:00+00:00"
}

Status	Meaning
202	Accepted; callback follows asynchronously.
400	Input failed input_schema validation (body carries error + path), or callback_url not allowed.
404	No autonomous routine with this id.
409	Duplicate idempotency_key — body echoes the prior run (run_id, status, session_id, created_at).
500	Session preparation or engine dispatch failed.
503	Server not ready.

Third-party webhook entry

POST /webhooks/{name}
<signature header>: <prefix><hex HMAC of raw body>
Content-Type: application/json

{name} is either a manifest-level webhook name (fan-out to one or more routines) or a routine id whose YAML declares autonomous.webhook. The raw JSON body becomes the run input. Webhook runs are fire-and-forget — no callback. Replays of an identical body dedupe to the existing run.

Response 200 (manifest-level fan-out):

{
  "webhook": "kyc-events",
  "matched": [
    "kyc-decision"
  ],
  "runs": [
    {
      "routine_id": "kyc-decision",
      "run_id": "run_0a1b2c3d4e5f60718293a4b5",
      "status": "accepted"
    }
  ]
}

Per-routine webhooks return the same 202 envelope as the trigger endpoint (a replayed body returns 200 with the existing run).

Status	Meaning
200 / 202	Dispatched (or deduped replay).
400	Body is not a JSON object.
401	Missing/invalid signature.
404	Unknown webhook name.
502	Routine matching failed — the provider should retry.
503	Server not ready.

Inject a tool event

POST /sessions/{session_id}/tool_events
Authorization: Bearer <agent api key>
Content-Type: application/json

Appends a synthetic tool result to a session's history — for supplying large external context (statements, history dumps) as if a tool had fetched it. Semantics: Tools.

Request body — ToolEventRequest

Body of POST /sessions/{session_id}/tool_events.

Field	Type	Required	Default	Description
tool_id	string	yes	—	Opaque tool identifier surfaced to the LLM prompt. Canonical form is 'service_name:tool_name' (single colon), e.g. 'injected:conversation_history'.
arguments	dict[string, JsonValue]	no	—	Tool call arguments — becomes the tool call's arguments field.
result	JsonValue	yes	—	Tool result payload — becomes the tool result's data.
result_metadata	dict[string, JsonValue]	no	—	Becomes the tool result's metadata (inside the tool_calls entry).
event_metadata	dict[string, JsonValue]	no	—	Becomes the event's top-level metadata.
idempotency_key	string	no	null	Optional key for safe retries. If an injected tool event with this key already exists in the session, returns it without creating a duplicate. Stored in the event metadata.
trigger_processing	boolean	no	false	If true, runs a response turn immediately after injection. WARNING: this cancels any turn currently processing for this session.

Response 200:

{
  "event_id": "evt_4f6a2b",
  "offset": 17,
  "creation_utc": "2026-06-04T10:15:00.412000+00:00",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Status	Meaning
200	Event created (or idempotent replay of an existing one).
404	Session not found.
503	Server not ready.

Routine graph

GET /journeys/{journey_id}/graph
Authorization: Bearer <agent api key>

Returns the full routine state machine — {"journey": {...}, "nodes": [...], "edges": [...]} — for dashboards and debugging UIs. The journeys path segment is legacy wire naming for routines; ids are the engine-assigned routine ids surfaced in traces. 404 for unknown ids, 503 while booting.

Conversation & customer API

The session/customer surface is consumed through the SDK, which owns its ergonomics (idempotent open, typed events, reconnecting streams). The routes it drives:

Surface	Routes
Sessions	create / read; GET /sessions/{id}/events (long-poll, min_offset-resumable) — the event stream; POST /sessions/{id}/events — post customer/system messages
Customers	register / read / update; customer variables and metadata

Use Integrating the SDK for this surface; event wire shapes are in Events & callbacks. The server rate-shapes aggressive event polling via an x-polling-backoff response header (seconds to wait) that well-behaved clients honour.