Harness server API
Every operation of venom serve's HTTP API (66 operations), with parameters, bodies, responses, schemas and a curl line each.
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 |
Liveness and capacity. No auth. |
| GET | /v1/openapi.yaml |
This document. No auth. |
| POST | /v1/auth/proof |
The server proves it holds the token, before a client sends it. No auth. Added 2026-10. |
| GET | /v1/sessions |
List open sessions. |
| POST | /v1/sessions |
Create a harness session in a directory under one of the server's allowed roots. |
| GET | /v1/saved-sessions |
Sessions saved with persist, newest first, that a new session can resume. Added 2026-10. |
| GET | /v1/projects |
The folders a session can open in, each with its git branch. Added 2026-11. |
| GET | /v1/workflows |
The workflow scripts of a workspace, by name. Added 2026-10. |
| GET | /v1/inbox |
The open inbox items, most urgent first. Added 2026-10. |
| GET | /v1/inbox/{id} |
One open inbox item. Added 2026-10. |
| POST | /v1/inbox/{id}/resolve |
Answer an inbox item. Added 2026-10. |
| GET | /v1/ide |
The browser IDE page. No auth. Added 2026-10. |
| GET | /v1/mobile |
The phone approval inbox page. No auth. Added 2026-10. |
| POST | /v1/mobile/pairings |
A one-time code that pairs a phone with the inbox page. Added 2026-10. |
| POST | /v1/mobile/session |
Trade a pairing code for the phone's cookie. No auth (the code is the credential). Added 2026-10. |
| DELETE | /v1/mobile/session |
Unpair this phone (forget its cookie). Added 2026-10. |
| GET | /v1/mobile/inbox |
What the phone inbox shows. Added 2026-10. |
| GET | /v1/mobile/events |
Server-Sent Events of the phone inbox. Added 2026-10. |
| POST | /v1/mobile/answer |
Answer an inbox item or a served session's approval from the phone. Added 2026-10. |
| GET | /v1/evidence |
The evidence bundle of a repository's change. Added 2026-10. |
| GET | /v1/sessions/{sessionId} |
Session state. |
| DELETE | /v1/sessions/{sessionId} |
Close a session. |
| POST | /v1/sessions/import |
Take over a session handed off from another machine (ADR 0024). Added 2026-10. |
| POST | /v1/sessions/{sessionId}/handoff |
Hand a persisted session to another machine (ADR 0024). Added 2026-10. |
| POST | /v1/sessions/{sessionId}/prompt |
Send a prompt (pi's prompt command). |
| POST | /v1/sessions/{sessionId}/steer |
Queue a steering message, delivered after the current turn's tool calls (pi's steer). |
| POST | /v1/sessions/{sessionId}/follow_up |
Queue a follow-up, delivered when the agent would otherwise stop (pi's follow_up). |
| POST | /v1/sessions/{sessionId}/abort |
Abort the running turn and wait until the session is idle (pi's abort). |
| PUT | /v1/sessions/{sessionId}/mode |
Set the permission mode. Emits a mode event. |
| POST | /v1/sessions/{sessionId}/agents/{pid}/model |
Switch one agent's model (ADR 0009 §8). |
| GET | /v1/sessions/{sessionId}/events |
Server-Sent Events for one session. |
| GET | /v1/sessions/{sessionId}/approvals |
Pending approval requests (the same objects as the approval_request events). |
| POST | /v1/sessions/{sessionId}/approvals/{approvalId} |
Answer a pending approval request. |
| GET | /v1/sessions/{sessionId}/questions |
Pending ask_user questions (the same objects as the question_request events). Added 2026-10. |
| POST | /v1/sessions/{sessionId}/questions/{questionId} |
Answer a pending ask_user question. Added 2026-10. |
| GET | /v1/sessions/{sessionId}/checkpoints |
The session's turn checkpoints (file snapshots), oldest first. Added 2026-10. |
| GET | /v1/sessions/{sessionId}/changes |
Each file one turn changed, with its text before and after. Added 2026-10. |
| GET | /v1/sessions/{sessionId}/files |
One directory of the session's workspace. Added 2026-10. |
| GET | /v1/sessions/{sessionId}/file |
A text file of the session's workspace. Added 2026-10. |
| PUT | /v1/sessions/{sessionId}/file |
Write a text file of the session's workspace. Added 2026-10. |
| DELETE | /v1/sessions/{sessionId}/file |
Delete a file of the session's workspace. Added 2026-10. |
| GET | /v1/sessions/{sessionId}/transcript |
The session's conversation so far, as text. Added 2026-10. |
| GET | /v1/sessions/{sessionId}/agents |
The session's agent processes (ps), with ages and rates. Added 2026-10. |
| GET | /v1/sessions/{sessionId}/agents/{pid} |
One agent process (lifetime rates). Added 2026-10. |
| POST | /v1/sessions/{sessionId}/agents/{pid}/signal |
Send a signal to an agent process. Added 2026-10. |
| GET | /v1/board |
The agent factory's health, the issue board plus the merge gate. Added 2026-10. |
| GET | /v1/gears |
The gears the server's venom.yaml offers, for an editor's gear switcher. Added 2026-10. |
| GET | /v1/schedules |
The scheduled jobs (venom.yaml schedules:) with their next and last run. Added 2026-10. |
| GET | /v1/schedules/runs |
Runs of scheduled jobs, newest first. Added 2026-10. |
| POST | /v1/schedules/{name}/run |
Start a job now, outside its schedule. Added 2026-10. |
| GET | /v1/schedules/runs/{runId}/output |
One file a browser task's run produced. Added 2026-10. |
| GET | /v1/calls |
Voice calls, live and stored, newest first. Added 2026-11. |
| POST | /v1/calls |
Start a call. Added 2026-11. |
| GET | /v1/calls/{callId} |
One call with its compliance events, handoff and per-turn metrics. Added 2026-11. |
| GET | /v1/calls/{callId}/events |
The call's events as SSE. Added 2026-11. |
| GET | /v1/calls/{callId}/transcript |
Caller finals and the agent's heard text. Added 2026-11. |
| GET | /v1/calls/{callId}/recording |
The call's recording, stereo PCM16 8 kHz WAV (caller left, agent right). Added 2026-11. |
| POST | /v1/calls/{callId}/hangup |
Hang up a live call. Added 2026-11. |
| POST | /v1/calls/{callId}/transfer |
A supervisor's handoff of a live call to the agent's handoff target. Added 2026-11. |
| GET | /v1/calls/{callId}/media |
The browser test line's media WebSocket. Ticket-authenticated. Added 2026-11. |
| GET | /v1/voice/agents |
The configured voice agents. Added 2026-11. |
| POST | /v1/voice/twilio/incoming |
Twilio's voice webhook. Public; checked by X-Twilio-Signature. Added 2026-11. |
| POST | /v1/voice/twilio/status |
Twilio's call status callback (answering-machine results). Public; signature-checked. Added 2026-11. |
| GET | /v1/voice/twilio/whisper/{token} |
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 |
Twilio Media Streams WebSocket. Public; single-use ticket from the TwiML. Added 2026-11. |
| GET | /v1/voice/clips/{clip} |
A whisper clip as WAV (<token>.wav). Public; single-use token, 2 min. Added 2026-11. |
/v1/health
Liveness and capacity. No auth.
GET /v1/health · operationId getHealth
No authentication.
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Server is up. | application/json Health |
curl 'http://127.0.0.1:8790/v1/health'/v1/openapi.yaml
This document. No auth.
GET /v1/openapi.yaml · operationId getOpenApi
No authentication.
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The OpenAPI document. | application/yaml string |
curl 'http://127.0.0.1:8790/v1/openapi.yaml'/v1/auth
The server proves it holds the token, before a client sends it. No auth. Added 2026-10.
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
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The proof. | application/json AuthProof |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
curl -X POST 'http://127.0.0.1:8790/v1/auth/proof' \
-H 'Content-Type: application/json' -d '{...}'/v1/sessions
List open sessions.
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 |
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.
POST /v1/sessions · operationId createSession
Requires Authorization: Bearer $VENOM_SERVER_TOKEN.
Request body (required)
application/json: CreateSessionRequest
Responses
| Status | Description | Body |
|---|---|---|
| 201 | Session created. | application/json 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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 404 | resume names no saved session of this workspace (saved_session_not_found). |
application/json Error |
| 409 | resume names a saved session that is already open on this server (saved_session_open). |
application/json Error |
| 429 | The session limit is reached (too_many_sessions). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>'Close a session.
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 |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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.
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 |
| 400 | Not a bundle, a failed checksum, a different commit, a dirty workspace (import_failed), or a bad cwd (bad_request). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 403 | cwd is not inside an allowed root (root_not_allowed). |
application/json Error |
| 409 | A stale bundle: this machine already has the session at an equal or newer lease epoch (import_failed). |
application/json Error |
| 413 | The bundle is larger than the server accepts (body_too_large). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json 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 |
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).
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
Responses
| Status | Description | Body |
|---|---|---|
| 202 | Accepted. | application/json PromptAccepted |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json 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 |
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).
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
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Queued or handled. | application/json QueuedResponse |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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).
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
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Queued or handled. | application/json QueuedResponse |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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).
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 |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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.
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 | 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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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).
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
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The switch is scheduled, or done when applied is now. |
application/json 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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 404 | No such session (session_not_found), or no live agent with that pid in it (agent_not_found). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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).
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 |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/sessions/<sessionId>/approvals'Answer a pending approval request.
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
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such pending approval: unknown, already answered, timed out, or aborted (approval_not_found). |
application/json Error |
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.
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 |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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.
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
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such pending question: unknown, already answered, timed out, or aborted (question_not_found). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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.
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 |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
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.
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 |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 404 | No such session (session_not_found) or path (file_not_found). |
application/json Error |
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.
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 |
| 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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 404 | No such session (session_not_found) or path (file_not_found). |
application/json Error |
| 413 | Over 512 KiB (too_large). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 404 | No such session (session_not_found) or path (file_not_found). |
application/json Error |
| 413 | Over 512 KiB (too_large). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 404 | No such session (session_not_found) or path (file_not_found). |
application/json Error |
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.
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 |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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.
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 |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or route (not_found). |
application/json Error |
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.
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 |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No such session (session_not_found) or process (agent_not_found: never spawned, or already reaped). |
application/json Error |
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.
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
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Delivered. | application/json SignalResult |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
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
Sessions saved with persist, newest first, that a new session can resume. Added 2026-10.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 403 | cwd is not inside an allowed root (root_not_allowed). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/saved-sessions'/v1/projects
The folders a session can open in, each with its git branch. Added 2026-11.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/projects'/v1/workflows
The workflow scripts of a workspace, by name. Added 2026-10.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 403 | cwd is not inside an allowed root (root_not_allowed). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/workflows'/v1/inbox
The open inbox items, most urgent first. Added 2026-10.
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 |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/inbox'One open inbox item. Added 2026-10.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No open item with that id or unique prefix (inbox_item_not_found). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/inbox/<id>'Answer an inbox item. Added 2026-10.
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
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Resolved. | application/json InboxResolved |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 404 | No open item with that id or unique prefix (inbox_item_not_found). |
application/json Error |
| 409 | The item was already answered (inbox_item_resolved). |
application/json Error |
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
The browser IDE page. No auth. Added 2026-10.
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 |
curl 'http://127.0.0.1:8790/v1/ide'/v1/mobile
The phone approval inbox page. No auth. Added 2026-10.
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 |
curl 'http://127.0.0.1:8790/v1/mobile'A one-time code that pairs a phone with the inbox page. Added 2026-10.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
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.
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 |
| 401 | Unknown, used or expired code (pairing_invalid). |
application/json Error |
| 403 | From another site (csrf_failed). |
application/json Error |
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.
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 |
| 403 | A paired phone's POST or DELETE without this origin or its x-venom-csrf token (csrf_failed). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
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.
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
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Answered. | application/json MobileAnswered |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 403 | A paired phone's POST or DELETE without this origin or its x-venom-csrf token (csrf_failed). |
application/json Error |
| 404 | No such open item, session or pending approval (inbox_item_not_found, session_not_found, approval_not_found). |
application/json Error |
| 409 | The item was already answered (inbox_item_resolved). |
application/json Error |
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
The evidence bundle of a repository's change. Added 2026-10.
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 |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
| 403 | root or its repository is not inside an allowed root (root_not_allowed). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/evidence'/v1/board
The agent factory's health, the issue board plus the merge gate. Added 2026-10.
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 |
| 404 | No board on this server (board_off). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/board'/v1/gears
The gears the server's venom.yaml offers, for an editor's gear switcher. Added 2026-10.
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 |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/gears'/v1/schedules
The scheduled jobs (venom.yaml schedules:) with their next and last run. Added 2026-10.
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 |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/schedules'Runs of scheduled jobs, newest first. Added 2026-10.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json Error |
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.
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 |
| 404 | No such job (schedule_not_found). |
application/json Error |
| 409 | The job is running now (schedule_running). |
application/json Error |
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.
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 |
| 404 | No such run (run_not_found) or no such file in it (output_not_found). |
application/json Error |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/schedules/runs/<runId>/output'/v1/calls
Voice calls, live and stored, newest first. Added 2026-11.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
curl -H "Authorization: Bearer $VENOM_SERVER_TOKEN" 'http://127.0.0.1:8790/v1/calls'Start a call. Added 2026-11.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
| 409 | max_calls calls are already running (max_calls). |
application/json Error |
| 502 | The call could not be set up (call_failed), e.g. the transport refused it. |
application/json Error |
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.
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 |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
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.
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 |
| 400 | Invalid body or parameters (bad_request, body_too_large, invalid_json). |
application/json Error |
| 401 | Missing or wrong bearer token (unauthorized). |
application/json 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 |
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.
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 |
| 404 | No such call (call_not_found) or agent (unknown_agent), or venom serve has no voice agents (voice_not_configured). |
application/json Error |
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.
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 |
| 404 | No such call (call_not_found), or none recorded, or the call is still live (no_recording). |
application/json Error |
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.
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 |
| 404 | No such call (call_not_found) or agent (unknown_agent), or venom serve has no voice agents (voice_not_configured). |
application/json Error |
| 409 | The call has ended (call_ended). |
application/json Error |
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.
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 |
| 404 | No such call (call_not_found) or agent (unknown_agent), or venom serve has no voice agents (voice_not_configured). |
application/json Error |
| 409 | The call has ended (call_ended). |
application/json Error |
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.
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. |
curl 'http://127.0.0.1:8790/v1/calls/<callId>/media'/v1/voice
The configured voice agents. Added 2026-11.
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 |
| 404 | No such call (call_not_found) or agent (unknown_agent), or venom serve has no voice agents (voice_not_configured). |
application/json Error |
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.
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 |
| 404 | No such call (call_not_found) or agent (unknown_agent), or venom serve has no voice agents (voice_not_configured). |
application/json Error |
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.
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 |
| 404 | No such call (call_not_found) or agent (unknown_agent), or venom serve has no voice agents (voice_not_configured). |
application/json Error |
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.
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 |
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.
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. |
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.
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 |
curl 'http://127.0.0.1:8790/v1/voice/clips/<clip>'Schemas
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
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
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
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
Added 2026-10. One agent process with its age and rates (ps/top).
| Field | Type | Required | Description |
|---|---|---|---|
info |
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
Added 2026-10.
| Field | Type | Required | Description |
|---|---|---|---|
agents |
array of AgentStatus | yes |
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
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
| Field | Type | Required | Description |
|---|---|---|---|
error |
object | yes | |
error.code |
string | yes | |
error.message |
string | yes |
Health
| Field | Type | Required | Description |
|---|---|---|---|
status |
"ok" |
yes | |
version |
string | yes | |
sessions |
integer | yes | |
maxSessions |
integer | yes |
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
Type: allow-once or allow-session or allow-project or deny
CompatOptions
Which Claude Code compatibility sources to load. false loads none; omitted loads all.
Type: boolean or object
CreateSessionRequest
| Field | Type | Required | Description |
|---|---|---|---|
cwd |
string | yes | Workspace directory. Must exist and resolve (after symlinks) inside one of the server's --roots. |
mode |
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 | 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 |
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 | 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
| 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
| 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
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
cwd |
string | yes | |
mode |
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
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | yes | |
streamingBehavior |
steer or followUp |
Required while a run is active (pi semantics). | |
images |
array of 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
| Field | Type | Required | Description |
|---|---|---|---|
nonce |
string | yes | Fresh random bytes (16 or more) as lowercase hex, new for every check. |
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
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
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
| Field | Type | Required | Description |
|---|---|---|---|
enabled |
boolean | yes | |
disabledReason |
string | Why checkpoints are off, when they are. | |
checkpoints |
array of CheckpointInfo | yes |
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
| 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
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | yes | |
content |
string | yes | |
size |
integer | yes | Bytes. |
TurnChanges
| Field | Type | Required | Description |
|---|---|---|---|
entryId |
string | yes | |
run |
string | yes | |
prompt |
string | ||
at |
integer | yes | |
files |
array of TurnFileChange | yes | |
more |
integer | Changed files beyond files, not listed. |
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 | How a browser task's run went (added 2026-10; docs/schedules.md, Browser tasks). | |
watch |
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
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
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
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 | One run of a scheduled job (added 2026-10). |
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
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
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 | 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
Added 2026-10. What the phone inbox shows.
| Field | Type | Required | Description |
|---|---|---|---|
items |
array of InboxItem | yes | The open inbox items, highest rank first. |
approvals |
array of 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
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
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
| 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
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
action |
approve or reject or redirect or take-over |
yes | |
message |
string |
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
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
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
| Field | Type | Required | Description |
|---|---|---|---|
projects |
array of Project | yes | |
truncated |
boolean | yes | More than 500 folders; the rest were left out. |
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
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
name |
string | yes | |
args |
object | yes |
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 | 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
| Field | Type | Required | Description |
|---|---|---|---|
items |
array of TranscriptItem | yes | |
total |
integer | yes | Items in the whole transcript (more than items holds when limit cut it). |
MessageRequest
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | yes |
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
| Field | Type | Required | Description |
|---|---|---|---|
disposition |
queued or handled |
yes |
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
| Field | Type | Required | Description |
|---|---|---|---|
selected |
array of string | yes | |
text |
string | A free-form answer. |
QuestionAnswers
| Field | Type | Required | Description |
|---|---|---|---|
answers |
array of QuestionAnswer | yes |
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 | 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
| Field | Type | Required | Description |
|---|---|---|---|
action |
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
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 or ModeEvent or SubagentsEvent or TodosEvent or HookEvent or DiagnosticEvent or NoticeEvent or EgressEvent or InjectionEvent or LspEvent or FormatEvent or EditToolEvent or TestEditEvent or UnseenRemovalEvent or CheckpointEvent or GuardEvent or CompactionEvent or AgentEvent or SpanEvent or MemoryEvent or CallEvent or CacheBreakEvent or WorkflowEvent or EscalationEvent
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
| 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
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
content |
string | yes | |
status |
pending or in_progress or completed or cancelled |
yes |
PermissionEvent
An audit record for every permission gate decision.
| Field | Type | Required | Description |
|---|---|---|---|
seq |
integer | yes | |
source |
"harness" |
yes | |
type |
"permission" |
yes | |
record |
AuditRecord | yes | One permission gate decision, as written to the audit log. |
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 | 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 | 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
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 | yes |
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 | yes |
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
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
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
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
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
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
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
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
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
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
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
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
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
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 | yes |
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
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
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
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
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
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 | 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
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
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
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 | yes | Added 2026-10. Tokens and cost an agent process used (ADR 0009). |
turns |
integer | yes | |
toolCalls |
integer | yes | |
quantaUsed |
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 | 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 | 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
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
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 | 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
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
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 | 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
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
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 | 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
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
One SSE data payload. source says where it came from:
session: pi's session events, in pi's JSON-stream shape (message_updatecarries 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'sparentToolCallIdfor 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 ownsource,compactionorbranchSummary, is sent asorigin),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/harnessemits, each with a schema inHarnessEvent:permission(an audit record for every gate decision),mode,todos,subagents(progress of thetasktool),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 andpsrow, 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 runprogress 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,byas 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 |