# HTTP API

Every endpoint rungent serves on your origin, how each is authenticated, the AG-UI events a run streams, the interrupts and how to answer them, and the shapes of answers and errors.

rungent serves these paths on your own origin. An embedded runtime answers them in your process;
with `rungent serve`, your proxy forwards them. Every path under `/rungent/v0` speaks JSON, except the
two that stream events. `rungent/client` is a typed client of all of it.

## Endpoints

| Endpoint | Who calls it | Purpose |
|---|---|---|
| `POST /rungent/v0/threads` | user | Create a thread: `{title?}` → `201 {id, title, createdAt}`. |
| `GET /rungent/v0/threads?cursor=` | user | The user's threads, newest first, 20 a page, with `next`. |
| `GET /rungent/v0/threads/{id}` | user | A thread with its AG-UI `messages` and open `interrupts`. |
| `PATCH /rungent/v0/threads/{id}` | user | Rename: `{title}`, 1 to 200 characters. |
| `DELETE /rungent/v0/threads/{id}` | user | Cancel its run and delete it with everything it holds; `204`. |
| `POST /rungent/v0/threads/{id}/runs` | user | Start a run; the answer is its events (SSE). |
| `GET /rungent/v0/threads/{id}/events?after={seq}` | user | Replay events after `seq`, then follow live (SSE). |
| `POST /rungent/v0/runs/{id}/cancel` | user | Cancel a run: `202 {id, status: "cancelling"}`. |
| `PUT /rungent/v0/threads/{id}/messages/{messageId}/feedback` | user | Rate an assistant message: `{rating: "up" \| "down", comment?}`. |
| `GET /rungent/v0/feedback?since=&limit=&cursor=` | `rungent:admin` | The tenant's ratings, oldest first. |
| `GET /rungent/v0/info` | anyone | `{name}`: the assistant's name. |
| `GET /rungent/v0/catalog` | user | The operations this user can see, with their input schemas. |
| `GET /rungent/v0/search?q=&limit=&types=` | user | Federated search. |
| `GET /rungent/v0/settings` | user | The model chain in effect, without keys. |
| `PUT`, `DELETE /rungent/v0/settings` | `rungent:admin` | Replace or forget the saved model chain. |
| `POST /rungent/v0/tasks/{taskId}` | your API | Complete a deferred task. |
| `POST /rungent/v0/generate` | your API | One model completion for a job of yours. |
| `/mcp` | user | MCP over streamable HTTP. |
| `GET /skill.md`, `GET /llms.txt` | anyone | Documents for agents, generated from the caller's catalog. |
| `GET /.well-known/rungent-keys.json` | anyone | rungent's public signing keys, for inspection. |
| `GET /.well-known/oauth-protected-resource/mcp` | anyone | MCP's OAuth metadata, when authorization servers are configured. |

The protocol version is `rungent/0`; a minor release may still change it, and the
[changelog](changelog.md) lists every break.

## Authentication

A user's request carries the credential your app already uses: its `Authorization` header, its
`Cookie` header, or both. rungent forwards them to your identity operation to learn who the user is
([Acting as the user](acting-as-the-user.md#who-the-user-is)). A request with neither, or one your
identity operation refuses, answers `401 unauthorized`. A thread belongs to the
`(subject, tenant)` that created it; anyone else gets `404`.

Your API's own calls, `POST /rungent/v0/tasks/{taskId}` and `POST /rungent/v0/generate`, carry an
[`Rungent-Host-Assertion`](#host-assertions) instead.

rungent refuses requests another site could make for a user signed in with cookies. Every `POST`,
`PUT`, `PATCH` and `DELETE` with `Sec-Fetch-Site: cross-site` answers `403 cross_site`. Outside
`/mcp`, a body must be `application/json`, else `415 unsupported_media_type`.

## Errors

Every error outside an event stream is `{"error": {"code", "message"}}`:

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_request` | The body or a query parameter is invalid; the message says which. |
| 401 | `unauthorized` | No credential, or your identity operation refused it. |
| 401 | `rungent_assertion_invalid` | A task completion or host job without a valid `Rungent-Host-Assertion`. |
| 403 | `forbidden`, `cross_site` | Needs `rungent:admin`; or a cross-site write. |
| 404 | `not_found`, `session_not_found` | No such thread, message, run or task for this caller; an unknown MCP session. |
| 409 | `run_active`, `task_closed` | The thread already has a run in progress; the task was completed or cancelled. |
| 415 | `unsupported_media_type` | A body that is not `application/json`. |
| 422 | `invalid_output` | A host job's answer still does not fit its `schema` after one repair. |
| 502 | `host_unavailable` | rungent could not read your OpenAPI document. |
| 503 | `settings_unreadable`, `model_unavailable` | Settings sealed with a lost secret; no model could answer a host job. |
| 504 | `timeout` | A host job ran past the run timeout. |
| 500 | `internal` | Anything else. |

## Start a run

`POST /rungent/v0/threads/{id}/runs` takes AG-UI `RunAgentInput`. rungent reads three fields:

```json
{
  "messages": [{ "id": "m_1", "role": "user", "content": "Stop gpu-train-01" }],
  "context": [{ "description": "The page the user is on", "value": "/console/instance/vm-42" }],
  "resume": []
}
```

- **`messages`.** rungent owns the history: send the thread's messages or only the new one, and rungent
  appends those whose ids it has not seen. A changed earlier message fails the run with
  `history_conflict`. A user message's `content` is text, or AG-UI parts of type `text`, `image`
  and `document`, at most 10 images and documents.
- **`context`.** What the user is looking at, added to this run's prompt as information, never as
  instructions: at most 16 entries and 8000 characters. It is not stored.
- **`resume`.** The answers to the thread's open interrupts; see [Interrupts](#interrupts).

The answer is `text/event-stream`, ending after `RUN_FINISHED` or `RUN_ERROR`. A run outlives its
response: closing the stream does not stop it, so an approved write always finishes and is
recorded. Only a cancel stops a run.

An `image` or `document` part's `source` is a URL or inline `data`. A path or URL on your origin
is fetched from your API with the user's credential, up to 5 MB; another URL is passed to the
model provider; inline data may be up to 5 MB. Images go only to `vision` endpoints; a text-like
document is given to the model as text, up to 20 000 characters.

## Events

A run streams [AG-UI 1.0](https://docs.ag-ui.com) events. Each frame is an `id:` line with the
event's sequence number and a `data:` line with its JSON, and `: keepalive` comments come between
events. rungent's own data sits under `metadata.rungent`, or in `CUSTOM` events named `rungent.*`.

```text
id: 41
data: {"type":"TOOL_CALL_START","toolCallId":"call_1","toolCallName":"stop_vm","metadata":{"rungent":{"seq":41,"op":"stop_vm","title":"Stop server","effect":"update"}}}

id: 44
data: {"type":"RUN_FINISHED","threadId":"th_1","runId":"run_7","outcome":{"type":"interrupt","interrupts":[{"id":"int_3","reason":"rungent:approval",…}]},"metadata":{"rungent":{"seq":44}}}
```

| What happens | AG-UI events | What rungent fixes |
|---|---|---|
| A run starts, ends or fails | `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR` | `RUN_FINISHED.outcome.type` is `success`, `interrupt` or `cancelled`; its `usage` lists tokens per provider and model. `RUN_ERROR.code` is a [run error code](#run-error-codes). |
| One model step | `STEP_STARTED`, `STEP_FINISHED` | `stepName` is `model:1`, `model:2`, … |
| Assistant text | `TEXT_MESSAGE_START`, `_CONTENT`, `_END` | Deltas are coalesced to about 50 ms. Raw reasoning is never sent. |
| A tool call | `TOOL_CALL_START`, `_ARGS`, `_END`, `_RESULT` | `START` carries `{op, title, effect}`; the arguments arrive whole and redacted; `RESULT.metadata.rungent` is `{status, error?, deduplicated?}`. |
| Progress | `ACTIVITY_SNAPSHOT` | `activityType` is `rungent.progress`, `content` is `{message}`. |
| Anything else | `CUSTOM` | See [Custom events](#custom-events). |

A failed call's result is `{"error": {code, message, detail?}}`, where `detail` is your API's
error body, redacted and cut to 4 KB, so the model can correct the call from your fields. With
knowledge, a run that appends a user message starts with a `search` call before `model:1`.

### Run error codes

| `RUN_ERROR.code` | Meaning |
|---|---|
| `model_unavailable` | No endpoint of the model chain could answer. |
| `max_steps` | The run reached its step limit (16 by default). |
| `open_interrupts` | The thread has open interrupts that `resume` did not answer. |
| `history_conflict` | `messages` changed a message rungent already holds. |
| `invalid_interaction` | A resume entry is invalid: unknown or answered interrupt, a payload that does not fit its `responseSchema`, an `argsHash` that does not match, or a user resolving a task. |
| `internal` | Anything else, including a run past its time limit (600 s by default). |

### Tool error codes

These go back to the model, which explains them in its own words; a client does not show them as
errors.

| Code | Meaning |
|---|---|
| `invalid_arguments` | The arguments do not fit the input schema. An operation with a form opens its form instead. |
| `unresolved_reference` | A name matched no item, or several. |
| `repeated_call` | A read that already succeeded in this run, repeated. |
| `already_attempted` | An approved write of this operation already failed in this run. |
| `not_executed` | The user rejected or cancelled, the approval expired, or the call no longer fits the catalog. Nothing ran. |
| `credential_expired` | The user's credential expired mid-run, or the run has none (it resumes a task). |
| `timeout` | Your API did not answer within `timeoutSeconds`. |
| `http_{status}` | Your API answered this status (`http_403`), with its body as `detail`. |

## Interrupts

A run pauses by ending with `outcome: {type: "interrupt", interrupts: [...]}`. Every interrupt has
an `id`, a `reason`, a `message` to show, its `toolCallId`, rungent's data in `metadata.rungent`, and,
except tasks, a `responseSchema` for the answer.

| `reason` | When | `metadata.rungent` | The answer's `payload` |
|---|---|---|---|
| `rungent:approval` | Before a write | `{op, arguments, argsHash, impact}` | `{approved}` |
| `rungent:form` | Before an operation with a form | `{op, arguments, form, issues?}` | `{arguments}` |
| `rungent:input` | The model asks which thing or which action | `{form}` | `{answers}` |
| `rungent:task` | Your API runs the work later | `{taskId, op}` | none; your API completes it |

The next run answers every open interrupt in `resume`:

```json
{ "interruptId": "int_3", "status": "resolved", "payload": { "approved": true }, "metadata": { "rungent": { "argsHash": "q2…" } } }
```

`status` is `resolved` or `cancelled`; a cancelled entry needs no payload, and its call ends with
`not_executed`. A user who types a new message instead sends `cancelled` for each open interrupt
alongside it.

### Approval (`rungent:approval`)

`impact` is the card: `{title, target, effect, risk, costHint, changes}`, from the operation's
[confirmation](x-rungent.md#confirmation), with `changes` its `fields` as `label: value`. The answer
is `{approved: true | false}` with `metadata.rungent.argsHash` echoing the hash. rungent then runs the
frozen arguments, at most once. An approval expires 15 minutes after it is asked (`expiresAt`).

### Form (`rungent:form`)

```json
{
  "op": "create_vm",
  "arguments": { "name": "prod" },
  "form": { "prompt": "Create a server",
    "questions": [{ "id": "zone_id", "prompt": "Zone", "kind": "choice", "required": true, "options": [{ "id": "z1", "label": "Beijing A" }] }] },
  "issues": [{ "path": "zone_id", "message": "required" }]
}
```

`arguments` are what the form starts from; `form` is your generic form, for a client without the
product's own component; `issues` say why the last submission was refused. The answer is
`{arguments}`, the operation's **complete** arguments. A client showing the generic form builds
them with `answersToArguments` from `rungent/protocol`, which sets each answer at its
question's dotted path.

A form, here and in `rungent:input`, has a `prompt` and 1 to 24 `questions` with unique ids:

| Question | Keys |
|---|---|
| `text` | `id`, `prompt`, `kind: "text"`, `required`, optional `placeholder` and `default` |
| `choice` | `id`, `prompt`, `kind: "choice"`, `required`, `options` (at least one), optional `multiple`, `allowCustom` and `default` |
| option | `id`, `label`, optional `description` and `recommended` |

### Question (`rungent:input`)

The model's `request_input` tool asks which thing or which action the user means, as `{form}`. The
answer is `{answers: {questionId: answer}}`: a string for a `text` question,
`{selected: [optionIds], custom?}` for a `choice`.

### Task (`rungent:task`)

An operation that answers `202 {"rungentTask": "<id>"}` pauses the run and emits `rungent.task` with
`status: "running"`. Your API completes it with [`POST /rungent/v0/tasks/{taskId}`](#deferred-tasks);
the user may only answer it as `cancelled`.

## Custom events

| `name` | `value` |
|---|---|
| `rungent.ui.open` | `{path}`: show this product page, from `x-rungent.open` after success. |
| `rungent.citation` | `{messageId, citations: [{n, hit}]}`: each search hit the message cites as `[n]`. Hits carry no `content`. |
| `rungent.context` | `{usedTokens, budgetTokens, source}`: how full the model's context is. |
| `rungent.model.retry` | `{step, attempt, maxAttempts, reason, endpoint, fallback}`: a model attempt failed and is retried. |
| `rungent.message.discard` | `{messageId}`: drop the partial text of an attempt that will be retried. |
| `rungent.task` | `{taskId, status, message?}`: a task's progress. |

Clients skip custom events they do not know; a generic AG-UI client still shows text, tool calls
and interrupts correctly.

## Replay after a disconnect

`seq` increases by thread, across runs, and the SSE `id:` line is the same number. A client that
loses the stream reconnects with `GET /rungent/v0/threads/th_1/events?after=44`: rungent replays every
event after it, then follows the thread live. `Last-Event-ID` works too, so a browser
`EventSource` resumes on its own.

## Catalog and search

`GET /rungent/v0/catalog` answers `{operations: [{name, title, description, effect, approval,
surfaces, input}]}`, without role operations; `input` is the
[input schema](catalog.md#the-input-schema).

`GET /rungent/v0/search` takes `q` (required), `limit` (default 10, at most 50) and `types`
(comma-separated). It answers `{hits, failed}`: each hit names its `source` and carries no
`content`; each failed source is `{source, code}` with `timeout`, `http_<status>` or
`invalid_response`.

## Settings

`GET /rungent/v0/settings` answers `{models: {chain: [...]}}`, each entry with `hasApiKey` and never a
key; an entry from code shows as provider `custom`. `PUT` replaces the whole chain with entries of
the [model chain's fields](deploy.md#choose-models); an entry sent without `apiKey` keeps the
stored key of the entry with the same `id`. `DELETE` forgets the saved chain, so the configured one
applies again. Both need `rungent:admin` and answer as `GET` does.

## Deferred tasks

When the work of a `202` operation is done, your API completes the task:

```http
POST /rungent/v0/tasks/task_123
Content-Type: application/json
Rungent-Host-Assertion: <compact JWS>

{"status": "succeeded", "result": {"id": "vm-43"}}
```

`status` is `succeeded` or `failed`; `result` becomes the tool result, redacted as the operation
says. The assertion's `op` is the operation that deferred, and its `sub` and `ten` the thread
owner's. It answers `202 {"runId"}`: rungent starts a run that resumes the interrupt. That run has no
user credential, so a call it makes to your API fails with `credential_expired`.

## Host jobs

`POST /rungent/v0/generate` is one model completion for a job of yours, such as a weekly report's
summary, signed with a `Rungent-Host-Assertion` whose `op` is `generate`:

```json
{
  "instructions": "Write the weekly report's summary in two sentences.",
  "input": "Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).",
  "schema": { "type": "object", "properties": { "headline": { "type": "string" } }, "required": ["headline"] },
  "maxOutputTokens": 400
}
```

`input` is required (up to 200 000 characters). With `schema`, the answer is `{object}`, valid
against it; without, `{text}`. The call uses the model chain without tools or a thread; an answer
that does not fit `schema` goes back to the model once.

## Host assertions

`Rungent-Host-Assertion` has the shape of the assertion rungent sends you: an EdDSA compact JWS with
header `{"alg": "EdDSA", "kid", "typ": "rungent-call+jwt"}`, signed with a key rungent pins in
`hostKeys` (`RUNGENT_HOST_KEYS`).

| Claim | Value |
|---|---|
| `iss` | Your origin. |
| `aud` | rungent's own URL. |
| `sub`, `ten` | Whom the call is for. |
| `sid`, `rid`, `cid` | Ids of your choosing, for audit. |
| `op` | The deferred operation, or `generate`. |
| `htm`, `htu` | `POST`, and the origin of rungent's public URL followed by the path you post to. |
| `bsh` | base64url SHA-256 of the exact body. |
| `iat`, `exp`, `jti` | At most 60 seconds apart; each `jti` is accepted once. |

A JavaScript host signs with `signAssertion` from `rungent/delegation`. In other
languages, any Ed25519 JWS library makes the token.

## Documents and keys

`/skill.md` (`text/markdown`) and `/llms.txt` (`text/plain`) answer `200` with or without a
credential. With one, they list the caller's operations. Without one, they list the catalog your
API serves anonymously; if that answers `401` or `403`, they hold the guide and how to connect,
and rungent remembers that for 5 minutes. `/.well-known/rungent-keys.json` is
`{"keys": [{"kty": "OKP", "crv": "Ed25519", "x", "kid"}]}`. On `/mcp`, each tool carries its CLI
spelling in `_meta.rungent` (`{command, args, effect}`).
