Agent and CLI API
The /v1 routes an agent or the venom CLI calls besides inference - org gears, usage, signed policy, guardrails, fleet, onboarding, backups and the session and task reports.
Besides inference, an agent working for your org needs to know which gears it may use, what it has spent, which
rules bind it, and where to report what happened. The venom CLI uses these routes; your own agent or app can too.
All of them take a client key (Authorization: Bearer vck_…, see Credentials),
and all answers carry cache-control: no-store.
Some routes act for a member: the person whose own key it is (a key their venom cloud login minted, or one
they made in the console marked personal). A shared, service or customer key has no member; those routes refuse
it or answer without personal data, as each section says.
Quick start
export VENOM_CLOUD=https://cloud.usevenom.dev
export VENOM_KEY=vck_...
curl -s "$VENOM_CLOUD/v1/gears" -H "Authorization: Bearer $VENOM_KEY" # the org's gears
curl -s "$VENOM_CLOUD/v1/usage/summary?since=7d" -H "Authorization: Bearer $VENOM_KEY" # this key's spend
curl -s "$VENOM_CLOUD/v1/policy" -H "Authorization: Bearer $VENOM_KEY" # the key group's signed policyconst headers = { Authorization: `Bearer ${process.env.VENOM_KEY}` };
const base = "https://cloud.usevenom.dev";
const gears = await (await fetch(`${base}/v1/gears`, { headers })).json();
const spend = await (await fetch(`${base}/v1/usage/summary?since=30d&sessions=5`, { headers })).json();
console.log(gears.gears.map((g: { name: string }) => g.name), spend.totals.cost_usd);import os, requests
h = {"Authorization": f"Bearer {os.environ['VENOM_KEY']}"}
base = "https://cloud.usevenom.dev"
r = requests.post(f"{base}/v1/task-outcomes", headers=h, json={"task": "acme/web#123", "outcome": "merged_pr"})
print(r.status_code, r.json()) # 201 {"object": "venom.task_outcome", ..., "recorded": true}Routes
| Route | What it does | Section |
|---|---|---|
GET /v1/gears |
the org's gears, the same body as the orchestrator's | Gears |
POST /v1/gears/experiments/{id}/sessions |
report one session of a gear experiment | Gears |
GET /v1/usage |
this key's spend today, last 7 days and this month, budget status, top sessions | Usage |
GET /v1/usage/summary |
this key's spend in rows by day, gear, role, model and task | Usage |
GET /v1/policy |
the key group's signed policy envelope | Policy |
GET /v1/policy-key |
the public key that signs the org's policies | Policy |
GET /v1/guardrails |
the guardrails that apply to this key's member | Guardrails |
PUT /v1/guardrails/overrides |
switch a relaxable org or key group rule for the member | Guardrails |
POST /v1/guardrails/draft |
draft a personal guardrail from a sentence (nothing saved) | Guardrails |
PUT /v1/fleet |
publish a machine's agents for one repository | Fleet |
GET /v1/fleet |
the key group's running agents | Fleet |
GET /v1/onboarding |
the org's onboarding paths with the member's progress | Onboarding |
POST /v1/onboarding/steps |
mark a manual onboarding step done or not done | Onboarding |
GET /v1/org/backup |
export the org's configuration (owners and admins) | Backup |
POST /v1/org/restore |
plan or apply a restore (owners and admins) | Backup |
POST /v1/task-outcomes |
report that a task's pull request merged or issue closed | Reports |
GET /v1/session-outcomes/settings |
whether the org takes session outcome reports | Reports |
POST /v1/session-outcomes |
report how a session went, in counts | Reports |
GET /v1/session-summaries/settings |
whether the org collects session summaries | Reports |
POST /v1/session-summaries |
upload a session's redacted summary | Reports |
The generated reference with every route's method, auth and a curl line is at /docs/api/cloud.
Gears
GET /v1/gears answers the org's gears, defined on the console's Gears page, in the self-hosted orchestrator's
body, so the venom CLI reads both the same way (Gears).
{"object": "list", "source": "Acme Corp", "locked": true, "default": "eco",
"gears": [{"name": "eco", "key": 1, "model": "venom-auto", "profile": "cloud-first",
"workers": {"model": ["qwen3-coder:30b"], "thinking": "low"},
"roles": {"summary": {"model": "gpt-5-mini", "service_tier": "flex"}}}],
"experiment": {"id": "0193…", "name": "eco vs deep", "a": "eco", "b": "deep", "split": 50, "ends_at": "2026-11-20T00:00:00Z", "opt_out": true}}| Field | Meaning |
|---|---|
source |
the org's name |
locked |
members may use only these gears |
gears[] |
name, key (1-9), description, model (a string or a list), thinking, profile (cloud, cloud-first, daemons, daemons-first or null), service_tier, workers and roles (smart, vision, browser, classifier, summary, reflex), each role with model, profile, thinking, service_tier |
degraded |
on a gear or role: models quality checks flagged and removed from its list (cloud only) |
default |
the gear a new session starts in when the user's config names none (cloud only; absent when unset) |
experiment |
the running gear experiment this key's new sessions join (cloud only; absent otherwise) |
- Gears come in key order (1-9), then the rest by name.
[]when the org has none. - Model lists are cut to what the key may use; a role left with no model is dropped, and so is a gear whose main model has none.
- The cloud never applies a gear. The client sends each role's model and its
profileasx-venom-profile, and the org's routing decides (a profile only narrows it, else403 profile_forbidden).
Gear experiment reports
POST /v1/gears/experiments/{id}/sessions records how one session of a running gear experiment went, at its end or
when the user opts out. The arm must be the one the session id hashes to.
| Field | Type | Rule |
|---|---|---|
session_id |
string | required, at most 256 characters |
arm |
string | a or b |
outcome |
string | ended, abandoned or opted_out (an opt-out is never overwritten) |
turns, tool_calls, tool_errors, stuck_shifts |
integer | optional, 0 to 1,000,000; tool_errors ≤ tool_calls |
switched |
boolean | optional: the user switched gear mid-session |
The body is at most 4 KiB; unknown fields are ignored. Answer: {"object": "venom.experiment_session", "experiment_id", "session_id", "arm", "recorded"}. recorded is false once the experiment stopped and the session
was never seen. An experiment of another org is 404; the wrong arm is 400 arm_mismatch.
Usage
GET /v1/usage is the cloud's version of the orchestrator's venom.usage body, for this key:
| Parameter | Type | Default | Rule |
|---|---|---|---|
sessions |
integer | 5 |
top sessions by cost today, 0 to 50 |
session |
string | none | one session's figures with its subagents and per-model split; at most 256 bytes |
The answer: {"object": "venom.usage", "now", "key": {"id", "name", "team"}, "budget", "today", "last_7_days", "month", "top_sessions", "session", "log": true, "notes"}. Each window holds requests, tokens and cost_usd.
key.team is the name of the key's key group (a key group holds API keys, daemons, policies and GPU grants, not
people; the API keeps the name team).
Spend by gear, role and task
GET /v1/usage/summary gives one row per UTC day, gear, role, requested model, served model and task, newest day
first, so one call can be grouped any way. venom cost reads it.
| Parameter | Type | Default | Rule |
|---|---|---|---|
since |
YYYY-MM-DD or <n>d |
the earlier of the month's first day and six days ago | not in the future; at most 92 days back |
sessions |
integer | 10 |
costliest sessions to include, 0 to 50 |
{"object": "venom.usage.summary", "now": "…", "from": "2026-10-28", "to": "2026-11-04",
"key": {"id": "…", "name": "ci-bot", "team": "platform"},
"totals": {"requests": 412, "errors": 3, "tokens_in": 1830000, "tokens_out": 91000, "cached_tokens": 1200000, "cost_usd": 4.12,
"partial": {"requests": 1, "tokens_out": 210, "cost_usd": 0.01}},
"rows": [{"day": "2026-11-03", "gear": "deep", "role": "main", "model": "venom-auto", "served_model": "gpt-5",
"task": "acme/web#123", "requests": 40, "errors": 0, "tokens_in": 300000, "tokens_out": 12000,
"cached_tokens": 250000, "cost_usd": 0.92, "partial": {"requests": 0, "tokens_out": 0, "cost_usd": 0}}],
"sessions": [{"session_id": "…", "first_ts": "…", "last_ts": "…", "requests": 40, "cost_usd": 0.92, "subagents": 2,
"gear": "deep", "top_model": "gpt-5", "task": "acme/web#123"}],
"notes": []}- The rows cover the key's rotation chain, so a rotated key still sees what it spent before; never another key.
partialcounts responses whose client went away, billed as streamed.errorsincludes them.- At most 5,000 rows; past that the earliest days are cut and a note says so.
- Tag requests with
x-venom-gear,x-venom-roleandx-venom-task(headers) to fill these columns. A request without a task counts toward the first task its root session named.
Signed policy
GET /v1/policy answers the current policy envelope of the key's key group, signed by the cloud so a laptop can trust it
over any channel. The venom CLI syncs it at start (Org policy).
{"format": "venom.policy/v1", "kid": "org-…", "seq": 3, "issued_at": "…", "expires_at": "…", "policy": {"version": 1}, "sig": "…"}- The answer has
ETag: "seq-<n>". Send it back inIf-None-Matchand an unchanged policy is304with no body. - A key group without a policy is
404 policy_not_found. sigis an Ed25519 signature (base64url) over the canonical JSON of the envelope withoutsig: keys sorted recursively, no whitespace. Accept only aseqat least the last one you saw.- Admins write the policy with
PUT /api/admin/v1/teams/{id}/policy.
Policy signing key
GET /v1/policy-key answers the key that signs this org's policies: the org's own key when it has one, else the
deployment's.
{"object": "policy.key", "kid": "org-AbCdEfGhIjKl", "alg": "Ed25519", "public_key": "…", "fingerprint": "1a2b 3c4d 5e6f 7a8b", "source": "tenant", "tenant_id": "…"}public_key is the raw 32-byte key in base64url; fingerprint the first 8 bytes of its SHA-256 in hex; source
is tenant or deployment. With neither key it is 503 policy_signing_not_configured. venom cloud login pins
this key on the laptop.
Guardrails
The guardrails that apply to a key's requests come in layers: the org's, the key group's (or the resold customer's) and the member's own (Guardrails).
GET /v1/guardrailsanswers them for the CLI's/guardrails. On a member's own key: the org and key group rules with their locks and the member's switches, the member's own rules, the catalog and"personal": true. On any other key: the org and key group layers only,"personal": falseand a note; nobody sees another person's rules.PUT /v1/guardrails/overridesswitches an org or key group rule for the member, as far as the rule's lock allows.Field Type Meaning codestring the rule's code, e.g. GR-ORG-PII-001enabledboolean turn it off or on for the member actionstring a different action, where the lock allows it clearboolean drop the member's override The body is at most 16 KiB. A locked rule, or a change looser than its lock allows, is
403 guardrail_locked; an unknown code is404 not_found. Answer:{"object": "guardrail.override", "override", "relaxed", "tightened"}.POST /v1/guardrails/draft{text, gear?}: the classifier model drafts one personal guardrail from a sentence (at most 500 characters), booked to the key. Nothing is saved:{"object": "guardrail.draft", "saved": false, "model", "rule", "note", "left_today"}. Thegearpicks whose classifier role drafts.
The override and draft routes need a member's own key (403 forbidden otherwise). Draft errors:
| Status | code |
Meaning |
|---|---|---|
| 400 | invalid_request |
no text, or over 500 characters |
| 400 | guardrail_drafting_model |
no model to draft with: give a gear a classifier role or set the drafting model |
| 403 | guardrail_drafting_off |
an org admin has drafting switched off |
| 422 | guardrail_draft_unusable |
the model's draft was not a valid rule |
| 429 | guardrail_drafting_limit |
the member's daily drafts are used up (x-should-retry: false) |
| 502 | guardrail_drafting_failed |
the model did not answer within 20 seconds |
Fleet
Which agents each machine of a key group is running, for a view of who is doing what. The key group is always the key's. The console's Fleet page reads the same rows.
curl -s -X PUT "$VENOM_CLOUD/v1/fleet" -H "Authorization: Bearer $VENOM_KEY" -H "Content-Type: application/json" \
-d '{"machine": "build-01", "repo": "github.com/acme/web",
"agents": [{"id": "a1", "name": "fix-flaky-test", "state": "running", "task": "acme/web#123", "cost_usd": 0.42, "tokens": 51000}]}'PUT /v1/fleet publishes a machine's full list for one repository: it replaces that machine and repository's
rows (an empty agents clears them) and leaves the rest alone.
| Field | Type | Rule |
|---|---|---|
machine |
string | required, at most 128 characters |
repo |
string | required, at most 512 |
agents[] |
array | at most 64; ids unique within the body |
agents[].id, name |
string | id required; each at most 128 |
agents[].state |
string | running, waiting, stuck, looping, idle or exited |
agents[].task |
string | optional, at most 200: the one line you choose to share |
agents[].cost_usd, tokens |
number | optional, not negative (tokens an integer) |
agents[].leases |
array | optional, at most 32 of {path, holder?, expiresAt} |
inbox_url |
string | optional: the machine's venom serve phone inbox, an http(s) URL ending in /v1/mobile, at most 300 characters, no credentials, query or fragment |
Answer: {"object": "fleet.publish", "machine", "repo", "agents", "removed", "ttl_s": 60}. The body is at most
512 KiB (413), and a key group holds at most 2,000 fresh rows (413 fleet_full).
GET /v1/fleet[?repo=] answers {"object": "list", "ttl_s": 60, "data": [{"machine", "id", "repo", "name", "member", "state", "task", "cost_usd", "tokens", "leases", "inbox_url", "updated_at"}]}, sorted by machine then id.
member is the name of the key that published the row.
Rows are soft state: publish at least every 20 seconds. A row not refreshed within ttl_s (60 seconds) is hidden
and later deleted. Nothing here is content: no prompts or outputs.
Onboarding
Admins build onboarding paths (ordered first tasks) on the console; venom onboard walks the member through them.
GET /v1/onboardinganswers{"object": "venom.onboarding", "member", "paths": [{"id", "name", "description", "total", "done", "steps": [{…, "done", "how", "done_at", "next"}]}]}. A key that is not a member's own reads the paths with no progress ("member": false).POST /v1/onboarding/steps{path_id, step_id, done?}marks a manual step done (donedefaults to true) or undoes it (false). Answer:{"object": "venom.onboarding.step", "path_id", "step_id", "done"}.
| Status | code |
Meaning |
|---|---|---|
| 400 | invalid_request |
no path_id (a UUID) or step_id |
| 404 | not_found |
no such path in the org, or no such step in it |
| 409 | no_member |
the key is not a member's own; sign in with venom cloud login |
| 409 | automatic_step |
the step completes by itself when the work shows up (a session, a merged PR, a closed issue) |
Org backup and restore
The org's configuration as one versioned JSON file, for venom cloud backup and venom cloud restore. The key's
creator must be an owner or admin of its org, else 403 forbidden. A backup never holds provider keys, API keys,
tokens, signing secrets or any log or usage row; its reenter list names what you would have to enter again.
curl -s "$VENOM_CLOUD/v1/org/backup?members=1" -H "Authorization: Bearer $VENOM_KEY" -o acme-backup.json
# Dry run (the default): what a restore would create, update or skip
jq -n --slurpfile b acme-backup.json '{backup: $b[0], on_conflict: "keep"}' |
curl -s "$VENOM_CLOUD/v1/org/restore" -H "Authorization: Bearer $VENOM_KEY" -H "Content-Type: application/json" -d @-GET /v1/org/backup[?members=1]downloadsvenom-backup-<org>-<date>.json({"format": "venom.org-backup", "version": 1, "exported_at", "source", "sections", "reenter"}).members=1includes members and roles.POST /v1/org/restoretakes:Field Type Default Meaning backupobject required the exported JSON, at most 2 MiB dry_runboolean trueplan only; nothing is written on_conflictstring overwriteoverwriteorkeep(skip items that differ)sectionsstring[] all e.g. ["gears", "routing", "budgets"]membersboolean falsechange the roles of people already in the org A restore never deletes. Each item is planned as
create,update(with the fields that differ) orskip(with why). Applied, it runs in one transaction and is audited. Sections that need more than an admin (customers,sso) are skipped for callers without the permission.
Session and task reports
Small reports a member's venom sends when a session or a task ends. They feed the console's scorecard, failure clusters, session history and cost per outcome. None carries a prompt, an answer or a file's content.
Task outcomes
POST /v1/task-outcomes records that a task's pull request was merged or its issue closed. The cloud never polls
GitHub: the client checks (venom asks gh) and reports.
| Field | Type | Default | Rule |
|---|---|---|---|
task |
string | required | a task reference (acme/web#123, a PR or issue URL, ENG-142), stored in its canonical spelling |
outcome |
string | required | merged_pr or closed_issue |
occurred_at |
RFC 3339 | now | not in the future (small clock skew is clamped), at most a year back |
One row per org, task and outcome, and the first report wins: 201 {"object": "venom.task_outcome", "task", "outcome", "recorded": true} when new, 200 with "recorded": false when known. A body over 2 KiB or a bad value
is 400. Cost per outcome divides the task's tagged spend (x-venom-task) by these.
Session outcomes
GET /v1/session-outcomes/settingsanswers{"object": "venom.session_outcomes.settings", "enabled"}. On by default; an org admin can turn it off. Ask the user before reporting, and send nothing while it is false.POST /v1/session-outcomesreports how a session went, in counts only. A report while the org has it off is403 outcomes_off.
| Field | Type | Meaning |
|---|---|---|
session_id |
string | required |
outcome |
string | ended (closed while idle after a clean run) or abandoned |
gear, started_at, ended_at |
string | optional |
turns, tool_calls, tool_errors, stuck_shifts, loops, first_output_ms, files_changed, files_reverted |
integer | optional counts |
tool_error_kinds |
object | counts by not_found, permission, timeout, exit_code, invalid_args, edit_mismatch, other |
failures |
object | counts by refusal, content_filter, timeout, provider_error, budget_block, allowlist_block, context_overflow, other |
branch_ref |
string | optional: the first 16 hex characters of sha256(<repo>@<branch>), never the branch name |
The body is at most 8 KiB; unknown fields are ignored. One report per org and session id: 201 new, 200
replaced ({"object": "venom.session_outcome", "session_id", "replaced"}). 400 invalid_request lists every
problem. Reports are kept as long as the org's request log.
Session summaries
GET /v1/session-summaries/settingsanswers{"object": "venom.session_summaries.settings", "enabled"}. Off until an org admin turns it on. Ask the user before every upload.POST /v1/session-summariesuploads a session's summary, already redacted on the machine. An upload while the org has it off is403 summaries_off.
| Field | Type | Rule |
|---|---|---|
session_id |
string | required |
title, goal, result |
string | goal required; at most 200, 500 and 1,000 characters |
outcome |
string | done, partial, failed or abandoned |
decisions, files |
string[] | at most 10 and 50 entries, each at most 300 characters |
repo, branch, model |
string | optional |
cost_usd, tokens, turns, duration_s |
number | optional |
trigger |
string | end, share or manual |
started_at, ended_at |
RFC 3339 | optional |
redaction |
object | required: {"applied": true, "counts": {...}} |
The body is at most 32 KiB. One summary per key group and session id: 201 new, 200 replaced ({"object": "venom.session_summary", "id": "sum_…", "replaced"}). Without redaction.applied it is 400 not_redacted; any
other problem is 400 invalid_summary with every problem listed; a field that still looks like a secret is
422 secrets_found. Summaries are kept for the org's retention (90 days by default) and searched on the console's
Session history page.
Errors
The common codes are in Errors. Codes specific to these routes are listed in each section above; in short:
| Status | code |
Route |
|---|---|---|
| 400 | arm_mismatch |
gear experiment reports |
| 403 | forbidden |
member-only routes on a key that is not a member's own; backups without owner or admin |
| 403 | guardrail_locked, guardrail_drafting_off |
guardrails |
| 403 | outcomes_off, summaries_off |
session reports while the org has them off |
| 404 | policy_not_found |
a key group with no policy |
| 409 | no_member, automatic_step |
onboarding |
| 413 | fleet_full |
fleet publish |
| 422 | secrets_found |
session summaries |
| 503 | policy_signing_not_configured |
policy key |