Skip to content
Docs menu

Harness server API

Every operation of venom serve's HTTP API (66 operations), with parameters, bodies, responses, schemas and a curl line each.

View .md

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