Skip to content
Docs menu

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.

View .md

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 policy
const 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 profile as x-venom-profile, and the org's routing decides (a profile only narrows it, else 403 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.
  • partial counts responses whose client went away, billed as streamed. errors includes 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-role and x-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 in If-None-Match and an unchanged policy is 304 with no body.
  • A key group without a policy is 404 policy_not_found.
  • sig is an Ed25519 signature (base64url) over the canonical JSON of the envelope without sig: keys sorted recursively, no whitespace. Accept only a seq at 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/guardrails answers 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": false and a note; nobody sees another person's rules.

  • PUT /v1/guardrails/overrides switches an org or key group rule for the member, as far as the rule's lock allows.

    Field Type Meaning
    code string the rule's code, e.g. GR-ORG-PII-001
    enabled boolean turn it off or on for the member
    action string a different action, where the lock allows it
    clear boolean 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 is 404 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"}. The gear picks 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/onboarding answers {"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 (done defaults 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] downloads venom-backup-<org>-<date>.json ({"format": "venom.org-backup", "version": 1, "exported_at", "source", "sections", "reenter"}). members=1 includes members and roles.

  • POST /v1/org/restore takes:

    Field Type Default Meaning
    backup object required the exported JSON, at most 2 MiB
    dry_run boolean true plan only; nothing is written
    on_conflict string overwrite overwrite or keep (skip items that differ)
    sections string[] all e.g. ["gears", "routing", "budgets"]
    members boolean false change the roles of people already in the org

    A restore never deletes. Each item is planned as create, update (with the fields that differ) or skip (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/settings answers {"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-outcomes reports how a session went, in counts only. A report while the org has it off is 403 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/settings answers {"object": "venom.session_summaries.settings", "enabled"}. Off until an org admin turns it on. Ask the user before every upload.
  • POST /v1/session-summaries uploads a session's summary, already redacted on the machine. An upload while the org has it off is 403 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