Sessions API
Share a session's trace, stream a live session to teammates, hand a session to someone else, and run venom serve sessions on a daemon through Venom Cloud.
These routes move agent sessions between people and machines. The venom CLI calls all of them (/share,
/share live, /handoff, venom serve through the cloud), and an app built on Venom Cloud can call them the same
way: a support tool that hands a stuck session to a human, a dashboard that streams an agent's work, a backend that
runs harness sessions on the org's daemons.
Every route here takes a client key (Authorization: Bearer vck_…), answers with cache-control: no-store, and
uses the error shape in Venom Cloud APIs overview. The cloud never redacts content for
you: every body that carries session text must say "redaction": {"applied": true}, and the cloud still refuses
text that matches its secret patterns (provider keys, GitHub and Slack tokens, AWS key ids, PEM private keys,
venom keys) with 422 secrets_found, without echoing the match. Stored content is sealed with the org's vault key,
so a deployment without VENOM_VAULT_KEYS answers 503 vault_not_configured.
Routes
| Route | What it does |
|---|---|
POST /v1/session-shares |
upload a redacted session trace; 201 new, 200 replaced |
DELETE /v1/session-shares/{id} |
remove a share made by the key's key group |
POST /v1/live-sessions |
start a live share of a running session (201), or update this key group's live share of it (200) |
PATCH /v1/live-sessions/{id} |
change grants, audience, title, pairing, or extend it |
DELETE /v1/live-sessions/{id} |
stop the live share and delete what it stored |
POST /v1/live-sessions/{id}/sync |
push transcript events, pull viewers and teammates' inputs |
POST /v1/handoffs |
send a session to a member or a key group |
GET /v1/handoffs |
the key's inbox (?box=inbox, default) or what it sent (?box=sent) |
GET /v1/handoffs/{id} |
one handoff; ?trace=1 adds the shared transcript |
DELETE /v1/handoffs/{id} |
the sender cancels it |
POST /v1/handoffs/{id}/accept |
a recipient takes it; the first one wins |
POST /v1/handoffs/{id}/decline |
a recipient declines it |
POST /v1/serve/sessions |
create a venom serve session on one daemon and bind it there |
GET /v1/serve/sessions/{id}/{rest...} |
any harness-server GET of the bound session (including the events stream) |
POST /v1/serve/sessions/{id}/{rest...} |
any harness-server POST (prompt, steer, follow-up…); POST …/resume moves the session |
PUT /v1/serve/sessions/{id}/{rest...} |
any harness-server PUT of the bound session |
PATCH /v1/serve/sessions/{id}/{rest...} |
any harness-server PATCH of the bound session |
DELETE /v1/serve/sessions/{id}/{rest...} |
any harness-server DELETE; deleting the session itself closes the binding |
The generated reference for these routes is at /docs/api/cloud. People read shares, live sessions and handoffs
in the console (Sessions); the console's admin routes are on the observability admin page.
Shared sessions
A share is a redacted copy of a session's trace that the org can replay in the console. It is what
venom session share and /share upload (see Sessions, resume and export).
curl -s "$VENOM_CLOUD/v1/session-shares" \
-H "Authorization: Bearer $VENOM_KEY" -H "Content-Type: application/json" \
-d '{
"title": "Fix the flaky retry test",
"trace": {"v": 1, "session": {"id": "3f2a9c"}, "items": [
{"kind": "user", "text": "Why does retry_test flake?"},
{"kind": "assistant", "text": "The backoff uses wall-clock time..."}
], "totals": {}},
"redaction": {"applied": true, "counts": {"secret": 0}}
}'{"object": "session_share", "id": "ss_5c0e…", "url": "https://cloud.usevenom.dev/sessions/ss_5c0e…",
"title": "Fix the flaky retry test", "session_id": "3f2a9c", "visibility": "org",
"created_at": "2026-11-03T09:12:00Z", "updated_at": "2026-11-03T09:12:00Z", "expires_at": "2026-12-03T09:12:00Z"}| Field | Type | Default | Notes |
|---|---|---|---|
trace |
object | required | the CLI's export trace: v: 1, session (id, cwd?, started?, name?), items, totals, optional scrubbed and egress (hosts the session contacted) |
trace.items[] |
object | kind: user, assistant, tool, meter, summary or note, with the CLI's fields; images (image/png, image/jpeg, image/gif, image/webp, base64) and, on tool items, subagents |
|
redaction |
object | required | applied must be true (else 400 not_redacted); counts is shown to viewers |
title |
string | the session's name, else Session <id> |
at most 200 characters |
actions |
object | none | the last seal of the session's signed action log (session, count, head, kid, public_key, sig, sealed_at); the cloud checks the Ed25519 signature (422 bad_signature) |
- One share per key group and session id. Sharing the same session again replaces the trace in place (same id and
link,
200), keeps comments and access, and restarts retention. - Size. The whole body is at most 4 MiB (
413 too_large); drop images or share a shorter session. - Who sees it.
visibility: "org": members withlogs:read. An admin can narrow it toadminsin the console. Public read-only links exist only when an org admin turns them on. - Retention. 30 days from the last upload by default (the org's setting, 1 to 365 days).
DELETE /v1/session-shares/{id}with a key of the key group that shared it answers{"id": "ss_…", "deleted": true}; any other id is404.
Live sessions
A live share streams a running session to the console as it happens. The owner can let named teammates send
messages to the agent (drivers) and answer its permission prompts (approvers). The client always dials out: it
pushes events and pulls inputs on the same sync request, so nothing ever connects to the machine running the agent.
const base = "https://cloud.usevenom.dev/v1";
const h = { Authorization: `Bearer ${process.env.VENOM_KEY}`, "Content-Type": "application/json" };
const live = await fetch(`${base}/live-sessions`, {
method: "POST", headers: h,
body: JSON.stringify({ session_id: "3f2a9c", title: "Release prep", drivers: ["alice"], redaction: { applied: true } }),
}).then((r) => r.json());
// Every 2 s while someone watches, every 5 s otherwise:
const s = await fetch(`${base}/live-sessions/${live.id}/sync`, {
method: "POST", headers: h,
body: JSON.stringify({
events: [{ kind: "item", index: 0, item: { kind: "user", text: "Bump the version and tag it" } }],
status: { state: "running", detail: "bash: npm test" },
}),
}).then((r) => r.json());
for (const input of s.inputs) console.log(input.author, input.kind, input.text ?? input.decision);POST /v1/live-sessions (at most 64 KiB):
| Field | Type | Default | Notes |
|---|---|---|---|
session_id |
string | required | the venom session id |
title |
string | at most 200 characters | |
expires_in_minutes |
integer | 240 | 5 to 1440 |
audience |
org | invited |
org |
org: every member with logs:read; invited: only invite |
invite |
string[] | members who may watch (email, or the part before @), at most 50 |
|
drivers |
string[] | may send messages | |
approvers |
string[] | may send messages and answer permission prompts | |
pair, pair_driver |
string, owner | partner |
none, owner |
pairing mode: one partner and a driver token (below) |
redaction |
object | required | {"applied": true} |
It answers {object: "live_session", id: "ls_…", url, title, session_id, state: "live", audience, expires_at, grants: [{member, email, role}], viewers: []}, role being viewer, driver, approver or blocked. An
unknown or ambiguous name is 400 unknown_members with error.unknown.
POST /v1/live-sessions/{id}/sync (at most 1 MiB):
| Field | Notes |
|---|---|
events |
at most 200: {kind: "item", index, item} (upsert of the transcript item at that position), {kind: "prompt", id, title, detail?, preview?, agent?} (a permission prompt now waiting), {kind: "prompt_closed", id, outcome: "allowed" | "denied" | "gone", by?}, {kind: "notice", text}, and in pairing mode {kind: "comment", text} |
acks |
[{id, state: "applied" | "rejected", reason?}] for inputs the client handled |
status |
{state: "running" | "idle" | "waiting", detail?} |
The answer has seq, state, expires_at, viewers (name, email?, role, since, last_seen), grants,
inputs and pair. An input is {id, kind: "message", text, author, created_at} or {id, kind: "approval", prompt_id, decision: "allow" | "deny", feedback?, author, created_at}; it comes back on every sync until acked.
A remote approval is always "allow once" and never stores a rule. Items are clipped (a tool's output to 64 KiB, at
most 10,000 items); an item or prompt that still matches a secret pattern is replaced by a note saying it was
withheld. Stop syncing on 410 live_ended (stopped or expired) or 404.
PATCH /v1/live-sessions/{id} takes title, audience, invite, drivers, approvers, block, unblock,
revoke (take a grant away), extend_minutes (at most 24 hours from now in all), pair (a member, or null to end
pairing) and pair_driver (hand the token to owner or partner; 409 not_pairing when nobody is paired). Only
a key of the owner's key group may change or stop the share; anything else is 404.
DELETE /v1/live-sessions/{id} stops it: the transcript, events and inputs are deleted at once.
Pairing. With pair, the share is private to the owner and one partner and the driver token decides who may
send messages (403 not_the_driver from anyone else). pair needs a member behind the key (400 pair_needs_owner)
and someone else (400 pair_self). The navigator's comments are never sent to the model unless the driver includes
them.
Handoffs
A handoff packages a session for a teammate: a note (goal, plan, done, open questions, next step), optionally the
transcript as a share, and the git branch with its diff stats. It is what /handoff and venom handoff use (see
Teams of agents).
import os, requests
base = "https://cloud.usevenom.dev/v1"
h = {"Authorization": f"Bearer {os.environ['VENOM_KEY']}"}
ho = requests.post(f"{base}/handoffs", headers=h, json={
"to": {"member": "alice@example.com"},
"title": "Retry flake fix",
"session_id": "3f2a9c",
"note": {"goal": "Make retry_test deterministic", "plan": ["Inject a clock"], "done": ["Found the cause"],
"open_questions": [], "next_step": "Replace time.Now in backoff.go"},
"git": {"repo": "github.com/acme/app", "branch": "fix/retry", "head": "a" * 40, "base": "main",
"pushed": True, "dirty": False, "stats": {"files": 2, "insertions": 30, "deletions": 4}},
"redaction": {"applied": True},
}).json()
inbox = requests.get(f"{base}/handoffs", headers=h, params={"box": "inbox"}).json()POST /v1/handoffs (at most 64 KiB) answers 201 with {object: "handoff", id: "ho_…", url, state: "open", title, from: {name, email?}, to: {kind: "member", name, email} | {kind: "team", name}, created_at, expires_at}.
| Field | Type | Notes |
|---|---|---|
to |
object | required: {member: <email or name before @>} or {team: <key group name>}. A key group handoff goes to everyone holding a key of that key group (the API keeps the name team) |
title |
string | required, at most 200 characters |
session_id |
string | required |
note |
object | required: goal, next_step (each at most 1,000 characters), plan, done, open_questions (at most 20 lines of 500 characters each) |
message |
string | at most 1,000 characters |
share_id |
string | a share (ss_…) of the same key group: the transcript |
git |
object | repo, branch, head (40 hex), base?, pushed, dirty, worktree?, stats (files, insertions, deletions), files? (at most 100) |
redaction |
object | required, {"applied": true} |
| Route | Answer and errors |
|---|---|
GET /v1/handoffs?box=inbox |
open handoffs to the key's member or key group, newest first; box=sent lists what the key's member sent |
GET /v1/handoffs/{id} |
for the recipients and the sender; ?trace=1 (or true) adds the shared transcript; anyone else gets 404 |
POST /v1/handoffs/{id}/accept |
{state: "accepted", accepted_by, accepted_at}; 409 already_accepted (says who), 409 handoff_closed (declined, cancelled or expired), 403 not_yours |
POST /v1/handoffs/{id}/decline |
body {reason?} (at most 500 characters), by a recipient |
DELETE /v1/handoffs/{id} |
by the sender: the handoff is cancelled |
A recipient name that matches nobody, or more than one member, is 400 unknown_recipient (with
error.candidates when ambiguous). Open handoffs expire after 14 days. The org's webhooks get handoff.created,
handoff.accepted and handoff.declined (ids, names, repo and branch, never the note).
venom serve sessions through the cloud
A venom serve session (the harness over HTTP) lives in one daemon's process: its tools, files and checkpoints are
on that machine. Through the cloud, a serve session is bound to one daemon and never moves by itself. Every request
is relayed to that daemon; serve sessions never use the direct (307) path, and the cloud's own providers never host
them. The daemon must advertise serve support (it runs venom serve).
The bodies are harness-server's: POST /v1/serve/sessions takes what POST /v1/sessions takes on venom serve, and
/v1/serve/sessions/{id}/<path> maps to /v1/sessions/{id}/<path> on the daemon, query string included.
# Create: the cloud routes once, binds the session, relays the create.
curl -si "$VENOM_CLOUD/v1/serve/sessions" \
-H "Authorization: Bearer $VENOM_KEY" -H "Content-Type: application/json" \
-d '{"cwd": "/srv/repos/app"}'
# x-venom-serve-binding: {"object":"venom.serve.binding","session_id":"s-9","daemon":{"id":"…","name":"gpu-sg-1","region":"ap-southeast-1"},"epoch":1,"state":"bound",…}
# Prompt it, then follow its events (SSE; reconnect with Last-Event-ID):
curl -s "$VENOM_CLOUD/v1/serve/sessions/s-9/prompt" \
-H "Authorization: Bearer $VENOM_KEY" -H "Content-Type: application/json" -d '{"message": "Run the tests"}'
curl -N "$VENOM_CLOUD/v1/serve/sessions/s-9/events" -H "Authorization: Bearer $VENOM_KEY"- Binding. The create answer is the harness's body plus an
x-venom-serve-bindingheader:{object: "venom.serve.binding", session_id, daemon: {id, name, region}, epoch, state, created_at, resumed_from, hlc}.x-venom-daemonon the create pins the daemon. - Key group scope. Only keys of the key group that created the session reach it; anything else (or a closed session) is
404 not_found. - Prompt filters. What a person types (
POST …/prompt,…/steer,…/follow_up) goes through the org's prompt filters; the agent's own model calls run on the daemon. - Streams.
GET …/eventsis relayed SSE withlast-event-idpassed through. A function has at most 800 seconds on the hosted tier, so a long stream ends and the client reconnects withLast-Event-ID. - The daemon is gone. Any call answers
503 session_daemon_unavailable. The cloud does not fail over or retry a serve request elsewhere: the session's state is not there. - Resume.
POST /v1/serve/sessions/{id}/resumeis the only way a session moves. Body (all optional):daemon(name or id to pin),saved_session(a saved harness session the new daemon restores, sent to it asPOST /v1/sessionswithresume) andcreate(extra create fields for that restore). It routes again excluding the lost daemon, bumpsepoch, and answers the new binding withresumed_from. A daemon drops requests carrying an older epoch. - Closing.
DELETE /v1/serve/sessions/{id}relays the harness's delete and, on success, closes the binding. POST /v1/serve/sessionsanswers503 no_daemon_available(withreasons) when no live daemon of the key can host a serve session; a method other thanGET,POST,PUT,PATCH,DELETEis405 method_not_allowed. Bodies are at most 1 MiB on create and resume, 4 MiB otherwise. Serve requests count against the key's RPM and the org's spend cap.
Errors
| Status | code |
Where |
|---|---|---|
| 400 | invalid_request (error.errors lists each problem), not_redacted |
all bodies |
| 400 | unknown_members, pair_needs_owner, pair_self |
live sessions |
| 400 | unknown_recipient |
handoffs |
| 403 | not_yours |
handoffs |
| 403 | not_the_driver, not_paired, not_a_driver, approvals_not_granted |
live sessions |
| 404 | not_found |
an id outside the key's key group or audience |
| 409 | already_accepted, handoff_closed |
handoffs |
| 409 | not_pairing, prompt_closed, driver_cannot_comment |
live sessions |
| 410 | live_ended |
live sessions after stop or expiry |
| 413 | too_large, request_too_large |
a body over the route's limit |
| 422 | secrets_found, bad_signature |
text that still matches a secret pattern; a bad action-log seal |
| 503 | vault_not_configured, session_daemon_unavailable, no_daemon_available |
deployment, serve sessions |
Related
- Venom Cloud APIs overview: credentials, errors, limits and headers
- Knowledge and tools API: memory, library, marketplace and runners
- Sessions, resume and export and Teams of agents for the CLI side