> 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

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 `1.4.0`. Conversation traffic is normally driven through the SDK ([Integrating the SDK](https://docs.interactive.ai/agents/guides/integrating-the-sdk.md)); this page is the wire-level contract.

## 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` after configuration and graph publication, `503 {"status": ...}` while booting — readiness |
| `GET /health`       | alias of `/health/ready`                                                                         |

Readiness waits for boot-time routine evaluation and graph publication — see the [boot sequence](https://docs.interactive.ai/agents/concepts/architecture.md#boot-sequence).

## Maintenance garbage collection

`POST /maintenance/gc` (no request body) uses the existing agent authentication. Pause and drain all work and stop all other replicas before calling. The endpoint does not verify those maintenance conditions or provide a separate operator role.

`200`: `{"deleted": {"routines": 2, "glossary": 3}, "errors": {}}`. Counts cover completed store sweeps. `500` returns the same shape with failed stores in `errors`; those stores may have partially deleted rows and have no count. `409` means storage is not PostgreSQL; `503` means the agent is not ready or its deployment inventory is unavailable.

The sweep holds the initialization lock and retains current IDs and rows created since this boot. Sessions, customers, variable values and evaluation caches are untouched. See [maintenance procedures](https://docs.interactive.ai/agents/operations/routine-graph-lifecycle.md#explicit-cleanup).

## 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](https://docs.interactive.ai/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`'s hostname must match an entry of 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}
<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):

```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 <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](https://docs.interactive.ai/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       | —       | 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`**:

```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.                                        |

## Try a formula

```
POST /formulas/evaluate
Authorization: Bearer <agent api key>
Content-Type: application/json
```

Works a formula out against sample data, with the evaluator a routine runs it with, so an author can check what a formula gives before putting it in a routine. It reads only the request (no session, variable or tool), runs no model call, and logs neither the data nor the result. See [Authoring routines](https://docs.interactive.ai/agents/guides/authoring-routines.md#trying-a-formula).

### Request body — `FormulaEvaluateRequest`

Body of `POST /formulas/evaluate`.

| Field       | Type                  | Required | Default | Description                                                                                                                                              |
| ----------- | --------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formula`   | string                | yes      | —       | The formula, as a routine writes it.                                                                                                                     |
| `functions` | dict\[string, string] | no       | —       | The routine's named functions the formula calls, as its `functions:` block writes them: `name(input, …)` to formula.                                     |
| `now`       | string                | no       | `null`  | The clock `today()` and `now()` read, so a date formula gives the same value on every call. Read in the agent's timezone; the current time when omitted. |
| `cases`     | list\[FormulaCase]    | yes      | —       | The sets of sample data to work the formula out against.                                                                                                 |

### A case — `FormulaCase`

One set of sample data a formula is worked out against.

| Field    | Type                     | Required | Default | Description                                                                                                                                                                                                                        |
| -------- | ------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`   | dict\[string, JsonValue] | no       | —       | What the formula reads, named as the formula names it: `input`, `variable`, `step` (`{step id: {ok, output, …}}`) and `message`; any other key is a value by that name, as a node's declared `input` or a value computed above it. |
| `expect` | JsonValue                | no       | `null`  | The value the formula should give. When present, the case's result says whether it did (`matches_expect`).                                                                                                                         |

**Request**:

```json
{
  "formula": "is_vip(step.get_player.output) && count(tickets) > 1",
  "functions": {
    "is_vip(player)": "lower(player.tier) == \"gold\" && player.spend > 1000"
  },
  "cases": [
    {
      "data": {
        "step": {
          "get_player": {
            "ok": true,
            "output": {
              "tier": "Gold",
              "spend": 1500
            }
          }
        },
        "tickets": [
          {
            "id": 1
          },
          {
            "id": 2
          }
        ]
      },
      "expect": true
    },
    {
      "data": {
        "step": {
          "get_player": {
            "ok": true,
            "output": {
              "tier": "Gold"
            }
          }
        },
        "tickets": []
      }
    }
  ]
}
```

**Response `200`** — one result per case, in order:

```json
{
  "problems": [],
  "results": [
    {
      "ok": true,
      "value": true,
      "matches_expect": true,
      "reads": {
        "step.get_player.output.tier": "Gold",
        "step.get_player.output.spend": 1500,
        "tickets": [
          {
            "id": 1
          },
          {
            "id": 2
          }
        ]
      },
      "missing": []
    },
    {
      "ok": true,
      "value": false,
      "reads": {
        "step.get_player.output.tier": "Gold",
        "step.get_player.output.spend": null,
        "tickets": []
      },
      "missing": [
        "step.get_player.output.spend: path segment 'spend' is missing"
      ]
    }
  ]
}
```

| Field                      | Meaning                                                                                                                                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `problems`                 | What a routine holding the formula would be refused for on save (it can't be read, an unknown function, a wrong number of inputs, a name no case gives, over 20,000 characters or 500 function calls once its functions are written out). When there are any, nothing is run and `results` is empty. |
| `results[].ok`             | `true` with `value`, or `false` with `error`: why the formula failed, in the words the step's trace would show.                                                                                                                                                                                      |
| `results[].matches_expect` | Whether `value` equals the case's `expect`, compared as formulas compare (`2` is `2.0`, `"10"` is not `10`). Only when the case sets `expect`; `false` for a failed formula.                                                                                                                         |
| `results[].reads`          | Each value the formula read from the case's data.                                                                                                                                                                                                                                                    |
| `results[].missing`        | Each read that found nothing, which the formula read as `null`.                                                                                                                                                                                                                                      |

| Status | Meaning                                                                                   |
| ------ | ----------------------------------------------------------------------------------------- |
| `200`  | The formula was checked, and run when it has no `problems`.                               |
| `413`  | Body over 1 MB.                                                                           |
| `422`  | Malformed body: no formula, a formula over 10000 characters, or not 1 to 50 cases.        |
| `429`  | 4 formulas are already being worked out on this agent; retry after `Retry-After` seconds. |
| `504`  | The formula took longer than 10 s to work out.                                            |

## Chat attachments

```
GET  /attachments/config
POST /attachments                                   (multipart, field `file`)
POST /sessions/{session_id}/attachments             {"attachments": [{"file_id", "version_id"}]}
GET  /attachments/{file_id}/versions/{version_id}
Authorization: Bearer <agent api key>
```

Used by the `/chat` UI. `config` returns `{"enabled": true, "max_bytes_by_extension": {".pdf": …}}` when a policy or routine uses a FileStore reader (`read_excel`, `read_pdf`, `read_docx`, `read_text`, `read_image`) served by a FileStore MCP; otherwise every route but `config` answers `409`. `max_bytes_by_extension` is the cap for each accepted extension. `POST /attachments` stores one PDF, XLSX, DOCX, CSV, TXT, Markdown, JSON, PNG, JPEG or WebP file in the project's Files and returns `{file_id, version_id, name, content_type, size}`. Attaching adds one custom event, `{"attachments": [{file_id, version_id, name, content_type, size}]}`, to the session; the agent reads the files with those ids through FileStore. Only files this agent uploaded can be attached. The versions route serves images only, for previews. Errors are `{"detail": "..."}`; the Files API's `400`, `403`, `409`, `413` and `429` pass through. While attachments are on, custom events carrying `attachments` are refused on `POST /sessions/{session_id}/events`.

## 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.

## Autonomous runs

The endpoints behind the agent UI's runs view. With a Postgres `database` they cover every replica's runs for `runtime.run_retention_days` (default 30); without one, only this pod's runs since it started. Shapes are in `agent_contracts.runs`.

| Method & path                        | Returns                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /runs`                          | `RunPage`: runs newest first. Filters: `routine_id`, `status` (repeat it for several, e.g. `status=running&status=accepted`), `source` (`api`, `webhook`, `schedule`, `replay`), `error_code`, `since`, `until`; `limit` (1–200, default 50) and `cursor` (the previous page's `next_cursor`; `400` if malformed).                                                 |
| `GET /runs/{run_id}`                 | `Run`: trigger, input, output or error, callback status and each attempt, iterations, iteration cap, token use. `404` for unknown ids.                                                                                                                                                                                                                             |
| `GET /runs/{run_id}/steps`           | `RunStepPage`: the run's steps in order (`iteration`, `node`, `policy`, `tool` with arguments and result, `route` for a step chosen by a rule or a single transition, `parallel` for a parallel step's members), plus the run's status. `after=<seq>` returns only later steps.                                                                                    |
| `GET /routines`                      | `RoutineInfo[]`: the routines the agent runs, with each node's `title`, `description` and transitions. `autonomous=true` lists only autonomous routines, each with its `input_schema`, `output_schema` and `timeout_seconds`.                                                                                                                                      |
| `GET /runs/stats`                    | `RunStats` for `range=1h`, `24h` (default) or `7d`: runs, succeeded, failed, dead-lettered callbacks, p50/p95 duration, runs over time, failures by `error_code`, and counts by source and routine.                                                                                                                                                                |
| `GET /schedules`                     | `ScheduleInfo[]`: each manifest schedule's next tick and its latest tick's status, attempts and error.                                                                                                                                                                                                                                                             |
| `POST /runs`                         | Start a run from the UI (`NewRunRequest`: `routine_id`, `input`, optional `idempotency_key` and `callback_url`). Without a `callback_url` the run records `callback_status: skipped`. Answers like the trigger endpoint: `202` with the run's receipt, `400` for an input that fails the routine's `input_schema`, `409` with the original run for a repeated key. |
| `POST /runs/{run_id}/rerun`          | Start a new run of the same routine, with the original input or the `input` given (`RerunRequest`). The new run's metadata carries `rerun_of`. It never reuses the original callback URL.                                                                                                                                                                          |
| `POST /runs/{run_id}/callback/retry` | Deliver a `dead_lettered` callback again, once; returns the `Run` with the new attempt appended. `409` when the callback is not dead-lettered.                                                                                                                                                                                                                     |

`503` while booting.

## Scenarios

The endpoints behind the agent UI's "New scenario", in Chats and in Runs. They set up a replay scenario's world (its customer, its context variables, and a session whose tool calls are answered from its fixtures) and leave the driving to a person. Scenarios are read from the platform's datasets, so they need the platform connection. Shapes are in `agent_contracts.scenarios`.

| Method & path                               | Returns                                                                                                                                                                                                                                                       |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /scenarios/datasets`                   | `ScenarioDataset[]`: the project's datasets.                                                                                                                                                                                                                  |
| `GET /scenarios?dataset=`                   | `ScenarioList`: the dataset's runnable scenarios, chat (`conversation`) and `automation`, with each one's script, trigger input, fixture tools and expectations; items that are not scenarios are listed under `skipped`.                                     |
| `POST /scenarios/start`                     | `StartedScenario` (`201`) for `{dataset, scenario}`: a chat scenario opens a session; an automation scenario also starts its routine's run, with no callback. `400` for an invalid scenario or a routine this agent does not run.                             |
| `GET /sessions/{session_id}/scenario-check` | `ScenarioCheck`: what the session did so far against the scenario's expectations (tools, routine steps, routines, policies and, for a run, the output), with the checks a replay uses and without its judge. `404` for a session not started from a scenario. |

## 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](https://docs.interactive.ai/agents/guides/integrating-the-sdk.md) for this surface; event wire shapes are in [Events & callbacks](https://docs.interactive.ai/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/agents/reference/http-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
