> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/reference/http-api.md). # HTTP API > **Context** — The agent server's complete inbound HTTP surface for runtime version `0.8.1`. Conversation traffic is normally driven through the SDK ([Integrating the SDK](/agents/guides/integrating-the-sdk.md)); this page is the wire-level contract. The machine-readable OpenAPI spec for this surface is published per version — see [Versioning & compatibility](/agents/operations/versioning.md#machine-readable-artifacts). ## 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 ` (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](/agents/concepts/architecture.md#boot-sequence). ## Trigger an autonomous routine ``` POST /routines/{routine_id}/trigger Authorization: Bearer Content-Type: application/json ``` Runs the routine asynchronously; the typed result is delivered later to `callback_url` — see [Autonomous routines](/agents/concepts/autonomous-routines.md). ### 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` must pass the routine's `callback_url_allowlist` when one is set. **Response `202`** — run accepted: ```json { "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} : 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): ```json { "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 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](/agents/concepts/tools.md#injecting-context-as-a-tool-event). ### 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 | — | | | `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`**: ```json { "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 ``` 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](/agents/guides/integrating-the-sdk.md) for this surface; event wire shapes are in [Events & callbacks](/agents/reference/events-and-callbacks.md). The server rate-shapes aggressive event polling via an `x-polling-backoff` response header (seconds to wait) that well-behaved clients honour. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.interactive.ai/agents/reference/http-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.