---
title: Harness server API
description: "Every operation of venom serve's HTTP API (66 operations), with parameters, bodies, responses, schemas and a curl line each."
section: api
order: 20
audience: [builder, operator, agent]
sources: [packages/harness-server/openapi.yaml]
---
Generated from `packages/harness-server/openapi.yaml` (OpenAPI 3.1.0, version 0.1.0), the source of truth for `venom serve`. The server's own copy is at `GET /v1/openapi.yaml`. Default address: `http://127.0.0.1:8790`.

## Overview

Harness sessions over HTTP with Server-Sent Events, so any language can drive `@venom/harness`.
This file is the source of truth for the HTTP surface: `test/openapi.test.ts` fails when a route
in `src/routes.ts` is missing here or the other way round.

Every route except `GET /v1/health`, `GET /v1/openapi.yaml`, `POST /v1/auth/proof`, the phone
inbox page `GET /v1/mobile` and its pairing `POST /v1/mobile/session` needs
`Authorization: Bearer $VENOM_SERVER_TOKEN`; the other `/v1/mobile/*` routes also take a paired
phone's cookie (`mobileCookie`). Operations marked `x-venom-browser: true` serve that page and
have no method in the clients. A client that did not start the server itself can
ask `POST /v1/auth/proof` first, without the token, to learn the server holds it. On a loopback bind, every request (public routes
too) must carry a loopback `Host` (`localhost`, `*.localhost`, 127.0.0.0/8, `[::1]`,
`host.docker.internal`); any other is answered 403 `host_not_allowed` (DNS-rebinding defence).

The server caps open connections (`--max-connections`, default the larger of 64 and 4 x the
session limit; event streams count). A request on a connection past the cap is answered 503
`too_many_connections` with `Connection: close` and `Retry-After: 1`, on any route, before
the Host check and auth.

Commands and event names follow pi's RPC mode (`prompt`, `steer`, `follow_up`, `abort`; the
JSON event stream's `agent_start`, `message_update`, `tool_execution_*`, `agent_settled`, ...),
so a client written against pi's RPC docs reads the same events here.

A permission "ask" becomes an `approval_request` event with an `approvalId`. Answer it with
`POST /v1/sessions/{sessionId}/approvals/{approvalId}` before `expiresAt`; when nobody answers,
the call is denied.

The model's `ask_user` tool becomes a `question_request` event with a `questionId`. Answer it with
`POST /v1/sessions/{sessionId}/questions/{questionId}` before `expiresAt`; when nobody answers,
the model is told to decide itself and state its assumption.

## Operations

66 operations.

| Method | Path | Summary |
|---|---|---|
| GET | [`/v1/health`](#op-getHealth) | Liveness and capacity. No auth. |
| GET | [`/v1/openapi.yaml`](#op-getOpenApi) | This document. No auth. |
| POST | [`/v1/auth/proof`](#op-proveServer) | The server proves it holds the token, before a client sends it. No auth. Added 2026-10. |
| GET | [`/v1/sessions`](#op-listSessions) | List open sessions. |
| POST | [`/v1/sessions`](#op-createSession) | Create a harness session in a directory under one of the server's allowed roots. |
| GET | [`/v1/saved-sessions`](#op-listSavedSessions) | Sessions saved with `persist`, newest first, that a new session can resume. Added 2026-10. |
| GET | [`/v1/projects`](#op-listProjects) | The folders a session can open in, each with its git branch. Added 2026-11. |
| GET | [`/v1/workflows`](#op-listWorkflows) | The workflow scripts of a workspace, by name. Added 2026-10. |
| GET | [`/v1/inbox`](#op-listInbox) | The open inbox items, most urgent first. Added 2026-10. |
| GET | [`/v1/inbox/{id}`](#op-getInboxItem) | One open inbox item. Added 2026-10. |
| POST | [`/v1/inbox/{id}/resolve`](#op-resolveInboxItem) | Answer an inbox item. Added 2026-10. |
| GET | [`/v1/ide`](#op-getIdePage) | The browser IDE page. No auth. Added 2026-10. |
| GET | [`/v1/mobile`](#op-getMobilePage) | The phone approval inbox page. No auth. Added 2026-10. |
| POST | [`/v1/mobile/pairings`](#op-createPairing) | A one-time code that pairs a phone with the inbox page. Added 2026-10. |
| POST | [`/v1/mobile/session`](#op-pairMobile) | Trade a pairing code for the phone's cookie. No auth (the code is the credential). Added 2026-10. |
| DELETE | [`/v1/mobile/session`](#op-unpairMobile) | Unpair this phone (forget its cookie). Added 2026-10. |
| GET | [`/v1/mobile/inbox`](#op-getMobileInbox) | What the phone inbox shows. Added 2026-10. |
| GET | [`/v1/mobile/events`](#op-streamMobileEvents) | Server-Sent Events of the phone inbox. Added 2026-10. |
| POST | [`/v1/mobile/answer`](#op-answerMobile) | Answer an inbox item or a served session's approval from the phone. Added 2026-10. |
| GET | [`/v1/evidence`](#op-getEvidence) | The evidence bundle of a repository's change. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}`](#op-getSession) | Session state. |
| DELETE | [`/v1/sessions/{sessionId}`](#op-closeSession) | Close a session. |
| POST | [`/v1/sessions/import`](#op-importSession) | Take over a session handed off from another machine (ADR 0024). Added 2026-10. |
| POST | [`/v1/sessions/{sessionId}/handoff`](#op-handoff) | Hand a persisted session to another machine (ADR 0024). Added 2026-10. |
| POST | [`/v1/sessions/{sessionId}/prompt`](#op-prompt) | Send a prompt (pi's `prompt` command). |
| POST | [`/v1/sessions/{sessionId}/steer`](#op-steer) | Queue a steering message, delivered after the current turn's tool calls (pi's `steer`). |
| POST | [`/v1/sessions/{sessionId}/follow_up`](#op-followUp) | Queue a follow-up, delivered when the agent would otherwise stop (pi's `follow_up`). |
| POST | [`/v1/sessions/{sessionId}/abort`](#op-abort) | Abort the running turn and wait until the session is idle (pi's `abort`). |
| PUT | [`/v1/sessions/{sessionId}/mode`](#op-setMode) | Set the permission mode. Emits a `mode` event. |
| POST | [`/v1/sessions/{sessionId}/agents/{pid}/model`](#op-switchAgentModel) | Switch one agent's model (ADR 0009 §8). |
| GET | [`/v1/sessions/{sessionId}/events`](#op-streamEvents) | Server-Sent Events for one session. |
| GET | [`/v1/sessions/{sessionId}/approvals`](#op-listApprovals) | Pending approval requests (the same objects as the `approval_request` events). |
| POST | [`/v1/sessions/{sessionId}/approvals/{approvalId}`](#op-decideApproval) | Answer a pending approval request. |
| GET | [`/v1/sessions/{sessionId}/questions`](#op-listQuestions) | Pending `ask_user` questions (the same objects as the `question_request` events). Added 2026-10. |
| POST | [`/v1/sessions/{sessionId}/questions/{questionId}`](#op-answerQuestion) | Answer a pending `ask_user` question. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}/checkpoints`](#op-listCheckpoints) | The session's turn checkpoints (file snapshots), oldest first. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}/changes`](#op-getChanges) | Each file one turn changed, with its text before and after. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}/files`](#op-listFiles) | One directory of the session's workspace. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}/file`](#op-readFile) | A text file of the session's workspace. Added 2026-10. |
| PUT | [`/v1/sessions/{sessionId}/file`](#op-writeFile) | Write a text file of the session's workspace. Added 2026-10. |
| DELETE | [`/v1/sessions/{sessionId}/file`](#op-deleteFile) | Delete a file of the session's workspace. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}/transcript`](#op-getTranscript) | The session's conversation so far, as text. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}/agents`](#op-listAgents) | The session's agent processes (`ps`), with ages and rates. Added 2026-10. |
| GET | [`/v1/sessions/{sessionId}/agents/{pid}`](#op-getAgent) | One agent process (lifetime rates). Added 2026-10. |
| POST | [`/v1/sessions/{sessionId}/agents/{pid}/signal`](#op-signalAgent) | Send a signal to an agent process. Added 2026-10. |
| GET | [`/v1/board`](#op-getBoard) | The agent factory's health, the issue board plus the merge gate. Added 2026-10. |
| GET | [`/v1/gears`](#op-listGears) | The gears the server's venom.yaml offers, for an editor's gear switcher. Added 2026-10. |
| GET | [`/v1/schedules`](#op-listSchedules) | The scheduled jobs (venom.yaml `schedules:`) with their next and last run. Added 2026-10. |
| GET | [`/v1/schedules/runs`](#op-listScheduleRuns) | Runs of scheduled jobs, newest first. Added 2026-10. |
| POST | [`/v1/schedules/{name}/run`](#op-runSchedule) | Start a job now, outside its schedule. Added 2026-10. |
| GET | [`/v1/schedules/runs/{runId}/output`](#op-getScheduleRunOutput) | One file a browser task's run produced. Added 2026-10. |
| GET | [`/v1/calls`](#op-listCalls) | Voice calls, live and stored, newest first. Added 2026-11. |
| POST | [`/v1/calls`](#op-createCall) | Start a call. Added 2026-11. |
| GET | [`/v1/calls/{callId}`](#op-getCall) | One call with its compliance events, handoff and per-turn metrics. Added 2026-11. |
| GET | [`/v1/calls/{callId}/events`](#op-streamCallEvents) | The call's events as SSE. Added 2026-11. |
| GET | [`/v1/calls/{callId}/transcript`](#op-getCallTranscript) | Caller finals and the agent's heard text. Added 2026-11. |
| GET | [`/v1/calls/{callId}/recording`](#op-getCallRecording) | The call's recording, stereo PCM16 8 kHz WAV (caller left, agent right). Added 2026-11. |
| POST | [`/v1/calls/{callId}/hangup`](#op-hangupCall) | Hang up a live call. Added 2026-11. |
| POST | [`/v1/calls/{callId}/transfer`](#op-transferCall) | A supervisor's handoff of a live call to the agent's handoff target. Added 2026-11. |
| GET | [`/v1/calls/{callId}/media`](#op-connectCallMedia) | The browser test line's media WebSocket. Ticket-authenticated. Added 2026-11. |
| GET | [`/v1/voice/agents`](#op-listVoiceAgents) | The configured voice agents. Added 2026-11. |
| POST | [`/v1/voice/twilio/incoming`](#op-twilioIncoming) | Twilio's voice webhook. Public; checked by `X-Twilio-Signature`. Added 2026-11. |
| POST | [`/v1/voice/twilio/status`](#op-twilioStatus) | Twilio's call status callback (answering-machine results). Public; signature-checked. Added 2026-11. |
| GET | [`/v1/voice/twilio/whisper/{token}`](#op-twilioWhisper) | TwiML that plays a warm transfer's whisper to the target. Public; single-use token, 2 min. Added 2026-11. |
| GET | [`/v1/voice/twilio/media`](#op-connectTwilioMedia) | Twilio Media Streams WebSocket. Public; single-use ticket from the TwiML. Added 2026-11. |
| GET | [`/v1/voice/clips/{clip}`](#op-getVoiceClip) | A whisper clip as WAV (`<token>.wav`). Public; single-use token, 2 min. Added 2026-11. |

## /v1/health {#group-health}

### Liveness and capacity. No auth. {#op-getHealth}

`GET /v1/health` · operationId `getHealth`

No authentication.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Server is up. | `application/json` [Health](#schema-Health) |

```bash
curl 'http://127.0.0.1:8790/v1/health'
```

## /v1/openapi.yaml {#group-openapiyaml}

### This document. No auth. {#op-getOpenApi}

`GET /v1/openapi.yaml` · operationId `getOpenApi`

No authentication.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The OpenAPI document. | `application/yaml` string |

```bash
curl 'http://127.0.0.1:8790/v1/openapi.yaml'
```

## /v1/auth {#group-auth}

### The server proves it holds the token, before a client sends it. No auth. Added 2026-10. {#op-proveServer}

`POST /v1/auth/proof` · operationId `proveServer`

No authentication.

A client that connects to a configured URL can't tell the real `venom serve` from another
program listening there, and its first authenticated request would hand that program the
token. So it first sends a fresh random `nonce` here, without the token, and the server
answers `proof` = lowercase hex HMAC-SHA256, keyed with the token (UTF-8), of
`"venom-serve-proof-v1\n" + nonce + "\n" + port`, where `port` is the local port the request
arrived on (also returned). The client computes the same with its token and sends nothing
else unless they match. For a loopback URL it also requires `port` to be the URL's port: a
fake server on one port could otherwise relay the nonce to a real server on another. Behind
a TLS proxy the port differs and TLS identifies the server, so a client checks the HMAC over
the returned port only. The Host check still applies.

**Request body** (required)

`application/json`: [AuthProofRequest](#schema-AuthProofRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The proof. | `application/json` [AuthProof](#schema-AuthProof) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST 'http://127.0.0.1:8790/v1/auth/proof' \
  -H 'Content-Type: application/json' -d '{...}'
```

## /v1/sessions {#group-sessions}

### List open sessions. {#op-listSessions}

`GET /v1/sessions` · operationId `listSessions`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Open sessions. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions'
```

### Create a harness session in a directory under one of the server's allowed roots. {#op-createSession}

`POST /v1/sessions` · operationId `createSession`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Request body** (required)

`application/json`: [CreateSessionRequest](#schema-CreateSessionRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 201 | Session created. | `application/json` [SessionState](#schema-SessionState) |
| 400 | A malformed body (`bad_request`), or a `model` the session's provider doesn't serve (`unknown_model`, added 2026-11; the message names the ones it does): the session is not created, rather than left on a model of pi's own that fails at the first prompt. | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | `cwd` is not inside an allowed root (`root_not_allowed`), or the organisation policy forbids the requested `mode` or `sandbox: false` (`policy_forbidden`, added 2026-10) or pins the orchestrator while the body asks for `cloudInference` (`policy_forbidden`, added 2026-11), or the client asked for `mode: sudo` and the server was not started with `--allow-sudo` (`sudo_forbidden`, added 2026-10). An organisation policy file that is invalid, or whose audit log can't be written, is 500 `policy_error` (added 2026-10). | `application/json` [Error](#schema-Error) |
| 404 | `resume` names no saved session of this workspace (`saved_session_not_found`). | `application/json` [Error](#schema-Error) |
| 409 | `resume` names a saved session that is already open on this server (`saved_session_open`). | `application/json` [Error](#schema-Error) |
| 429 | The session limit is reached (`too_many_sessions`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Session state. {#op-getSession}

`GET /v1/sessions/{sessionId}` · operationId `getSession`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Session state. | `application/json` [SessionState](#schema-SessionState) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>'
```

### Close a session. {#op-closeSession}

`DELETE /v1/sessions/{sessionId}` · operationId `closeSession`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Aborts any running turn (pi kills the running command's process group), denies pending
approvals, disposes the pi session and stops the harness's egress proxy. Event streams end
with a `session_closed` event.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Closed. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X DELETE -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>'
```

### Take over a session handed off from another machine (ADR 0024). Added 2026-10. {#op-importSession}

`POST /v1/sessions/import` · operationId `importSession`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

The body is the bundle `POST /v1/sessions/{sessionId}/handoff` returned, as
`application/octet-stream` (at most the server's `maxHandoffBytes`, 1 GiB by default). The
checksums are verified, the session unpacked into this server's agent dir and venom home,
its working-tree edits restored over `cwd` (which must be at the same commit and clean),
and it opens as a live persisted session holding the lease at the bundle's epoch. A bundle
whose epoch is not ahead of a copy already here is refused (409 `import_failed`) unless
`force=1` (an operator reclaim). Trust, permissions and the audit log do not move.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cwd` | query | string |  | The workspace to restore into (inside a root). Optional when the server has one root. |
| `force` | query | `1` |  | `1` replaces a copy of the session already here, at the next lease epoch. |

**Request body** (required)

`application/octet-stream`: string (binary)

**Responses**

| Status | Description | Body |
|---|---|---|
| 201 | The session, open and idle. | `application/json` [SessionState](#schema-SessionState) |
| 400 | Not a bundle, a failed checksum, a different commit, a dirty workspace (`import_failed`), or a bad `cwd` (`bad_request`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | `cwd` is not inside an allowed root (`root_not_allowed`). | `application/json` [Error](#schema-Error) |
| 409 | A stale bundle: this machine already has the session at an equal or newer lease epoch (`import_failed`). | `application/json` [Error](#schema-Error) |
| 413 | The bundle is larger than the server accepts (`body_too_large`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/import' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Hand a persisted session to another machine (ADR 0024). Added 2026-10. {#op-handoff}

`POST /v1/sessions/{sessionId}/handoff` · operationId `handoff`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Stops taking writes, waits for a running turn to end (up to the server's `handoffWaitMs`,
30 s by default), packs the session (transcript, spill files, blobs, the checkpoint
history and the working tree's uncommitted state) and streams the bundle back. The source
session stays open but read-only: its lease is now in transit at the next epoch, and every
prompt, steer and follow-up answers 409 `lease_lost`. The bundle can hold secrets that were
in tool output; move it over TLS and delete it after the import.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The bundle. `x-venom-session` and `x-venom-epoch` name the session and the epoch it moves to. | `application/octet-stream` string (binary) |
| 400 | The session was not created with `persist` (`not_persisted`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |
| 409 | A turn is still running past the wait (`busy`), the session is already handed off or another machine holds its lease (`lease_lost`), or the export failed (`handoff_failed`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/handoff'
```

### Send a prompt (pi's `prompt` command). {#op-prompt}

`POST /v1/sessions/{sessionId}/prompt` · operationId `prompt`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Answers once pi has accepted the prompt; the run continues in the background and streams
events. When the prompt that started a run finishes, a `prompt_end` event carries the final
assistant text (or the error). `truncated: true` on it (added 2026-11) means that final reply was
still cut off at the output-token limit after venom's retries, so `text` is partial. While a run is active, `streamingBehavior` must be `steer`
or `followUp`, otherwise the answer is 409 `busy`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Request body** (required)

`application/json`: [PromptRequest](#schema-PromptRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 202 | Accepted. | `application/json` [PromptAccepted](#schema-PromptAccepted) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |
| 409 | A run is active and no `streamingBehavior` was given (`busy`), or the session's lease is another machine's or it was handed off (`lease_lost`, added 2026-10: the session is read-only here). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/prompt' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Queue a steering message, delivered after the current turn's tool calls (pi's `steer`). {#op-steer}

`POST /v1/sessions/{sessionId}/steer` · operationId `steer`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Request body** (required)

`application/json`: [MessageRequest](#schema-MessageRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Queued or handled. | `application/json` [QueuedResponse](#schema-QueuedResponse) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/steer' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Queue a follow-up, delivered when the agent would otherwise stop (pi's `follow_up`). {#op-followUp}

`POST /v1/sessions/{sessionId}/follow_up` · operationId `followUp`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Request body** (required)

`application/json`: [MessageRequest](#schema-MessageRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Queued or handled. | `application/json` [QueuedResponse](#schema-QueuedResponse) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/follow_up' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Abort the running turn and wait until the session is idle (pi's `abort`). {#op-abort}

`POST /v1/sessions/{sessionId}/abort` · operationId `abort`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Idle. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/abort'
```

### Set the permission mode. Emits a `mode` event. {#op-setMode}

`PUT /v1/sessions/{sessionId}/mode` · operationId `setMode`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

A pending approval of the main agent that only the policy asked for (no hook, no supply-chain check) and that the new mode allows is settled at once as `allow-once`, with `approval_resolved` `by: mode` (added 2026-11).

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Request body** (required)

`application/json`: object

| Field | Type | Required | Description |
|---|---|---|---|
| `mode` | [PermissionMode](#schema-PermissionMode) | yes | `sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Mode set. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | The organisation policy does not allow this mode (`policy_forbidden`, added 2026-10), or the client asked for `sudo` and the server was not started with `--allow-sudo` (`sudo_forbidden`, added 2026-10). The mode is unchanged. | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X PUT -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/mode' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Switch one agent's model (ADR 0009 §8). {#op-switchAgentModel}

`POST /v1/sessions/{sessionId}/agents/{pid}/model` · operationId `switchAgentModel`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

The main agent switches at once when no run is active (`applied: "now"`); otherwise, and for
a subagent, at its next turn boundary (`applied: "turn-boundary"`), before its next model
request. The new model has no cached copy of the session's prompt, so the next request pays
for the whole context once (`cacheLost: true`); messages already sent are never rewritten.
A context over the new model's compaction trigger is compacted first. A `notice` event says
so when the switch takes effect. Added 2026-10.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `pid` | path | integer | yes | The agent's pid (`ProcInfo.pid`; the main agent is 1). |

**Request body** (required)

`application/json`: [SwitchModelRequest](#schema-SwitchModelRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The switch is scheduled, or done when `applied` is `now`. | `application/json` [SwitchModelResult](#schema-SwitchModelResult) |
| 400 | A malformed body or pid (`bad_request`), or a model the session's provider doesn't list (`unknown_model`; the message names the available ones). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | The organisation policy pins the orchestrator (`orchestrator.baseUrl`) and the model belongs to another provider (`policy_forbidden`, added 2026-10). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`), or no live agent with that pid in it (`agent_not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/agents/<pid>/model' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Server-Sent Events for one session. {#op-streamEvents}

`GET /v1/sessions/{sessionId}/events` · operationId `streamEvents`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Each event is `id: <seq>`, `event: <type>`, `data: <Event JSON>`. The server keeps the last
events of each session (2000 by default), so a client that reconnects with `Last-Event-ID`
(or `?after=<seq>`) gets what it missed; when the gap is older than the buffer, the replay
starts with an `events_dropped` event. `: ping` comments are sent every 15 s. The stream
ends after `session_closed`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `after` | query | integer |  | Replay events with `seq` greater than this. `Last-Event-ID` wins when both are set. |
| `Last-Event-ID` | header | string |  |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The event stream. | `text/event-stream` [Event](#schema-Event) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/events'
```

### Pending approval requests (the same objects as the `approval_request` events). {#op-listApprovals}

`GET /v1/sessions/{sessionId}/approvals` · operationId `listApprovals`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Pending approvals. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/approvals'
```

### Answer a pending approval request. {#op-decideApproval}

`POST /v1/sessions/{sessionId}/approvals/{approvalId}` · operationId `decideApproval`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `approvalId` | path | string | yes |  |

**Request body** (required)

`application/json`: [ApprovalDecision](#schema-ApprovalDecision)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Decision delivered to the harness. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such pending approval: unknown, already answered, timed out, or aborted (`approval_not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/approvals/<approvalId>' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Pending `ask_user` questions (the same objects as the `question_request` events). Added 2026-10. {#op-listQuestions}

`GET /v1/sessions/{sessionId}/questions` · operationId `listQuestions`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Pending questions. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/questions'
```

### Answer a pending `ask_user` question. Added 2026-10. {#op-answerQuestion}

`POST /v1/sessions/{sessionId}/questions/{questionId}` · operationId `answerQuestion`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

One answer per question, in order (fewer is allowed: the rest read as unanswered). `selected`
holds the chosen option labels; `text` is a free-form answer, which is always allowed.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `questionId` | path | string | yes |  |

**Request body** (required)

`application/json`: [QuestionAnswers](#schema-QuestionAnswers)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Answers delivered to the model. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such pending question: unknown, already answered, timed out, or aborted (`question_not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/questions/<questionId>' \
  -H 'Content-Type: application/json' -d '{...}'
```

### The session's turn checkpoints (file snapshots), oldest first. Added 2026-10. {#op-listCheckpoints}

`GET /v1/sessions/{sessionId}/checkpoints` · operationId `listCheckpoints`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

One entry per assistant turn that changed files (`harness.checkpoints.list()`), on the
session's current branch. `enabled` is false when checkpoints are off (git is not
installed, or the server turned them off); the list is then empty. Pass an entry's
`entryId` to `GET .../changes?turn=` for the files' text.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The checkpoints. | `application/json` [CheckpointList](#schema-CheckpointList) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/checkpoints'
```

### Each file one turn changed, with its text before and after. Added 2026-10. {#op-getChanges}

`GET /v1/sessions/{sessionId}/changes` · operationId `getChanges`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

From the turn's two snapshots, so the diff is exact whatever wrote the file (edit, write,
apply_patch, bash). Paths are workspace-relative. A file gets no text (`omitted` says why)
when its name is a secret's (`.env*`, keys, `credentials.json`, ...: the permission
engine's list; snapshots leave those out anyway), the session's read tool may not read it
right now (`denied`: a read deny or ask rule, an organisation policy; added 2026-10), it is
not UTF-8 text, it is a symlink or
a nested repository, one side is over 256 KiB, or the response already carries 4 MiB of
text. At most 100 files are listed; `more` counts the rest.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `turn` | query | string | yes | The checkpoint's `entryId` (from `GET .../checkpoints`, or the `entry.id` of an `entry_appended` event whose `entry.customType` is `venom-checkpoint`). |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The turn's changes. | `application/json` [TurnChanges](#schema-TurnChanges) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`), no checkpoint with that id in this session (`checkpoint_not_found`), checkpoints are off (`checkpoints_off`), or its snapshots were garbage-collected (`checkpoint_gone`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/changes'
```

### One directory of the session's workspace. Added 2026-10. {#op-listFiles}

`GET /v1/sessions/{sessionId}/files` · operationId `listFiles`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

For the browser IDE's file tree. Folders first, then files by name; `.git` is left out and
symlinks are listed but not followed. At most 2000 entries (`truncated`). Names are listed
whatever the read rules say; a file's text is gated by `GET .../file`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `path` | query | string |  | Workspace-relative directory. Empty or `.`: the workspace itself. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The directory. | `application/json` [DirListing](#schema-DirListing) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | The path leaves the session's workspace, by `..`, an absolute path or a symlink (`path_outside`); it is inside `.git` (`path_protected`); or the session's permission rules refuse it (`read_denied`, `write_denied`: a deny rule, a secret's name, an organisation policy). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or path (`file_not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/files'
```

### A text file of the session's workspace. Added 2026-10. {#op-readFile}

`GET /v1/sessions/{sessionId}/file` · operationId `readFile`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

UTF-8 text up to 512 KiB, and only a file the session's own `read` tool would be allowed to
read right now (the permission engine's verdict, `allow`; a secret's name, a deny or ask
rule or an organisation policy gives 403 `read_denied`). 413 `too_large`, 400 `not_text`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `path` | query | string | yes | Workspace-relative, `/`-separated. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The file. | `application/json` [FileContent](#schema-FileContent) |
| 400 | Missing or bad path, it is not a regular file (`not_a_file`), or it is not UTF-8 text (`not_text`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | The path leaves the session's workspace, by `..`, an absolute path or a symlink (`path_outside`); it is inside `.git` (`path_protected`); or the session's permission rules refuse it (`read_denied`, `write_denied`: a deny rule, a secret's name, an organisation policy). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or path (`file_not_found`). | `application/json` [Error](#schema-Error) |
| 413 | Over 512 KiB (`too_large`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/file'
```

### Write a text file of the session's workspace. Added 2026-10. {#op-writeFile}

`PUT /v1/sessions/{sessionId}/file` · operationId `writeFile`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

The browser IDE's save, and its rejection of an agent edit (writing the turn's `before` text
back). Creates the file when its directory exists. The session's `write` verdict decides: a
`deny` (a protected path, a deny rule, the organisation policy) is 403 `write_denied`; an
`ask` is the person at the keyboard answering for themselves. An existing file must also be
readable by the session, so a secret is never overwritten blind. At most 512 KiB.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

**Request body** (required)

`application/json`: object

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes |  |
| `content` | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Written. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | The path leaves the session's workspace, by `..`, an absolute path or a symlink (`path_outside`); it is inside `.git` (`path_protected`); or the session's permission rules refuse it (`read_denied`, `write_denied`: a deny rule, a secret's name, an organisation policy). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or path (`file_not_found`). | `application/json` [Error](#schema-Error) |
| 413 | Over 512 KiB (`too_large`). | `application/json` [Error](#schema-Error) |

```bash
curl -X PUT -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/file' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Delete a file of the session's workspace. Added 2026-10. {#op-deleteFile}

`DELETE /v1/sessions/{sessionId}/file` · operationId `deleteFile`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

The browser IDE's rejection of a file the agent added. A regular file only (not a directory
or a symlink); the session's `write` verdict must not be `deny`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `path` | query | string | yes | Workspace-relative, `/`-separated. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Deleted. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | The path leaves the session's workspace, by `..`, an absolute path or a symlink (`path_outside`); it is inside `.git` (`path_protected`); or the session's permission rules refuse it (`read_denied`, `write_denied`: a deny rule, a secret's name, an organisation policy). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or path (`file_not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -X DELETE -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/file'
```

### The session's conversation so far, as text. Added 2026-10. {#op-getTranscript}

`GET /v1/sessions/{sessionId}/transcript` · operationId `getTranscript`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

What a client shows for a resumed session: user messages, assistant text and tool calls,
tool results, oldest first. Each item's `text` keeps its first 64 KiB (`truncated` when cut),
and a response carries at most 8 Mi characters of text, the newest items first (older
items' text is cut, `truncated`); images are counted, not sent. pi's other message kinds
(compaction summaries, custom messages) are left out.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `limit` | query | integer |  | The newest this many items (default 200, at most 1000). |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The transcript. | `application/json` [Transcript](#schema-Transcript) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/transcript'
```

### The session's agent processes (`ps`), with ages and rates. Added 2026-10. {#op-listAgents}

`GET /v1/sessions/{sessionId}/agents` · operationId `listAgents`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

One entry per process in the session's runtime kernel (ADR 0009): the main agent (`pid` = `tree`;
pids are unique in the server process, not 1) and its `task` subagents while they run or wait to be collected. `tokensPerSec`
and `toolCallsPerMin` are over the interval since the previous call to this route for the
session (a lifetime average on the first call, or for a process seen for the first time).

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `top` | query | integer |  | Only the N agents with the highest `tokensPerSec`, highest first (1 to 100; ADR 0009's `top`). Added 2026-10. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The process table. | `application/json` [AgentList](#schema-AgentList) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or route (`not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/agents'
```

### One agent process (lifetime rates). Added 2026-10. {#op-getAgent}

`GET /v1/sessions/{sessionId}/agents/{pid}` · operationId `getAgent`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `pid` | path | integer | yes | A pid from `GET .../agents`. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The process. | `application/json` [AgentStatus](#schema-AgentStatus) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or process (`agent_not_found`: never spawned, or already reaped). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/agents/<pid>'
```

### Send a signal to an agent process. Added 2026-10. {#op-signalAgent}

`POST /v1/sessions/{sessionId}/agents/{pid}/signal` · operationId `signalAgent`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

ADR 0009 §4's signals, delivered to that one process through the runtime's signal table.
`SIGINT` aborts its in-flight model request or tool (a subagent stops with a partial report,
its parent goes on), `SIGKILL` stops it at once, `SIGCONT` wakes a paused one: these act
`now`. `SIGTERM` (stop with a partial report), `SIGSTOP` (park as `blocked(paused)`, holding
no request, until `SIGCONT`), `SIGUSR1`, `SIGUSR2` and `SIGCHLD` act at its next
`safe-point`, a turn boundary. Inside a critical section (a multi-file patch's commit) the
stopping signals are `deferred` until it ends. `tree: true` sends it to the process's live
descendants too, deepest first; a second `SIGINT` to a tree root within a second becomes
`SIGTERM`. What happened shows on the event stream (`agent` state changes, `span` events
with `kind: signal`).

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |
| `pid` | path | integer | yes | A pid from `GET .../agents`. |

**Request body** (required)

`application/json`: [SignalRequest](#schema-SignalRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Delivered. | `application/json` [SignalResult](#schema-SignalResult) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such session (`session_not_found`) or no live process with that pid in it (`agent_not_found`: never spawned, exited or reaped). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/agents/<pid>/signal' \
  -H 'Content-Type: application/json' -d '{...}'
```

## /v1/saved-sessions {#group-saved-sessions}

### Sessions saved with `persist`, newest first, that a new session can resume. Added 2026-10. {#op-listSavedSessions}

`GET /v1/saved-sessions` · operationId `listSavedSessions`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Saved sessions under the server's agent dir (pi's layout, so the terminal's `--resume`
sees the same ones), only those whose workspace is inside one of the server's roots. Pass
an `id` as `resume` to `POST /v1/sessions` (with the same `cwd`) to continue it.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cwd` | query | string |  | Only sessions started in this workspace (the same rules as a session's `cwd`). |
| `limit` | query | integer |  | At most this many (default 50, at most 500). |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Saved sessions. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | `cwd` is not inside an allowed root (`root_not_allowed`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/saved-sessions'
```

## /v1/projects {#group-projects}

### The folders a session can open in, each with its git branch. Added 2026-11. {#op-listProjects}

`GET /v1/projects` · operationId `listProjects`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Each of the server's allowed roots (`--root`), then the git repositories directly under one
(one level, by name; hidden directories and `node_modules` are skipped; a symlink only when it
resolves inside the same root). A root that is itself a repository says so. The branch is read
from `.git/HEAD` (no git process). Never file contents. At most 500 entries; `truncated` says
whether some were left out. Pass a project's `path` as `cwd` to `POST /v1/sessions`.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The projects. | `application/json` [ProjectList](#schema-ProjectList) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/projects'
```

## /v1/workflows {#group-workflows}

### The workflow scripts of a workspace, by name. Added 2026-10. {#op-listWorkflows}

`GET /v1/workflows` · operationId `listWorkflows`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

The scripts under `.venom/workflows/` of `cwd` (`venom workflow list` prints the same).
Listing only: running one stays a session's `/workflow run` prompt, which goes through the
session's permission mode.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cwd` | query | string | yes | The workspace (the same rules as a session's `cwd`). |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The workflows, by name. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | `cwd` is not inside an allowed root (`root_not_allowed`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/workflows'
```

## /v1/inbox {#group-inbox}

### The open inbox items, most urgent first. Added 2026-10. {#op-listInbox}

`GET /v1/inbox` · operationId `listInbox`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

The decisions only the human can make, from every local session (docs/inbox.md; `venom inbox
list --json` prints the same), ranked by `rank` = blast × uncertainty × (1 + minutes blocked).
The inbox is the host's (`venomHome`), not a workspace's: it is not narrowed by the roots.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The open items, highest `rank` first. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/inbox'
```

### One open inbox item. Added 2026-10. {#op-getInboxItem}

`GET /v1/inbox/{id}` · operationId `getInboxItem`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | An inbox item's id, or a prefix that is unique among the open items. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The item. | `application/json` [InboxItem](#schema-InboxItem) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No open item with that id or unique prefix (`inbox_item_not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/inbox/<id>'
```

### Answer an inbox item. Added 2026-10. {#op-resolveInboxItem}

`POST /v1/inbox/{id}/resolve` · operationId `resolveInboxItem`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Records the answer; the agent waiting on the item (`InboxStore.wait`) wakes with it. `approve`
lets it go on, `reject` refuses (`message` is the reason), `redirect` refuses and gives the
instruction in `message` (required), `take-over` stops the agent and waits for the human.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | An inbox item's id, or a prefix that is unique among the open items. |

**Request body** (required)

`application/json`: [InboxResolveRequest](#schema-InboxResolveRequest)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Resolved. | `application/json` [InboxResolved](#schema-InboxResolved) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No open item with that id or unique prefix (`inbox_item_not_found`). | `application/json` [Error](#schema-Error) |
| 409 | The item was already answered (`inbox_item_resolved`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/inbox/<id>/resolve' \
  -H 'Content-Type: application/json' -d '{...}'
```

## /v1/ide {#group-ide}

### The browser IDE page. No auth. Added 2026-10. {#op-getIdePage}

`GET /v1/ide` · operationId `getIdePage`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

One self-contained HTML document (inline CSS and JS, system fonts, no external request; a
Content-Security-Policy allows only its own script and style and requests to this origin).
The page holds nothing: it asks for the server token, keeps it in memory only and sends it as
a bearer header on every call below, so it has exactly the access any client with the token
has. It shows the session's files, an editor with a diff of the agent's edits (accept or
reject), the agent chat from the SSE stream, the output of its shell commands, and its
permission questions, answered through `POST .../approvals/{approvalId}`. docs/web-ide.md.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The page. | `text/html` string |

```bash
curl 'http://127.0.0.1:8790/v1/ide'
```

## /v1/mobile {#group-mobile}

### The phone approval inbox page. No auth. Added 2026-10. {#op-getMobilePage}

`GET /v1/mobile` · operationId `getMobilePage`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

One self-contained HTML document (inline CSS and JS, system fonts, no external request; a
Content-Security-Policy allows only its own script and style and requests to this origin).
The page itself holds nothing: it loads `GET /v1/mobile/inbox` and `GET /v1/mobile/events`
with the cookie a pairing set, and shows how to pair when there is none. Opened as
`/v1/mobile#pair=<code>` it first trades the code (`POST /v1/mobile/session`) and drops the
fragment from the address bar. docs/inbox.md → On your phone.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The page. | `text/html` string |

```bash
curl 'http://127.0.0.1:8790/v1/mobile'
```

### A one-time code that pairs a phone with the inbox page. Added 2026-10. {#op-createPairing}

`POST /v1/mobile/pairings` · operationId `createPairing`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

The code works once and for 2 minutes (`HarnessServerOptions.mobile.pairTtlMs`); the last 8
unused codes stay valid. `venom serve pair` calls this and prints the first of `urls` as a QR
code. The code goes in the URL fragment, which browsers never send, so it is in no request
line, server log or Referer. Bearer token only: a paired phone can't mint more pairings.

**Responses**

| Status | Description | Body |
|---|---|---|
| 201 | The pairing. | `application/json` [MobilePairing](#schema-MobilePairing) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/mobile/pairings'
```

### Trade a pairing code for the phone's cookie. No auth (the code is the credential). Added 2026-10. {#op-pairMobile}

`POST /v1/mobile/session` · operationId `pairMobile`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

Sets `venom_mobile_<port>`: HttpOnly, SameSite=Strict, `Path=/v1/mobile`, Max-Age 12 hours
(`Secure` behind a proxy that sends `X-Forwarded-Proto: https`). The code is compared in
constant time and used up. A request whose `Origin` or `Sec-Fetch-Site` names another site
is refused 403 `csrf_failed`. Paired phones live in memory: a restart unpairs them; 16 at most
(pairing another drops the oldest).

**Request body** (required)

`application/json`: object

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | string | yes | The code from `POST /v1/mobile/pairings`. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Paired; the cookie is set. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Unknown, used or expired code (`pairing_invalid`). | `application/json` [Error](#schema-Error) |
| 403 | From another site (`csrf_failed`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST 'http://127.0.0.1:8790/v1/mobile/session' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Unpair this phone (forget its cookie). Added 2026-10. {#op-unpairMobile}

`DELETE /v1/mobile/session` · operationId `unpairMobile`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Unpaired; the cookie is cleared. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | A paired phone's POST or DELETE without this origin or its `x-venom-csrf` token (`csrf_failed`). | `application/json` [Error](#schema-Error) |

```bash
curl -X DELETE -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/mobile/session'
```

### What the phone inbox shows. Added 2026-10. {#op-getMobileInbox}

`GET /v1/mobile/inbox` · operationId `getMobileInbox`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

The open inbox items (as `GET /v1/inbox`: approvals of TUI sessions, questions, stuck runs,
merges, leases) and every served session's pending approvals, with the session they belong to.
With a phone's cookie it also returns `csrf`, the token the page's POST and DELETE requests
carry in `x-venom-csrf`.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The inbox. | `application/json` [MobileInbox](#schema-MobileInbox) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/mobile/inbox'
```

### Server-Sent Events of the phone inbox. Added 2026-10. {#op-streamMobileEvents}

`GET /v1/mobile/events` · operationId `streamMobileEvents`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

`event: inbox`, `data: <MobileInbox JSON>` at once and whenever the set of waiting items
changes: at once for a served session's approval, within 2 s for inbox files other processes
write. `: ping` comments keep it open. A phone that unpairs or whose cookie expires loses the
stream at the next change.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The event stream. | `text/event-stream` [MobileInbox](#schema-MobileInbox) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/mobile/events'
```

### Answer an inbox item or a served session's approval from the phone. Added 2026-10. {#op-answerMobile}

`POST /v1/mobile/answer` · operationId `answerMobile`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

`{kind: inbox, id, action, message?}` resolves an inbox item as `POST /v1/inbox/{id}/resolve`
does; `{kind: approval, sessionId, approvalId, action, feedback?}` decides an approval as
`POST /v1/sessions/{sessionId}/approvals/{approvalId}` does. With the cookie, the request must
come from this origin and carry `x-venom-csrf`. Every answer is logged (`venom serve: phone
answered ...`).

**Request body** (required)

`application/json`: [MobileAnswer](#schema-MobileAnswer)

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Answered. | `application/json` [MobileAnswered](#schema-MobileAnswered) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | A paired phone's POST or DELETE without this origin or its `x-venom-csrf` token (`csrf_failed`). | `application/json` [Error](#schema-Error) |
| 404 | No such open item, session or pending approval (`inbox_item_not_found`, `session_not_found`, `approval_not_found`). | `application/json` [Error](#schema-Error) |
| 409 | The item was already answered (`inbox_item_resolved`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/mobile/answer' \
  -H 'Content-Type: application/json' -d '{...}'
```

## /v1/evidence {#group-evidence}

### The evidence bundle of a repository's change. Added 2026-10. {#op-getEvidence}

`GET /v1/evidence` · operationId `getEvidence`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

`venom evidence --json` for `root` (docs/evidence-bundle.md, `docs/evidence-bundle.schema.json`):
changed files, tests added, the impacted-test plan, invariants. `root` follows the rules of a
session's `cwd`, and the git repository it sits in must be inside a root as well. `base` is a
git ref (default `HEAD`, the uncommitted changes); a value that could be read as an option
(leading `-`) or holds whitespace is refused.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `root` | query | string | yes | A directory inside the server's roots, in a git repository. |
| `base` | query | string |  | The ref to compare with. Default `HEAD`. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The bundle. | `application/json` [EvidenceBundle](#schema-EvidenceBundle) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 403 | `root` or its repository is not inside an allowed root (`root_not_allowed`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/evidence'
```

## /v1/board {#group-board}

### The agent factory's health, the issue board plus the merge gate. Added 2026-10. {#op-getBoard}

`GET /v1/board` · operationId `getBoard`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

What `venom board health --json` prints (docs/board.md, ADR 0030): open issues per `status:*` label,
in-progress claims and their age, claim -> PR -> merge times per issue and per worker, gate runs on
this host (pass rate, stages that passed only on retry), per-stage outcomes from the flaky ledger,
requeues (PRs closed unmerged, issues claimed more than once) and the batch merge queue
(`scripts/gate.sh --queue`). Computed on request from `gh` and this host's gate state, at most once a
minute. When `gh` fails, `forge.ok` is false and the gate parts are still filled in. 404
`board_off` when the server was started without a board (no GitHub `origin` remote).

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The report. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No board on this server (`board_off`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/board'
```

## /v1/gears {#group-gears}

### The gears the server's venom.yaml offers, for an editor's gear switcher. Added 2026-10. {#op-listGears}

`GET /v1/gears` · operationId `listGears`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Each gear (docs/configuration.md -> Gears: the built-ins plus the user's own) with the model it
resolves to against the provider's model list. An editor switches the main agent to a gear by
posting that model to `POST /v1/sessions/{sessionId}/agents/1/model`. A server started without
gears (an embedding app) answers an empty list.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The gears, in key order. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/gears'
```

## /v1/schedules {#group-schedules}

### The scheduled jobs (venom.yaml `schedules:`) with their next and last run. Added 2026-10. {#op-listSchedules}

`GET /v1/schedules` · operationId `listSchedules`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Jobs `venom serve` runs on a cron schedule (docs/schedules.md). Each run is a session like a
client's: inside a root, counted against the session limit, saved (`persist`), every approval
question answered no. Empty when the server has no schedules.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The jobs. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/schedules'
```

### Runs of scheduled jobs, newest first. Added 2026-10. {#op-listScheduleRuns}

`GET /v1/schedules/runs` · operationId `listScheduleRuns`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `schedule` | query | string |  | Only this job's runs. |
| `limit` | query | integer |  | At most this many (default 50, at most 500). |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | Runs. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/schedules/runs'
```

### Start a job now, outside its schedule. Added 2026-10. {#op-runSchedule}

`POST /v1/schedules/{name}/run` · operationId `runSchedule`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Answers at once with the run as it started (`status: running`); `GET /v1/schedules/runs`
shows it end. Its session is listed in `GET /v1/sessions` while it runs.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 202 | Started. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such job (`schedule_not_found`). | `application/json` [Error](#schema-Error) |
| 409 | The job is running now (`schedule_running`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/schedules/<name>/run'
```

### One file a browser task's run produced. Added 2026-10. {#op-getScheduleRunOutput}

`GET /v1/schedules/runs/{runId}/output` · operationId `getScheduleRunOutput`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

A file from the run's `browser.files` (docs/schedules.md, Browser tasks): `result.json`, the
text of an extract step (`<name>.txt`), the model's answer when it took over (`answer.md`), or
a download (`downloads/<file>`). Sent as an attachment: JSON, plain text, else
`application/octet-stream`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `runId` | path | string | yes |  |
| `file` | query | string | yes | The file's path as `browser.files` lists it. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The file. | `application/octet-stream` string (binary) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such run (`run_not_found`) or no such file in it (`output_not_found`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/schedules/runs/<runId>/output'
```

## /v1/calls {#group-calls}

### Voice calls, live and stored, newest first. Added 2026-11. {#op-listCalls}

`GET /v1/calls` · operationId `listCalls`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Realtime voice agents (docs/voice-agents.md §5.3). Live calls come from the runtime, ended ones
from the call store (`~/.venom/calls`). Every calls route answers 404 `voice_not_configured`
when venom.yaml has no `voice.agents`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | `live` or `ended` |  |  |
| `agent` | query | string |  |  |
| `limit` | query | integer |  |  |
| `before` | query | string |  | Only calls that started before this ISO 8601 time. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The calls. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls'
```

### Start a call. Added 2026-11. {#op-createCall}

`POST /v1/calls` · operationId `createCall`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

`browser` opens the browser test line: the answer carries a media WebSocket URL and a single-use
ticket (60 s) for `GET /v1/calls/{callId}/media` (docs/voice-agents.md §5.4); the call starts when
the socket connects. `bridge` (added 2026-11, Venom Line) is the same for the orchestrator's media
bridge (`GET /v1/comms/media`, ADR 0061 §7): no `Origin` check, the caller's and line's numbers in
`from` and `to`, agent audio at `output_rate`, and the line's per-call settings in `line`; tools
and transfers then run through the bridge's socket. `asterisk` and `twilio` place an outbound call
to `to`.

**Request body** (required)

`application/json`: object

| Field | Type | Required | Description |
|---|---|---|---|
| `agent` | string | yes |  |
| `transport` | `browser` or `bridge` or `asterisk` or `twilio` | yes |  |
| `to` | string |  | The number or endpoint to call (asterisk, twilio); the line's number (bridge). |
| `from` | string |  | The caller's number (bridge). |
| `output_rate` | `8000` or `16000` or `24000` |  | The agent audio's PCM16 rate on the media socket (bridge). |
| `line` | object |  | Venom Line's per-call settings (bridge), from Venom Cloud through the bridge. |
| `line.opening` | string |  | Spoken first by script: the consent notice, then the greeting. |
| `line.voice` | string |  | The TTS voice. |
| `line.tools` | array of `lookup_caller` or `ask_knowledge` or `create_ticket` or `book_follow_up` or `transfer` |  |  |
| `line.max_call_s` | number |  |  |
| `line.max_usd` | number |  |  |
| `context` | map of string |  | Per-call data for the first user message's `[call context]` block. |

**Responses**

| Status | Description | Body |
|---|---|---|
| 201 | The call. | `application/json` object |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |
| 409 | `max_calls` calls are already running (`max_calls`). | `application/json` [Error](#schema-Error) |
| 502 | The call could not be set up (`call_failed`), e.g. the transport refused it. | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls' \
  -H 'Content-Type: application/json' -d '{...}'
```

### One call with its compliance events, handoff and per-turn metrics. Added 2026-11. {#op-getCall}

`GET /v1/calls/{callId}` · operationId `getCall`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `callId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The call. | `application/json` [VoiceCallDetail](#schema-VoiceCallDetail) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls/<callId>'
```

### The call's events as SSE. Added 2026-11. {#op-streamCallEvents}

`GET /v1/calls/{callId}/events` · operationId `streamCallEvents`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

Each event is a `CallEvent` (docs/voice-agents.md §4.5), its SSE `event:` the event's `type` and
its `id:` a sequence number from 1. `Last-Event-ID` or `?after=` replays past it. A live call's
stream ends when the call ends; an ended call's stored events are replayed and the stream closes.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `callId` | path | string | yes |  |
| `after` | query | integer |  |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The event stream. | `text/event-stream` [VoiceCallEvent](#schema-VoiceCallEvent) |
| 400 | Invalid body or parameters (`bad_request`, `body_too_large`, `invalid_json`). | `application/json` [Error](#schema-Error) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls/<callId>/events'
```

### Caller finals and the agent's heard text. Added 2026-11. {#op-getCallTranscript}

`GET /v1/calls/{callId}/transcript` · operationId `getCallTranscript`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `callId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The transcript; for the agent, what the caller heard. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls/<callId>/transcript'
```

### The call's recording, stereo PCM16 8 kHz WAV (caller left, agent right). Added 2026-11. {#op-getCallRecording}

`GET /v1/calls/{callId}/recording` · operationId `getCallRecording`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `callId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The recording. | `audio/wav` string (binary) |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`), or none recorded, or the call is still live (`no_recording`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls/<callId>/recording'
```

### Hang up a live call. Added 2026-11. {#op-hangupCall}

`POST /v1/calls/{callId}/hangup` · operationId `hangupCall`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `callId` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 202 | Hanging up. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |
| 409 | The call has ended (`call_ended`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls/<callId>/hangup'
```

### A supervisor's handoff of a live call to the agent's handoff target. Added 2026-11. {#op-transferCall}

`POST /v1/calls/{callId}/transfer` · operationId `transferCall`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `callId` | path | string | yes |  |

**Request body**

`application/json`: object

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | string |  |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 202 | Transferring; the call's `handoff` events report how it goes. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |
| 409 | The call has ended (`call_ended`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls/<callId>/transfer' \
  -H 'Content-Type: application/json' -d '{...}'
```

### The browser test line's media WebSocket. Ticket-authenticated. Added 2026-11. {#op-connectCallMedia}

`GET /v1/calls/{callId}/media` · operationId `connectCallMedia`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

A WebSocket upgrade with `?ticket=` from `POST /v1/calls` (single use, 60 s, bound to the call)
and, for the browser line, an `Origin` in `voice.browser.origins`; otherwise refused 403. The
media bridge's socket (`transport: bridge`) speaks the same messages, agent audio at its
`output_rate`, plus `tool`/`transfer` (server) and `tool_result`/`transfer_result` (bridge). Binary frames are PCM16 LE
mono, 16 kHz in and 24 kHz out; text frames carry `hello`, `mark`, `clear`, `end` (server) and
`mark_played`, `dtmf`, `hangup` (browser). docs/voice-agents.md §5.4. A plain GET answers 426.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `callId` | path | string | yes |  |
| `ticket` | query | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 101 | Switching protocols. |  |
| 403 | Bad or used ticket, or origin not allowed. |  |

```bash
curl 'http://127.0.0.1:8790/v1/calls/<callId>/media'
```

## /v1/voice {#group-voice}

### The configured voice agents. Added 2026-11. {#op-listVoiceAgents}

`GET /v1/voice/agents` · operationId `listVoiceAgents`

Requires `Authorization: Bearer $VENOM_SERVER_TOKEN`.

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The agents. | `application/json` object |
| 401 | Missing or wrong bearer token (`unauthorized`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/voice/agents'
```

### Twilio's voice webhook. Public; checked by `X-Twilio-Signature`. Added 2026-11. {#op-twilioIncoming}

`POST /v1/voice/twilio/incoming` · operationId `twilioIncoming`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

Set as the number's voice webhook: `{voice.twilio.public_url}/v1/voice/twilio/incoming`. The signature
is Twilio's HMAC-SHA1 over the public URL and the form params, compared in constant time. Answers
TwiML: `<Connect><Stream>` to `/v1/voice/twilio/media` with a single-use ticket for the agent
`voice.routes` picks by `To`; `<Reject>` when no route matches or `max_calls` are running.
docs/voice-agents.md §5.5.

**Request body** (required)

`application/x-www-form-urlencoded`: map of string

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | TwiML. | `text/xml` string |
| 403 | Missing or invalid signature (`bad_signature`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST 'http://127.0.0.1:8790/v1/voice/twilio/incoming' \
  -H 'Content-Type: application/json' -d '{...}'
```

### Twilio's call status callback (answering-machine results). Public; signature-checked. Added 2026-11. {#op-twilioStatus}

`POST /v1/voice/twilio/status` · operationId `twilioStatus`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

**Request body** (required)

`application/x-www-form-urlencoded`: map of string

**Responses**

| Status | Description | Body |
|---|---|---|
| 204 | Recorded. |  |
| 403 | Missing or invalid signature (`bad_signature`). | `application/json` [Error](#schema-Error) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl -X POST 'http://127.0.0.1:8790/v1/voice/twilio/status' \
  -H 'Content-Type: application/json' -d '{...}'
```

### TwiML that plays a warm transfer's whisper to the target. Public; single-use token, 2 min. Added 2026-11. {#op-twilioWhisper}

`GET /v1/voice/twilio/whisper/{token}` · operationId `twilioWhisper`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `token` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | TwiML `<Play>` of the clip. | `text/xml` string |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl 'http://127.0.0.1:8790/v1/voice/twilio/whisper/<token>'
```

### Twilio Media Streams WebSocket. Public; single-use ticket from the TwiML. Added 2026-11. {#op-connectTwilioMedia}

`GET /v1/voice/twilio/media` · operationId `connectTwilioMedia`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

µ-law 8 kHz `media` messages both ways, `mark` echoes bound what the caller heard, `clear` drops
Twilio's buffer on barge-in. A bad or used ticket is refused 403; a plain GET answers 426.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ticket` | query | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 101 | Switching protocols. |  |
| 403 | Bad or used ticket. |  |

```bash
curl 'http://127.0.0.1:8790/v1/voice/twilio/media'
```

### A whisper clip as WAV (`<token>.wav`). Public; single-use token, 2 min. Added 2026-11. {#op-getVoiceClip}

`GET /v1/voice/clips/{clip}` · operationId `getVoiceClip`

No authentication.

Served to a browser page (the phone inbox or the IDE); the clients have no method for it.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `clip` | path | string | yes |  |

**Responses**

| Status | Description | Body |
|---|---|---|
| 200 | The clip. | `audio/wav` string (binary) |
| 404 | No such call (`call_not_found`) or agent (`unknown_agent`), or venom serve has no voice agents (`voice_not_configured`). | `application/json` [Error](#schema-Error) |

```bash
curl 'http://127.0.0.1:8790/v1/voice/clips/<clip>'
```

## Schemas

### VoiceCallSummary {#schema-VoiceCallSummary}

Added 2026-11. One voice call (docs/voice-agents.md §5.3).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `agent` | string | yes |  |
| `transport` | `browser` or `bridge` or `asterisk` or `twilio` | yes |  |
| `direction` | `inbound` or `outbound` | yes |  |
| `from` | string | yes | E.164 where known; the browser line says browser:<user>. |
| `to` | string | yes |  |
| `state` | `live` or `ended` | yes |  |
| `startedAt` | string (date-time) | yes |  |
| `endedAt` | string (date-time) |  |  |
| `durationMs` | integer |  |  |
| `outcome` | string |  | Who ended it and why, e.g. `caller: hangup`. |
| `recording` | boolean | yes |  |
| `costUsd` | number | yes |  |
| `turns` | integer | yes |  |
| `interruptions` | integer | yes | Barge-ins. |
| `p50FirstAudioMs` | integer or null | yes | Median end of caller speech → first agent audio, over the call's turns. |

### VoiceCallDetail {#schema-VoiceCallDetail}

Added 2026-11. A call with its compliance events, last handoff event and per-turn metrics.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `agent` | string | yes |  |
| `transport` | `browser` or `bridge` or `asterisk` or `twilio` | yes |  |
| `direction` | `inbound` or `outbound` | yes |  |
| `from` | string | yes | E.164 where known; the browser line says browser:<user>. |
| `to` | string | yes |  |
| `state` | `live` or `ended` | yes |  |
| `startedAt` | string (date-time) | yes |  |
| `endedAt` | string (date-time) |  |  |
| `durationMs` | integer |  |  |
| `outcome` | string |  | Who ended it and why, e.g. `caller: hangup`. |
| `recording` | boolean | yes |  |
| `costUsd` | number | yes |  |
| `turns` | integer | yes |  |
| `interruptions` | integer | yes | Barge-ins. |
| `p50FirstAudioMs` | integer or null | yes | Median end of caller speech → first agent audio, over the call's turns. |
| `compliance` | array of object | yes |  |
| `compliance[].kind` | string | yes |  |
| `compliance[].detail` | string | yes |  |
| `compliance[].t` | number | yes |  |
| `handoff` | object |  |  |
| `handoff.phase` | `requested` or `dialing` or `bridged` or `failed` | yes |  |
| `handoff.reason` | string | yes |  |
| `handoff.t` | number | yes |  |
| `metrics` | array of object | yes |  |
| `metrics[].turnId` | string | yes |  |
| `metrics[].eosToFirstAudioMs` | number or null |  |  |

### VoiceCallEvent {#schema-VoiceCallEvent}

Added 2026-11. A `CallEvent` (docs/voice-agents.md §4.5): `call.state`, `caller.partial`,
`caller.final`, `agent.segment`, `agent.spoken`, `interruption`, `tool`, `turn.metrics`,
`compliance`, `guard`, `handoff`, `dtmf` or `error`. `t` is ms since the call started.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes |  |
| `t` | number |  |  |

### VoiceTranscriptItem {#schema-VoiceTranscriptItem}

Added 2026-11. One transcript line; the agent's text is what the caller heard.

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `caller` or `agent` | yes |  |
| `text` | string | yes |  |
| `startMs` | number | yes |  |
| `endMs` | number | yes |  |
| `interrupted` | boolean |  |  |
| `backchannel` | boolean |  |  |

### AgentStatus {#schema-AgentStatus}

Added 2026-10. One agent process with its age and rates (`ps`/`top`).

| Field | Type | Required | Description |
|---|---|---|---|
| `info` | [ProcInfo](#schema-ProcInfo) | yes | Added 2026-10. One row of the agent process table (ADR 0009): the session's main agent is the tree root (`tree`), `task` children are its children. A `blocked` process always has a `wait` reason. |
| `ageMs` | integer | yes | Milliseconds since spawn (to the exit, for an exited process). |
| `waitMs` | integer |  | Milliseconds a blocked process has waited. |
| `tokensPerSec` | number | yes |  |
| `toolCallsPerMin` | number | yes |  |

### AgentList {#schema-AgentList}

Added 2026-10.

| Field | Type | Required | Description |
|---|---|---|---|
| `agents` | array of [AgentStatus](#schema-AgentStatus) | yes |  |

### SignalRequest {#schema-SignalRequest}

Added 2026-10.

| Field | Type | Required | Description |
|---|---|---|---|
| `signal` | `SIGINT` or `SIGTERM` or `SIGKILL` or `SIGSTOP` or `SIGCONT` or `SIGUSR1` or `SIGUSR2` or `SIGCHLD` | yes |  |
| `tree` | boolean |  | Send it to the process's live descendants too, deepest first. |
| `reason` | string |  | Recorded on the signal span and event (default "POST /signal"). |

### SignalResult {#schema-SignalResult}

Added 2026-10.

| Field | Type | Required | Description |
|---|---|---|---|
| `pid` | integer | yes |  |
| `signal` | string | yes |  |
| `tree` | boolean | yes |  |
| `delivery` | `now` or `safe-point` or `deferred` | yes | When it acts on the process: `now`, at its next `safe-point` (a turn boundary), or `deferred` until its critical section ends. |

### Error {#schema-Error}

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.code` | string | yes |  |
| `error.message` | string | yes |  |

### Health {#schema-Health}

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `"ok"` | yes |  |
| `version` | string | yes |  |
| `sessions` | integer | yes |  |
| `maxSessions` | integer | yes |  |

### PermissionMode {#schema-PermissionMode}

`sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume.

Type: `plan` or `default` or `accept-edits` or `auto` or `yolo` or `sudo`

### ApprovalAction {#schema-ApprovalAction}

Type: `allow-once` or `allow-session` or `allow-project` or `deny`

### CompatOptions {#schema-CompatOptions}

Which Claude Code compatibility sources to load. `false` loads none; omitted loads all.

Type: boolean or object

### CreateSessionRequest {#schema-CreateSessionRequest}

| Field | Type | Required | Description |
|---|---|---|---|
| `cwd` | string | yes | Workspace directory. Must exist and resolve (after symlinks) inside one of the server's `--root`s. |
| `mode` | [PermissionMode](#schema-PermissionMode) |  | `sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume. |
| `model` | string |  | Model id on the venom provider (default `venom-default`). The provider itself (base URL, key) is server configuration. |
| `rules` | object |  | Permission rules for this session, e.g. `bash(npm test:*)`. |
| `rules.allow` | array of string |  |  |
| `rules.ask` | array of string |  |  |
| `rules.deny` | array of string |  |  |
| `compat` | [CompatOptions](#schema-CompatOptions) |  | Which Claude Code compatibility sources to load. `false` loads none; omitted loads all. |
| `persist` | boolean |  | Persist the transcript as JSONL under the server's agent dir. Default false. |
| `trustProject` | boolean |  | Trust the project's hooks, MCP servers and allow rules. Default false. |
| `thinkingLevel` | `off` or `minimal` or `low` or `medium` or `high` or `xhigh` |  |  |
| `tools` | array of string |  | Restrict active pi tools. |
| `appendSystemPrompt` | array of string |  |  |
| `subagents` | boolean |  | The `task` tool. Default true. |
| `planning` | boolean |  | Plan mode and the `todo` tool. Default true. |
| `sandbox` | boolean or `"auto"` |  | OS sandbox for bash. Default `auto` (on in yolo). |
| `approvalTimeoutMs` | integer |  | How long an approval request waits for an answer before it is denied. Capped by the server (`venom serve` caps it at 10 minutes, or at `--approval-timeout` when that is higher). |
| `resume` | string |  | Added 2026-10. Continue this saved session (an `id` from `GET /v1/saved-sessions`) instead of starting a new one: pi restores its conversation and new entries are appended to the same file. It must have been started in this `cwd` (404 `saved_session_not_found` otherwise). Implies `persist`. |
| `venomMcp` | `false` or [SessionVenomMcp](#schema-SessionVenomMcp) |  | Added 2026-11. Venom Cloud's product MCP servers (Globe, Tasks, People, Funnel, ...: one deferred server per product at `<url>/workspace/mcp/<product>`) for this session, with this session's own credential in place of the server host's `venom cloud login`; `false` connects none. Venom Cloud sets it on the sessions it starts (a computer agent's run) with a key scoped to that agent and org. The key goes only in those servers' Authorization header: it is never in the session state, the events or the model's context. Without it, a logged-in host connects every product with its own key. |
| `cloudInference` | [SessionCloudInference](#schema-SessionCloudInference) |  | Added 2026-11. Venom Cloud's inference for this session: its model requests (the main turns, subagents and side calls) go to `<url>/v1` with this key and `x-venom-daemon: cloud`, so the cloud serves them from its own providers and never relays them back to a daemon, instead of to the server's own provider. Venom Cloud sets it when a chat's gear runs on cloud keys (docs/adr/0081-venom-agents-app.md, Amendment 2026-11-18). The key goes only in those requests' Authorization header: never in the session state, the events, the transcript or the model's context. The OS sandbox keeps the server's orchestrator as its own, so commands do not reach the cloud through it. Refused (403 `policy_forbidden`) when the organisation policy pins the orchestrator. `GET /v1/gears` says `cloudInference: true` on a server that takes it. |

### SessionCloudInference {#schema-SessionCloudInference}

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | The Venom Cloud origin (the session calls `<url>/v1`), https (http only to loopback), no userinfo. |
| `key` | string | yes | A Venom Cloud client key of whoever started the session; usage, budgets and model access are theirs. |

### SessionVenomMcp {#schema-SessionVenomMcp}

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | The Venom Cloud origin, https (http only to loopback), no userinfo. |
| `key` | string | yes | A Venom Cloud key (a client or agent key) sent as the bearer token to the product servers. |
| `products` | array of string |  | Only these products (`globe`, `tasks`, `people`, `exp` or `experiments`, ...). Default all. |

### SessionState {#schema-SessionState}

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `cwd` | string | yes |  |
| `mode` | [PermissionMode](#schema-PermissionMode) | yes | `sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume. |
| `model` | string |  | `provider/id`. |
| `status` | `idle` or `running` | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `lastEventId` | integer | yes |  |
| `pendingApprovals` | integer | yes |  |
| `approvalTimeoutMs` | integer | yes |  |
| `messageCount` | integer |  |  |
| `sandboxActive` | boolean |  |  |
| `projectTrusted` | boolean |  |  |
| `persisted` | boolean |  |  |
| `sessionFile` | string |  |  |
| `piSessionId` | string |  | pi's session id, which the venom provider sends as `x-venom-session`: the id the orchestrator logs this session's requests under (`GET /admin/v1/sessions/{id}`). Subagents run as their own sessions with their own ids. |
| `imageInput` | boolean |  | Added 2026-10. The session's model takes images, so a prompt may carry `images`. |

### PromptRequest {#schema-PromptRequest}

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes |  |
| `streamingBehavior` | `steer` or `followUp` |  | Required while a run is active (pi semantics). |
| `images` | array of [ImageInput](#schema-ImageInput) |  | Added 2026-10. Images sent with the message, for a model that takes them (`SessionState.imageInput`; 400 `images_not_supported` otherwise). A prompt body may be up to 16 MiB (the server option `maxPromptBytes`); every other body stays at 1 MiB. |

### AuthProofRequest {#schema-AuthProofRequest}

| Field | Type | Required | Description |
|---|---|---|---|
| `nonce` | string | yes | Fresh random bytes (16 or more) as lowercase hex, new for every check. |

### AuthProof {#schema-AuthProof}

| Field | Type | Required | Description |
|---|---|---|---|
| `proof` | string | yes | Lowercase hex HMAC-SHA256(token, "venom-serve-proof-v1\n" + nonce + "\n" + port). |
| `port` | integer | yes | The local port the request arrived on. |

### ImageInput {#schema-ImageInput}

An image sent with a prompt (added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | string | yes | The image file's bytes, base64 (no `data:` prefix). They must be `mimeType`'s format (magic bytes) and the header's size at most 20000 px a side and 50 megapixels (400 `bad_request`). |
| `mimeType` | `image/png` or `image/jpeg` or `image/gif` or `image/webp` | yes |  |

### CheckpointInfo {#schema-CheckpointInfo}

One turn checkpoint (added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `entryId` | string | yes | The `venom-checkpoint` session entry; `GET .../changes?turn=` takes it. |
| `run` | string | yes | The entry id of the user message that started the run (one prompt, many turns). |
| `prompt` | string |  | That prompt, shortened. |
| `before` | string | yes | Snapshot commit before the turn (in the server's shadow store). |
| `after` | string | yes | Snapshot commit after the turn. |
| `files` | array of string | yes | Changed paths, workspace-relative (at most 50). |
| `more` | integer |  | Changed paths beyond `files`. |
| `at` | integer | yes | When the turn's first change started (ms since the epoch). |
| `undone` | boolean | yes | The run is currently undone (`/undo`). |

### CheckpointList {#schema-CheckpointList}

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | boolean | yes |  |
| `disabledReason` | string |  | Why checkpoints are off, when they are. |
| `checkpoints` | array of [CheckpointInfo](#schema-CheckpointInfo) | yes |  |

### TurnFileChange {#schema-TurnFileChange}

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes | Workspace-relative, `/`-separated. |
| `status` | `A` or `D` or `M` or `T` | yes | A added, D deleted, M modified, T type changed (file and symlink). |
| `added` | integer |  |  |
| `removed` | integer |  |  |
| `before` | string |  | The text before the turn (absent for an added file, or when `omitted`). |
| `after` | string |  | The text after the turn (absent for a deleted file, or when `omitted`). |
| `omitted` | `secret` or `denied` or `binary` or `too-large` or `symlink` or `submodule` or `budget` |  | Why there is no text. |

### DirListing {#schema-DirListing}

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes | The directory, workspace-relative (empty for the workspace). |
| `entries` | array of object | yes |  |
| `entries[].name` | string | yes |  |
| `entries[].type` | `file` or `dir` or `symlink` | yes |  |
| `entries[].size` | integer |  |  |
| `truncated` | boolean |  |  |

### FileContent {#schema-FileContent}

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes |  |
| `content` | string | yes |  |
| `size` | integer | yes | Bytes. |

### TurnChanges {#schema-TurnChanges}

| Field | Type | Required | Description |
|---|---|---|---|
| `entryId` | string | yes |  |
| `run` | string | yes |  |
| `prompt` | string |  |  |
| `at` | integer | yes |  |
| `files` | array of [TurnFileChange](#schema-TurnFileChange) | yes |  |
| `more` | integer |  | Changed files beyond `files`, not listed. |

### ScheduleRun {#schema-ScheduleRun}

One run of a scheduled job (added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `schedule` | string | yes | The job's name. |
| `trigger` | `cron` or `catch-up` or `manual` or `event` | yes | `catch-up`: one run for every time missed while the server was down. `event`: started by one of the job's `on:` events (`event` names it). |
| `event` | string |  | An `event` run's trigger, one line: `tool_call bash: <session id>`. |
| `status` | `running` or `completed` or `error` or `aborted` or `budget` or `skipped` | yes | `budget`: stopped at the job's `maxUsd`. |
| `startedAt` | string (date-time) | yes |  |
| `endedAt` | string (date-time) |  |  |
| `durationMs` | integer |  |  |
| `costUsd` | number | yes | Its model calls at list price (0 for local models). |
| `summary` | string | yes | The final answer, one line, at most 300 characters. |
| `error` | string |  |  |
| `piSessionId` | string |  | The saved session (`GET /v1/saved-sessions`; `resume` it to continue). |
| `workspace` | string |  | The git worktree it ran in. |
| `workspaceKept` | boolean |  | The worktree was kept because the run changed something (else removed). |
| `model` | string |  |  |
| `browser` | [ScheduleBrowserRun](#schema-ScheduleBrowserRun) |  | How a browser task's run went (added 2026-10; docs/schedules.md, Browser tasks). |
| `watch` | [ScheduleWatchRun](#schema-ScheduleWatchRun) |  | A page watch's check that fired or failed (added 2026-10; docs/browser-extension.md, Page watches). Its run's `schedule` is `watch:<name>`; quiet checks leave no run. |

### ScheduleWatchRun {#schema-ScheduleWatchRun}

A page watch's check that fired or failed (added 2026-10; docs/browser-extension.md, Page watches). Its run's `schedule` is `watch:<name>`; quiet checks leave no run.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes |  |
| `url` | string | yes |  |
| `fired` | boolean | yes | The watch's condition started to hold (a change, a price under the threshold, an element that appeared). |
| `summary` | string | yes | The check's line, e.g. `price: 89.99 (below 100: yes), was 120`. |
| `actions` | array of string |  | What it did about it (the webhook's answer, the task replayed, the agent's answer). |

### ScheduleBrowserRun {#schema-ScheduleBrowserRun}

How a browser task's run went (added 2026-10; docs/schedules.md, Browser tasks).

| Field | Type | Required | Description |
|---|---|---|---|
| `task` | string | yes | The recorded script. |
| `outcome` | `replayed` or `healed` or `failed` | yes | `replayed`: no model call. `healed`: a step failed because the page changed and the model finished the task (the fix is saved to the script). `failed`: it didn't finish. |
| `steps` | integer | yes | Steps in the script. |
| `done` | integer | yes | Steps the model-free replay ran to completion. |
| `failure` | string |  | Where the model-free replay stopped. |
| `fallback` | boolean |  | The model took over (capped at the job's `maxUsd`). |
| `outputs` | string |  | The run's output directory on the server. |
| `files` | array of string |  | The files in `outputs`, relative (`GET /v1/schedules/runs/{runId}/output?file=`). |

### ScheduleInfo {#schema-ScheduleInfo}

A scheduled job (added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes |  |
| `cron` | string | yes | Empty for a job that runs only on events. |
| `on` | array of object |  | Events that start a run (`intent_closed`, `session_created`, `session_timeout`, `tool_call`). |
| `on[].event` | `intent_closed` or `session_created` or `session_timeout` or `tool_call` | yes |  |
| `on[].tools` | array of string |  | `tool_call` only: the tool names it matches. |
| `queued` | integer |  | Event runs waiting for the job's current run to end (first in, first out). |
| `prompt` | string | yes |  |
| `cwd` | string | yes |  |
| `workspace` | boolean | yes | Each run gets its own git worktree of `cwd`. |
| `model` | string |  |  |
| `gear` | string |  |  |
| `role` | string |  | A standing role (`dependency-bumper`, `flaky-hunter`, `dead-code`, `docs-drift`, or the name of a role a plugin ships, `venom role add`); each run is filed in the inbox (added 2026-10). |
| `browserTask` | string |  | A recorded browser script the job replays with no model; each run is filed in the inbox (added 2026-10). |
| `browser` | `headless` or `launch` or `extension` or `attach` |  | Where a browser task runs. |
| `params` | map of string |  | The browser task's parameter values (never a secret one). |
| `allow` | array of string |  | Permission rules the unattended run may use without asking. |
| `mode` | `plan` or `default` or `accept-edits` or `auto` or `yolo` | yes |  |
| `maxUsd` | number | yes |  |
| `enabled` | boolean | yes |  |
| `running` | boolean | yes |  |
| `nextRunAt` | string (date-time) |  | In the past when a run was missed (it starts at the next check). |
| `lastRun` | [ScheduleRun](#schema-ScheduleRun) |  | One run of a scheduled job (added 2026-10). |

### InboxItem {#schema-InboxItem}

Added 2026-10. One decision waiting for the human (`InboxItem` in `@venom/harness/inbox`) with its rank.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `kind` | `approval` or `question` or `merge` or `lease` | yes |  |
| `title` | string | yes |  |
| `detail` | string |  |  |
| `agent` | string |  | Who is waiting. |
| `session` | string |  |  |
| `cwd` | string |  |  |
| `pid` | integer | yes | The waiting process. |
| `blast` | integer | yes | 1 (cosmetic) to 5 (irreversible or shared). |
| `uncertainty` | integer | yes | 1 (obvious) to 5 (the agent has no idea). |
| `createdAt` | integer | yes | Unix milliseconds. |
| `rank` | number | yes | blast × uncertainty × (1 + minutes blocked), at the time of the request. |

### MobilePairing {#schema-MobilePairing}

Added 2026-10. A one-time code that pairs a phone with the inbox page (`POST /v1/mobile/pairings`).

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | string | yes | 128 random bits, base64url. Works once. |
| `expiresAt` | string (date-time) | yes |  |
| `path` | string | yes | `/v1/mobile#pair=<code>`. |
| `urls` | array of string | yes | Full URLs a phone can open: this machine's LAN IPv4 addresses on a wildcard bind, the bound address otherwise. |
| `reachable` | `lan` or `this-machine` | yes | `this-machine` on a loopback bind: a phone can't reach it until venom serve listens with `--host` on the network. |

### MobileApproval {#schema-MobileApproval}

Added 2026-10. A served session's pending approval, with the session it belongs to.

| Field | Type | Required | Description |
|---|---|---|---|
| `approvalId` | string | yes |  |
| `tool` | string | yes |  |
| `toolCallId` | string |  | pi's id of the call being gated: the `toolCallId` of its `tool_execution_start` event, so a client can attach the question to the call it already shows. Absent for checks that are not a model tool call (a slash command's `!` shell expansion). For a subagent's call it is the child session's id, which never appears in this stream; see `parentToolCallId`. |
| `parentToolCallId` | string |  | For a subagent's call, the parent's `task` call that started the subagent (that one is in this stream). For a call another tool issued, pi's parent call id. |
| `input` | object | yes |  |
| `summary` | string | yes | One-line description of the call. |
| `reason` | string | yes | Why the policy asks. |
| `mode` | [PermissionMode](#schema-PermissionMode) | yes | `sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume. |
| `suggestions` | array of string | yes | Rules that would auto-allow similar calls (used by allow-session / allow-project). |
| `rules` | array of string |  | What allow-session / allow-project stores when the decision names no `rule` or `rules`: every rule this call needs to be auto-allowed next time. A compound command gets one per segment that asked (`npm test \| tee out.txt` → `bash(npm test:*)`, `bash(tee out.txt:*)`); other calls the first suggestion. Show them all before the user chooses. Empty: no rule can cover the call, offer only allow-once. |
| `agent` | string |  | Set when a subagent makes the call. |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `sessionId` | string | yes |  |
| `cwd` | string | yes |  |

### MobileInbox {#schema-MobileInbox}

Added 2026-10. What the phone inbox shows.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array of [InboxItem](#schema-InboxItem) | yes | The open inbox items, highest `rank` first. |
| `approvals` | array of [MobileApproval](#schema-MobileApproval) | yes |  |
| `csrf` | string |  | With a phone's cookie only. The value its POST and DELETE requests carry in `x-venom-csrf`. |
| `expiresAt` | string (date-time) |  | With a phone's cookie only. When the pairing ends. |

### MobileAnswer {#schema-MobileAnswer}

Added 2026-10. An answer from the phone inbox.

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | `inbox` or `approval` | yes |  |
| `id` | string |  | kind inbox: the item's id. |
| `sessionId` | string |  | kind approval: the session. |
| `approvalId` | string |  | kind approval: the approval. |
| `action` | string | yes | kind inbox: an `InboxResolveRequest.action`; kind approval: an `ApprovalAction`. |
| `message` | string |  | kind inbox: as `InboxResolveRequest.message`. |
| `feedback` | string |  | kind approval: as `ApprovalDecision.feedback`. |
| `rule` | string |  | kind approval: as `ApprovalDecision.rule`. |
| `rules` | array of string |  | kind approval: as `ApprovalDecision.rules`. |

### MobileAnswered {#schema-MobileAnswered}

Added 2026-10.

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | `inbox` or `approval` | yes |  |
| `action` | string | yes |  |
| `id` | string |  | kind inbox: the item answered. |
| `message` | string |  |  |
| `approvalId` | string |  | kind approval: the approval answered. |

### InboxResolveRequest {#schema-InboxResolveRequest}

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `approve` or `reject` or `redirect` or `take-over` | yes |  |
| `message` | string |  | The instruction for `redirect` (required there), the reason for `reject`. |

### InboxResolved {#schema-InboxResolved}

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `action` | `approve` or `reject` or `redirect` or `take-over` | yes |  |
| `message` | string |  |  |

### EvidenceBundle {#schema-EvidenceBundle}

Added 2026-10. `venom.evidence/v1`, the same document as `docs/evidence-bundle.schema.json`
(that file is the authority for the nested shapes).

| Field | Type | Required | Description |
|---|---|---|---|
| `schema` | `"venom.evidence/v1"` | yes |  |
| `generatedAt` | string | yes |  |
| `base` | string | yes |  |
| `head` | string |  |  |
| `changed` | array of string | yes |  |
| `tests` | object | yes |  |
| `tests.added` | array of string | yes |  |
| `tests.runs` | array of object | yes |  |
| `tests.impact` | object | yes |  |
| `bench` | array of object | yes |  |
| `evals` | array of object | yes |  |
| `invariants` | array of object | yes |  |
| `invariants[].name` | string | yes |  |
| `invariants[].status` | `pass` or `fail` or `n/a` | yes |  |
| `invariants[].detail` | string |  |  |
| `session` | object |  |  |
| `screenshots` | array of string | yes |  |
| `risk` | object |  |  |

### WorkflowInfo {#schema-WorkflowInfo}

A workflow script of a workspace (added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | What `/workflow run <name>` takes. |
| `file` | string | yes | The script's path, relative to the workspace. |

### Project {#schema-Project}

A folder a session can open in (added 2026-11).

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | The directory's own name. |
| `path` | string | yes | Its absolute, canonical path; pass it as a session's `cwd`. |
| `root` | string | yes | The allowed root it is, or sits directly under. |
| `git` | boolean | yes | Whether it is a git repository. |
| `branch` | string |  | The branch its HEAD points at; absent when it is not a repository or HEAD is detached. |

### ProjectList {#schema-ProjectList}

| Field | Type | Required | Description |
|---|---|---|---|
| `projects` | array of [Project](#schema-Project) | yes |  |
| `truncated` | boolean | yes | More than 500 folders; the rest were left out. |

### SavedSession {#schema-SavedSession}

A session saved with `persist` (added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | pi's session id; `POST /v1/sessions` takes it as `resume`. |
| `cwd` | string | yes |  |
| `name` | string |  | The name set with `/name`, if any. |
| `created` | string (date-time) | yes |  |
| `modified` | string (date-time) | yes |  |
| `messageCount` | integer | yes |  |
| `firstMessage` | string | yes | The first user message, its first 200 characters. |

### TranscriptToolCall {#schema-TranscriptToolCall}

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes |  |
| `args` | object | yes |  |

### TranscriptItem {#schema-TranscriptItem}

One message of a session's conversation (added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `user` or `assistant` or `toolResult` | yes |  |
| `text` | string | yes | The message's text blocks joined by newlines (first 64 KiB). |
| `truncated` | boolean |  | `text` or `thinking` was cut. |
| `thinking` | string |  | An assistant message's thinking (first 64 KiB). |
| `toolCalls` | array of [TranscriptToolCall](#schema-TranscriptToolCall) |  | An assistant message's tool calls. |
| `toolCallId` | string |  | A tool result's call. |
| `toolName` | string |  |  |
| `isError` | boolean |  |  |
| `images` | integer |  | Images in the message (not sent). |
| `timestamp` | integer |  | ms since the epoch. |

### Transcript {#schema-Transcript}

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array of [TranscriptItem](#schema-TranscriptItem) | yes |  |
| `total` | integer | yes | Items in the whole transcript (more than `items` holds when `limit` cut it). |

### MessageRequest {#schema-MessageRequest}

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes |  |

### PromptAccepted {#schema-PromptAccepted}

| Field | Type | Required | Description |
|---|---|---|---|
| `promptId` | string | yes | Matches the `prompt_end` event of this prompt (only sent when `disposition` is `started`). |
| `disposition` | `started` or `queued` or `handled` | yes |  |
| `lastEventId` | integer | yes | Last event seq before the prompt. Stream with `?after=` this to miss nothing. |

### QueuedResponse {#schema-QueuedResponse}

| Field | Type | Required | Description |
|---|---|---|---|
| `disposition` | `queued` or `handled` | yes |  |

### QuestionRequest {#schema-QuestionRequest}

Added 2026-10. One `ask_user` call waiting for an answer.

| Field | Type | Required | Description |
|---|---|---|---|
| `questionId` | string | yes |  |
| `questions` | array of object | yes |  |
| `questions[].header` | string | yes |  |
| `questions[].question` | string | yes |  |
| `questions[].options` | array of object | yes |  |
| `questions[].options[].label` | string | yes |  |
| `questions[].options[].description` | string | yes |  |
| `questions[].multiSelect` | boolean |  |  |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes | When an unanswered question gives up (the session's `approvalTimeoutMs`); the model is then told to decide itself. |

### QuestionAnswer {#schema-QuestionAnswer}

| Field | Type | Required | Description |
|---|---|---|---|
| `selected` | array of string | yes |  |
| `text` | string |  | A free-form answer. |

### QuestionAnswers {#schema-QuestionAnswers}

| Field | Type | Required | Description |
|---|---|---|---|
| `answers` | array of [QuestionAnswer](#schema-QuestionAnswer) | yes |  |

### ApprovalRequest {#schema-ApprovalRequest}

| Field | Type | Required | Description |
|---|---|---|---|
| `approvalId` | string | yes |  |
| `tool` | string | yes |  |
| `toolCallId` | string |  | pi's id of the call being gated: the `toolCallId` of its `tool_execution_start` event, so a client can attach the question to the call it already shows. Absent for checks that are not a model tool call (a slash command's `!` shell expansion). For a subagent's call it is the child session's id, which never appears in this stream; see `parentToolCallId`. |
| `parentToolCallId` | string |  | For a subagent's call, the parent's `task` call that started the subagent (that one is in this stream). For a call another tool issued, pi's parent call id. |
| `input` | object | yes |  |
| `summary` | string | yes | One-line description of the call. |
| `reason` | string | yes | Why the policy asks. |
| `mode` | [PermissionMode](#schema-PermissionMode) | yes | `sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume. |
| `suggestions` | array of string | yes | Rules that would auto-allow similar calls (used by allow-session / allow-project). |
| `rules` | array of string |  | What allow-session / allow-project stores when the decision names no `rule` or `rules`: every rule this call needs to be auto-allowed next time. A compound command gets one per segment that asked (`npm test \| tee out.txt` → `bash(npm test:*)`, `bash(tee out.txt:*)`); other calls the first suggestion. Show them all before the user chooses. Empty: no rule can cover the call, offer only allow-once. |
| `agent` | string |  | Set when a subagent makes the call. |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |

### ApprovalDecision {#schema-ApprovalDecision}

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | [ApprovalAction](#schema-ApprovalAction) | yes |  |
| `feedback` | string |  | Returned to the model with a denial. |
| `rule` | string |  | Rule to remember for allow-session / allow-project (default the request's `rules`). `edit(<workspace>)`, offered as a suggestion on in-workspace edit asks, allows every edit in the workspace for the session (protected paths and outside writes still ask) and is never persisted. |
| `rules` | array of string |  | Several rules to remember together for allow-session / allow-project (wins over `rule`; default the request's `rules`). |

### HarnessEvent {#schema-HarnessEvent}

The `data` of an event with `source: "harness"`: what `@venom/harness` emits (its
`HarnessEvent` type), plus `seq` and `source`. `type` says which. A field the harness names
`source` is sent as `origin`, since the envelope's `source` would overwrite it.
`test/contract.test.ts` derives these from the harness's TypeScript types and fails when
they drift. Fields marked "added 2026-10" are absent from older servers; treat any field
you don't know as forward-compatible.

Type: [PermissionEvent](#schema-PermissionEvent) or [ModeEvent](#schema-ModeEvent) or [SubagentsEvent](#schema-SubagentsEvent) or [TodosEvent](#schema-TodosEvent) or [HookEvent](#schema-HookEvent) or [DiagnosticEvent](#schema-DiagnosticEvent) or [NoticeEvent](#schema-NoticeEvent) or [EgressEvent](#schema-EgressEvent) or [InjectionEvent](#schema-InjectionEvent) or [LspEvent](#schema-LspEvent) or [FormatEvent](#schema-FormatEvent) or [EditToolEvent](#schema-EditToolEvent) or [TestEditEvent](#schema-TestEditEvent) or [UnseenRemovalEvent](#schema-UnseenRemovalEvent) or [CheckpointEvent](#schema-CheckpointEvent) or [GuardEvent](#schema-GuardEvent) or [CompactionEvent](#schema-CompactionEvent) or [AgentEvent](#schema-AgentEvent) or [SpanEvent](#schema-SpanEvent) or [MemoryEvent](#schema-MemoryEvent) or [CallEvent](#schema-CallEvent) or [CacheBreakEvent](#schema-CacheBreakEvent) or [WorkflowEvent](#schema-WorkflowEvent) or [EscalationEvent](#schema-EscalationEvent)

### AuditRecord {#schema-AuditRecord}

One permission gate decision, as written to the audit log.

| Field | Type | Required | Description |
|---|---|---|---|
| `ts` | string (date-time) | yes |  |
| `sessionId` | string |  |  |
| `cwd` | string | yes |  |
| `mode` | string | yes |  |
| `tool` | string | yes |  |
| `toolCallId` | string |  | pi's id of the gated call, when the decision was about a model tool call. |
| `summary` | string | yes |  |
| `verdict` | `allow` or `ask` or `deny` | yes | The policy's verdict before any human input. |
| `outcome` | `allow` or `deny` | yes | The final outcome after approval (the verdict when none was needed). |
| `via` | string | yes | How the outcome was reached (policy, user choice, hook, headless default, `loop-guard`, `injection-detector`, ...). |
| `reason` | string | yes |  |
| `rule` | string |  |  |
| `agent` | string |  | Set for a subagent's call. |
| `hint` | string |  | How to allow it, for denials that configuration can lift (egress). |
| `sandboxed` | boolean |  | bash only. Whether the command runs inside the OS sandbox. |
| `network` | `all` or `none` or `allowlist` |  | bash only, when sandboxed. The network policy it runs under. |
| `source` | `user` |  | `user` for a command the person typed themselves (`!cmd`); absent for the model's own calls. |

### SubagentProgress {#schema-SubagentProgress}

| Field | Type | Required | Description |
|---|---|---|---|
| `index` | integer | yes |  |
| `agent` | string | yes |  |
| `description` | string | yes |  |
| `status` | `queued` or `running` or `done` or `error` | yes |  |
| `lastAction` | string |  |  |
| `toolCalls` | integer | yes |  |

### TodoItem {#schema-TodoItem}

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `content` | string | yes |  |
| `status` | `pending` or `in_progress` or `completed` or `cancelled` | yes |  |

### PermissionEvent {#schema-PermissionEvent}

An audit record for every permission gate decision.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"permission"` | yes |  |
| `record` | [AuditRecord](#schema-AuditRecord) | yes | One permission gate decision, as written to the audit log. |

### ModeEvent {#schema-ModeEvent}

The permission mode changed (a client's `PUT .../mode`, or a `/plan` handoff).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"mode"` | yes |  |
| `mode` | [PermissionMode](#schema-PermissionMode) | yes | `sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume. |
| `previous` | [PermissionMode](#schema-PermissionMode) | yes | `sudo` (added 2026-10) is session-only: no approval prompts, bash without the OS sandbox. A client may ask for it only when the server was started with `--allow-sudo` (else 403 `sudo_forbidden`), and an organisation policy that limits modes or requires the sandbox refuses it (403 `policy_forbidden`). It is never saved or restored on resume. |

### SubagentsEvent {#schema-SubagentsEvent}

Progress of the subagents one `task` call (`toolCallId`) started.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"subagents"` | yes |  |
| `toolCallId` | string | yes |  |
| `progress` | array of [SubagentProgress](#schema-SubagentProgress) | yes |  |

### TodosEvent {#schema-TodosEvent}

The `todo` tool's list, in full, after each change.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"todos"` | yes |  |
| `todos` | array of [TodoItem](#schema-TodoItem) | yes |  |

### HookEvent {#schema-HookEvent}

A Claude Code hook's message for the user.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"hook"` | yes |  |
| `event` | string | yes | The hook event (`PreToolUse`, `PreCompact`, ...). |
| `message` | string | yes |  |

### DiagnosticEvent {#schema-DiagnosticEvent}

Something the harness could not do (a config file, an MCP server, a checkpoint), for logs.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"diagnostic"` | yes |  |
| `message` | string | yes |  |

### NoticeEvent {#schema-NoticeEvent}

A slash command's output in a session without a UI (`/undo`, `/redo`, `/checkpoints`, `/context`, `/cost`, `/review`).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"notice"` | yes |  |
| `message` | string | yes |  |
| `level` | `info` or `warning` or `error` | yes |  |

### EgressEvent {#schema-EgressEvent}

The egress proxy refused a sandboxed command's connection (also audited).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"egress"` | yes |  |
| `host` | string | yes |  |
| `port` | integer | yes |  |
| `method` | string | yes |  |
| `reason` | string | yes |  |
| `hint` | string | yes | The setting that would allow it. |

### InjectionEvent {#schema-InjectionEvent}

Advisory: a tool result (or a project memory file, `tool: "memory"`) has text shaped like a prompt injection. Nothing was blocked; the model got a note. Also audited.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"injection"` | yes |  |
| `tool` | string | yes |  |
| `origin` | string | yes | Where the text came from (a path, a URL, the command). The harness calls it `source`; servers before 2026-10 overwrote it with the envelope's `source` and sent no `origin`. |
| `kinds` | array of `override` or `fetch-exec` or `exfil` or `secret-access` or `push` or `imperative-run` or `no-confirm` or `agent-addressed` or `setup-script` or `role-spoof` or `tool-call` or `exfil-image` or `hidden-text` or `conceal` | yes |  |
| `excerpt` | string | yes |  |

### LspEvent {#schema-LspEvent}

Language-server diagnostics collected after an edit/write: which server, how long, how many errors, whether a block was appended to the result, or why nothing came back (`skipped`).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"lsp"` | yes |  |
| `tool` | string | yes |  |
| `path` | string | yes |  |
| `server` | string |  |  |
| `ms` | integer | yes |  |
| `errors` | integer | yes |  |
| `reported` | boolean | yes |  |
| `skipped` | `no-server` or `failed` or `timeout` or `disposed` |  |  |
| `dependents` | object |  | Added 2026-10. Set when the edit changed the file's surface and the files that depend on it were checked: `checked` files asked, `files` of them with `errors` errors, `ms` of the total `ms`, or why the check stopped (`skipped`). |
| `dependents.checked` | integer | yes |  |
| `dependents.files` | integer | yes |  |
| `dependents.errors` | integer | yes |  |
| `dependents.ms` | integer | yes |  |
| `dependents.skipped` | `timeout` or `failed` |  |  |

### FormatEvent {#schema-FormatEvent}

The project's formatter ran on a file after an edit/write (`changed`: it rewrote the file), failed (`failure`; the edit is kept), or was skipped (`skipped`).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"format"` | yes |  |
| `tool` | string | yes |  |
| `path` | string | yes |  |
| `formatter` | string | yes |  |
| `ms` | integer | yes |  |
| `changed` | boolean | yes |  |
| `failure` | `exit` or `timeout` or `sandbox` or `spawn` or `too-large` or `unreadable` or `aborted` |  |  |
| `skipped` | `no-binary` or `no-sandbox` |  |  |

### EditToolEvent {#schema-EditToolEvent}

Added 2026-10. The file-editing tools chosen for the session's model: which of `edit` / `apply_patch` it is offered, the model and the concrete model it resolved to, and why.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"edit-tool"` | yes |  |
| `tools` | array of `edit` or `apply_patch` | yes |  |
| `model` | string |  |  |
| `target` | string |  |  |
| `reason` | string | yes |  |

### TestEditEvent {#schema-TestEditEvent}

Added 2026-10. An `edit`/`apply_patch` of a test file changed only assertions' expected values; the result got an advisory note. Nothing was blocked.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"test-edit"` | yes |  |
| `tool` | string | yes |  |
| `paths` | array of string | yes |  |
| `changes` | integer | yes |  |

### UnseenRemovalEvent {#schema-UnseenRemovalEvent}

Added 2026-10. A `write` over an existing file removed lines the model never saw in any tool result or input this session; the result got a note listing them. Nothing was blocked.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"unseen-removal"` | yes |  |
| `path` | string | yes |  |
| `lines` | integer | yes |  |

### CheckpointEvent {#schema-CheckpointEvent}

A file checkpoint was recorded (`snapshot`), or files were undone, redone or restored.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"checkpoint"` | yes |  |
| `action` | `snapshot` or `undo` or `redo` or `restore` | yes |  |
| `files` | integer | yes | Files the turn changed (snapshot), or files written or removed on disk (the others). |
| `ms` | integer | yes |  |
| `summary` | string |  |  |
| `paths` | array of string |  | Absolute paths written or removed on disk (undo, redo, restore). |

### GuardEvent {#schema-GuardEvent}

A runaway guard fired: `repeat` (the same call `count` times in a row), `failures` (added 2026-10: the last `count` bash calls failed with the same error, whatever their arguments; posted to the inbox when headless), `reread` (a file read again unchanged), `tool-limit` (the run's tool-call ceiling), `turn-limit` (a subagent's `maxTurns`), `overthink` (added 2026-10: a nudge to act after reasoning or planning without acting; `outcome` is `nudge`, `count` the reasoning tokens since the last action), `stuck` (added 2026-10: the session's stuck detector, a file edited back and forth or the same call failing the same way; `allow` after a gear shift or the user's yes, `nudge` headless, `deny` when the run was stopped). `outcome` says whether the call ran. Also audited (`via: "loop-guard"`).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"guard"` | yes |  |
| `guard` | `repeat` or `failures` or `reread` or `tool-limit` or `turn-limit` or `time-limit` or `cost-limit` or `overthink` or `stuck` | yes |  |
| `tool` | string | yes |  |
| `summary` | string | yes |  |
| `count` | integer | yes |  |
| `limit` | integer | yes |  |
| `outcome` | `allow` or `deny` or `nudge` | yes |  |
| `decidedBy` | `user` or `headless` or `limit` | yes | `headless` (no UI: denied) is what a server session gets. |

### CacheBreakEvent {#schema-CacheBreakEvent}

Added 2026-10-13. A request whose cached tokens fell under half of the prompt prefix it shared with the previous request (`venom-cache-break`); also counted by `/cost`.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"cache-break"` | yes |  |
| `cause` | `model` or `effort` or `compaction` or `mask` or `tools` or `system` or `idle` or `prefix` or `provider` | yes | The guessed cause, most specific first; `provider` when nothing visible changed. |
| `model` | string | yes | `provider/model` |
| `expected` | integer | yes | Tokens shared with the previous request. |
| `cached` | integer | yes |  |
| `lost` | integer | yes | Shared tokens re-sent uncached. |
| `idleMs` | integer | yes | From the previous response's end to this request. |
| `message` | integer |  | `prefix`: the index of the first message sent differently. |

### EscalationEvent {#schema-EscalationEvent}

Added 2026-10. A fast-tier subagent's task was re-run on a stronger tier after its work failed a check (auto-escalation, docs/configuration.md → Gears): why, where it went, whether the re-run passed and its list-price cost. UI and accounting only; the parent model reads the task result.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"escalation"` | yes |  |
| `escalation` | [EscalationRecord](#schema-EscalationRecord) | yes |  |

### EscalationRecord {#schema-EscalationRecord}

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | The escalation's id (esc_ + 16 hex), as x-venom-escalation carries it. |
| `reason` | `tests_failed` or `lint_failed` or `typecheck_failed` or `tool_errors` or `verifier_rejected` | yes |  |
| `agent` | string | yes | The subagent's type. |
| `description` | string |  |  |
| `from` | string |  | The model the first attempt ran on. |
| `to` | string | yes | What the re-run ran on: a tier (smart, main) or the model id the gear names. |
| `model` | string |  | The model the re-run answered with. |
| `ok` | boolean | yes | The re-run passed what the first attempt failed. |
| `extraCostUsd` | number | yes | The re-run's list-price cost. |

### WorkflowEvent {#schema-WorkflowEvent}

Added 2026-10. One progress step of a `/workflow run` (docs/workflows.md) and the line the TUI shows for it; `status` on the `end` step.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"workflow"` | yes |  |
| `kind` | `start` or `phase` or `log` or `agent_start` or `agent_end` or `end` | yes |  |
| `line` | string | yes |  |
| `status` | `completed` or `error` or `budget` or `aborted` |  |  |

### CompactionEvent {#schema-CompactionEvent}

venom's context compaction: `mask` replaced old tool outputs with stubs, `summarize` had `model` summarize the history.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"compaction"` | yes |  |
| `stage` | `mask` or `summarize` or `failed` | yes | `failed`: pi reported a failed compaction (`errorMessage`, `aborted`, `failures`). |
| `tokensBefore` | integer | yes |  |
| `tokensAfter` | integer | yes |  |
| `masked` | integer | yes | Tool results masked (mask stage). |
| `spilled` | integer |  | Of those, how many had their full output saved to a spill file the stub names. |
| `reason` | `auto` or `manual` or `threshold` or `overflow` |  | What started a summary. |
| `contextWindow` | integer | yes |  |
| `trigger` | integer | yes |  |
| `model` | string |  | The summary model (summarize stage). |
| `errorMessage` | string |  | Added 2026-10. Why compaction failed (failed stage). |
| `aborted` | boolean |  | Added 2026-10. It was cancelled rather than failed (failed stage). |
| `failures` | integer |  | Added 2026-10. Consecutive automatic compaction failures in the session after this one; a successful compaction resets it (failed stage). |
| `unseen` | array of string |  | Added 2026-10. Tool-call ids of results this step masked before the model saw them (mask stage): the re-read guard does not count those reads. |
| `seen` | array of string |  | Added 2026-10. Tool-call ids of the other results this step masked, ones the model had seen (mask stage): their lines are out of view, so the re-read guard no longer counts them as given. |
| `handles` | array of string |  | Added 2026-10. Blob handles (`blob:sha256:…`) of the results this step masked (ADR 0010). |
| `structural` | integer |  | Added 2026-10. Of the masked results, how many got a structural view in their stub (ADR 0010). |
| `cold` | boolean |  | Added 2026-10. Done at a cold moment (the provider's prompt cache had expired): the rewrite cost no cached prefix, and it may have run below the trigger. |
| `idle` | boolean |  | Added 2026-10. Done while the user was idle, against the model's soft context-quality threshold (idle compaction). |
| `relevance` | object |  | Added 2026-10. The summary's relevance pass (summarize stage, ADR 0016), when it ran: the decider that answered, the span's tool results it judged, how many went to the summary model as one line (`dropped`) or with more of their text (`full`), lines pinned, wall time, requests. |
| `relevance.provider` | string | yes |  |
| `relevance.model` | string | yes |  |
| `relevance.judged` | integer | yes |  |
| `relevance.dropped` | integer | yes |  |
| `relevance.full` | integer | yes |  |
| `relevance.pinned` | integer | yes |  |
| `relevance.latencyMs` | integer | yes |  |
| `relevance.requests` | integer | yes |  |

### AgentUsage {#schema-AgentUsage}

Added 2026-10. Tokens and cost an agent process used (ADR 0009).

| Field | Type | Required | Description |
|---|---|---|---|
| `input` | integer | yes |  |
| `output` | integer | yes |  |
| `cached` | integer | yes |  |
| `cost` | number | yes |  |

### AgentQuanta {#schema-AgentQuanta}

Added 2026-10. Units an agent consumes (a quantum, or what it used of one).

| Field | Type | Required | Description |
|---|---|---|---|
| `turns` | integer |  |  |
| `toolCalls` | integer |  |  |
| `tokens` | integer |  |  |
| `wallMs` | integer |  |  |

### AgentExitStatus {#schema-AgentExitStatus}

Added 2026-10. Why an agent process exited: `done`, `turn-limit` (partial report), `terminated` (SIGTERM, partial report), `killed` (SIGKILL), `crashed`, `budget` (the tree's quota ran out), `orphaned` (its parent was gone; the report went to the tree root), `truncated` (its final reply was cut off at the output-token limit, partial report; added 2026-11).

| Field | Type | Required | Description |
|---|---|---|---|
| `pid` | integer | yes |  |
| `reason` | `done` or `turn-limit` or `terminated` or `killed` or `crashed` or `budget` or `time-limit` or `orphaned` or `truncated` | yes |  |
| `report` | string | yes |  |
| `partial` | boolean | yes |  |
| `usage` | [AgentUsage](#schema-AgentUsage) | yes | Added 2026-10. Tokens and cost an agent process used (ADR 0009). |
| `turns` | integer | yes |  |
| `toolCalls` | integer | yes |  |
| `durationMs` | integer | yes |  |
| `error` | string |  |  |
| `outcome` | `done` or `exhausted` or `blocked` or `stopped` |  | Added 2026-10 (VEN-49). The reason's outcome class, set for a subagent's exit. |
| `hint` | string |  | Added 2026-10 (VEN-49). A short next-step hint for whoever reads the report. |

### SwitchModelRequest {#schema-SwitchModelRequest}

Added 2026-10. `POST …/agents/{pid}/model`.

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | A model id of the session's provider (e.g. `venom-smart`), or `provider/id`. |

### SwitchModelResult {#schema-SwitchModelResult}

Added 2026-10.

| Field | Type | Required | Description |
|---|---|---|---|
| `pid` | integer | yes |  |
| `model` | string | yes | The model id switched to. |
| `applied` | `now` or `turn-boundary` | yes |  |
| `cacheLost` | `true` | yes | The new model has no cached copy of the session's prompt. |

### ProcInfo {#schema-ProcInfo}

Added 2026-10. One row of the agent process table (ADR 0009): the session's main agent is the tree root (`tree`), `task` children are its children. A `blocked` process always has a `wait` reason.

| Field | Type | Required | Description |
|---|---|---|---|
| `pid` | integer | yes |  |
| `ppid` | integer |  |  |
| `tree` | integer | yes |  |
| `name` | string | yes |  |
| `class` | `interactive` or `batch` or `idle` | yes |  |
| `weight` | number | yes |  |
| `effectiveWeight` | number | yes | The weight the scheduler uses, after priority inheritance. |
| `state` | `new` or `ready` or `running` or `blocked` or `zombie` or `reaped` | yes |  |
| `wait` | object |  |  |
| `wait.reason` | `model-slot` or `approval` or `tool` or `child` or `lock` or `mailbox` or `paused` | yes |  |
| `wait.detail` | string | yes |  |
| `wait.sinceMs` | number | yes |  |
| `model` | string | yes |  |
| `usage` | [AgentUsage](#schema-AgentUsage) | yes | Added 2026-10. Tokens and cost an agent process used (ADR 0009). |
| `turns` | integer | yes |  |
| `toolCalls` | integer | yes |  |
| `quantaUsed` | [AgentQuanta](#schema-AgentQuanta) | yes | Added 2026-10. Units an agent consumes (a quantum, or what it used of one). |
| `restarts` | integer | yes |  |
| `locks` | object | yes |  |
| `locks.held` | array of string | yes |  |
| `locks.waiting` | string |  |  |
| `liveness` | `alive` or `slow` or `hung` | yes |  |
| `lastAction` | string |  | The latest tool call as one line (`edit src/a.ts`, `bash: npm test`, `code_search refs Foo`). |
| `agent` | [AgentMeta](#schema-AgentMeta) |  | Added 2026-10. Who a process is, for a live agents view: the main agent is `main` / `orchestrator`, a `task` subagent its agent definition's name and the role derived from it (frontmatter `role:`, else its tools and name), an exec session `exec` / `shell`. |
| `idle` | boolean |  | Added 2026-10. The main agent between prompts: `running` in the table for the session's life, waiting for the user. |
| `latencyMs` | object | yes |  |
| `latencyMs.p50` | number | yes |  |
| `latencyMs.p95` | number | yes |  |
| `startedAt` | number | yes |  |
| `exit` | [AgentExitStatus](#schema-AgentExitStatus) |  | Added 2026-10. Why an agent process exited: `done`, `turn-limit` (partial report), `terminated` (SIGTERM, partial report), `killed` (SIGKILL), `crashed`, `budget` (the tree's quota ran out), `orphaned` (its parent was gone; the report went to the tree root), `truncated` (its final reply was cut off at the output-token limit, partial report; added 2026-11). |

### AgentMeta {#schema-AgentMeta}

Added 2026-10. Who a process is, for a live agents view: the main agent is `main` / `orchestrator`, a `task` subagent its agent definition's name and the role derived from it (frontmatter `role:`, else its tools and name), an exec session `exec` / `shell`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes |  |
| `role` | `orchestrator` or `planner` or `explorer` or `writer` or `reviewer` or `tester` or `researcher` or `shell` or `agent` | yes |  |
| `color` | string |  | The agent file's `color:` (Claude Code's field), as written. |
| `description` | string |  | The `task` description, or the exec command. |
| `tier` | string |  | The model tier the agent definition names (`fast`, `smart`, `inherit`). |

### AgentEvent {#schema-AgentEvent}

Added 2026-10. An agent process changed (ADR 0009): its `ps` row, and the state transition when there was one. At most one per process per 250 ms, except exits.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"agent"` | yes |  |
| `info` | [ProcInfo](#schema-ProcInfo) | yes | Added 2026-10. One row of the agent process table (ADR 0009): the session's main agent is the tree root (`tree`), `task` children are its children. A `blocked` process always has a `wait` reason. |
| `transition` | object |  |  |
| `transition.from` | `new` or `ready` or `running` or `blocked` or `zombie` or `reaped` | yes |  |
| `transition.to` | `new` or `ready` or `running` or `blocked` or `zombie` or `reaped` | yes |  |

### Span {#schema-Span}

Added 2026-10. A trace span (OpenTelemetry-style field names): `traceId` is the agent tree, a child's root span's parent is the parent's `task` tool span.

| Field | Type | Required | Description |
|---|---|---|---|
| `traceId` | string | yes |  |
| `spanId` | string | yes |  |
| `parentSpanId` | string |  |  |
| `pid` | integer | yes |  |
| `name` | string | yes |  |
| `kind` | `turn` or `tool` or `wait` or `signal` | yes |  |
| `start` | number | yes |  |
| `end` | number |  |  |
| `attrs` | map of string or number or boolean | yes |  |

### SpanEvent {#schema-SpanEvent}

Added 2026-10. A trace span ended (a turn, a tool call, a wait or a signal; ADR 0009).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"span"` | yes |  |
| `span` | [Span](#schema-Span) | yes | Added 2026-10. A trace span (OpenTelemetry-style field names): `traceId` is the agent tree, a child's root span's parent is the parent's `task` tool span. |

### MemoryEvent {#schema-MemoryEvent}

Added 2026-10. The context memory layer acted (ADR 0010): a `thrash` detected, `load-control` applied, a `fault` (a masked item read again), a blob `gc`, or `pin` (a summary dropped pinned facts and venom put them back; `pin` added 2026-10).

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"memory"` | yes |  |
| `event` | `thrash` or `load-control` or `fault` or `gc` or `pin` | yes |  |
| `detail` | string | yes |  |
| `handles` | array of string |  |  |

### CallEvent {#schema-CallEvent}

Added 2026-10. One model request finished (the call meter): the agent's own turn, a subagent's (`call.agent`, `call.role`), or one of venom's side requests (`call.kind`). UI only; nothing of it reaches the model.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `"harness"` | yes |  |
| `type` | `"call"` | yes |  |
| `call` | [CallRecord](#schema-CallRecord) | yes | Added 2026-10. One model request: the model asked for and the one that answered, tokens and list-price cost (`config/prices.yaml`; 0 and `priced: false` for a local or unpriced model). |

### CallRecord {#schema-CallRecord}

Added 2026-10. One model request: the model asked for and the one that answered, tokens and list-price cost (`config/prices.yaml`; 0 and `priced: false` for a local or unpriced model).

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | `turn` or `auto-classifier` or `decide` or `vision` or `compaction` or `hook` or `keepwarm` or `reflex` or `btw` | yes |  |
| `agent` | string |  | The subagent's type; absent for the main agent. |
| `role` | string |  | The subagent's role (the agents panel's colour). |
| `pid` | integer |  |  |
| `requested` | string |  | The model id the request named (an alias such as venom-default). |
| `served` | string |  | The model that answered (x-venom-model, else the body's model). |
| `upstream` | string |  | The orchestrator upstream that answered (x-venom-upstream). |
| `fallbackReason` | string |  | Why the orchestrator did not serve the request with the first target it tried (x-venom-fallback): reason codes, comma-separated, e.g. 429_quota. Absent when it did. Added 2026-10. |
| `autoTier` | string |  | The tier Venom Cloud's venom-auto picked (x-venom-auto-tier: cheap, balanced, premium). Absent otherwise. Added 2026-10. |
| `autoEscalated` | string |  | Why venom-auto retried a cheap-tier answer on the next tier within the request (x-venom-auto-escalated's reason: provider_error, empty, truncated, filtered). Absent otherwise. Added 2026-10. |
| `escalation` | string |  | The request belongs to a subagent task re-run on a stronger tier (auto-escalation): the reason code. Added 2026-10. |
| `input` | integer | yes | Prompt tokens, the cached share included. |
| `cached` | integer | yes |  |
| `cacheWrite` | integer | yes |  |
| `output` | integer | yes |  |
| `reasoning` | integer |  | Of output, reasoning tokens, when reported. |
| `costUsd` | number | yes |  |
| `priced` | boolean | yes |  |
| `ms` | integer | yes |  |
| `error` | string |  |  |

### Event {#schema-Event}

One SSE `data` payload. `source` says where it came from:

- `session`: pi's session events, in pi's JSON-stream shape (`message_update` carries only
  the delta, no cumulative snapshot): `agent_start`, `turn_start`, `message_start`,
  `message_update`, `message_end`, `tool_execution_start`, `tool_execution_update`,
  `tool_execution_end` (the three carry pi's `parentToolCallId` for a call another tool made),
  `turn_end`, `agent_end`, `agent_settled`, `queue_update`, `compaction_start`,
  `compaction_end`, `auto_retry_start`, `auto_retry_end`, `summarization_retry_scheduled`,
  `summarization_retry_attempt_start` (its own `source`, `compaction` or `branchSummary`,
  is sent as `origin`), `summarization_retry_finished`, `entry_appended` (a session
  entry was saved), `session_info_changed` (the session's name), `thinking_level_changed`,
  `bash_execution_update` (output of a user `!` command). pi may add more: skip types you
  don't know.
- `harness`: what `@venom/harness` emits, each with a schema in `HarnessEvent`: `permission`
  (an audit record for every gate decision), `mode`, `todos`, `subagents` (progress of the
  `task` tool), `compaction` (venom's mask/summarize step), `egress` (a sandboxed connection
  the egress proxy refused), `lsp` (language-server diagnostics collected after an
  edit/write, and for the files that depend on it), `format` (the project's formatter ran on
  an edited file), `edit-tool` (which file-editing tools the model got), `test-edit` (an
  edit changed only a test's expected values; advisory), `unseen-removal` (a write removed
  lines the model never read; advisory), `checkpoint` (a file checkpoint was
  recorded, or files were undone, redone or restored), `guard` (a runaway guard fired),
  `injection` (advisory: a tool result looks like a prompt injection), `hook`, `diagnostic`,
  `notice` (a slash command's output in a session without a UI: `/undo`, `/redo`,
  `/checkpoints`, `/context`, `/cost`), `agent` (an agent process's state and `ps` row,
  added 2026-10), `span` (a trace span ended, added 2026-10), `memory` (the context memory
  layer acted, added 2026-10), `call` (one model request: model asked for and served,
  tokens, cost; added 2026-10), `cache-break` (a request lost most of its cached prompt prefix,
  with the guessed cause; added 2026-10-13), `workflow` (a `/workflow run` progress line, added 2026-10),
  `escalation` (a fast-tier subagent's task was re-run on a stronger tier, added 2026-10).
- `server`: `approval_request`, `approval_resolved` (`by`: `client`, `timeout`, `abort`, `mode`,
  `close`), `question_request`, `question_resolved` (`answered`, `by` as for approvals; added 2026-10), `prompt_end` (`promptId`, `text`, `error?`, `truncated?` added 2026-11), `events_dropped`, `session_closed`.

| Field | Type | Required | Description |
|---|---|---|---|
| `seq` | integer | yes |  |
| `source` | `session` or `harness` or `server` | yes |  |
| `type` | string | yes |  |
