Skip to content
Docs menu

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.

View .md

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 with logs:read. An admin can narrow it to admins in 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 is 404.

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-binding header: {object: "venom.serve.binding", session_id, daemon: {id, name, region}, epoch, state, created_at, resumed_from, hlc}. x-venom-daemon on 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 …/events is relayed SSE with last-event-id passed through. A function has at most 800 seconds on the hosted tier, so a long stream ends and the client reconnects with Last-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}/resume is 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 as POST /v1/sessions with resume) and create (extra create fields for that restore). It routes again excluding the lost daemon, bumps epoch, and answers the new binding with resumed_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/sessions answers 503 no_daemon_available (with reasons) when no live daemon of the key can host a serve session; a method other than GET, POST, PUT, PATCH, DELETE is 405 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