Venom Cloud APIs overview
The four HTTP surfaces of Venom Cloud, the credentials each takes, the error shape, rate limits, request headers and where every route is documented.
Venom Cloud is an HTTP service. Apps, agents and scripts talk to it the way the console does: JSON over HTTPS. These pages are for you if you build an app on Venom Cloud (a support bot, a collections SaaS, a CI job), if you script your org's setup, or if you run your own deployment. The console itself is described in the Venom Cloud section.
The hosted service is at https://cloud.usevenom.dev. A self-hosted deployment uses its own origin; every path
below is the same.
A first request
Create a client key in the console (Settings, API keys) and call the OpenAI-compatible surface:
export VENOM_CLOUD=https://cloud.usevenom.dev
export VENOM_KEY=vck_... # a client key
curl -s "$VENOM_CLOUD/v1/chat/completions" \
-H "Authorization: Bearer $VENOM_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "venom-auto", "messages": [{"role": "user", "content": "Say hi"}]}'import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://cloud.usevenom.dev/v1", apiKey: process.env.VENOM_KEY });
const r = await client.chat.completions.create({ model: "venom-auto", messages: [{ role: "user", content: "Say hi" }] });
console.log(r.choices[0].message.content);import os
from openai import OpenAI
client = OpenAI(base_url="https://cloud.usevenom.dev/v1", api_key=os.environ["VENOM_KEY"])
r = client.chat.completions.create(model="venom-auto", messages=[{"role": "user", "content": "Say hi"}])
print(r.choices[0].message.content)Any OpenAI SDK works: the cloud answers with the same bodies and the same SSE streams. Some requests answer
307 to a daemon's own address (the direct path); openai-python and fetch-based clients follow it. A client
that does not follow redirects can send x-venom-mesh-mode: relay.
The surfaces
| Prefix | Who calls it | Credential | Page |
|---|---|---|---|
/v1/* |
apps, agents, the venom CLI | client key vck_… |
Inference API, Agent and CLI API, Sessions API, Knowledge and tools API |
/api/admin/v1/* |
the console, org automation, the operator | admin token or key group admin key vak_… |
access, routing, spend, fleet, logs and audit, knowledge and tools, customers and MSP |
/api/mesh/v1/* |
daemons (the Go orchestrator in mesh mode) | join token vjt_…, then a signed daemon JWT |
Daemon API |
/scim/v2/* |
your identity provider | a SCIM token | SCIM API |
/api/cli/v1/*, /auth/* |
the venom CLI, browsers | none (device code), then a key | Sign-in flows |
/api/billing/*, /api/integrations/*, /api/clerk/* |
Stripe, Slack, Linear, Jira, Clerk | the sender's signature | Webhooks |
/api/status, /api/audit/v1/*, /download/*, /docs/* |
anyone, auditors | none, or an auditor token | Public endpoints |
The generated reference for every /v1 route (method, path, auth and a curl line) is at /docs/api/cloud.
These pages say what each route is for and how to use it.
Credentials
| Credential | Format | Sent as | Made by | Reaches |
|---|---|---|---|---|
| client key | vck_ + 43 characters |
Authorization: Bearer vck_… |
the console (Settings, API keys), POST /api/admin/v1/keys, or a CLI device login |
/v1/*, scoped to one key group: its models, limits and budgets |
| key group admin key | vak_ + 43 characters |
Authorization: Bearer vak_… |
only the cloud admin token, through POST /api/admin/v1/admin-keys |
/api/admin/v1/* as that key group's admin |
| cloud admin token | VENOM_CLOUD_ADMIN_TOKEN, 32 characters or more |
Authorization: Bearer … |
the deployment's operator, in its environment | all of /api/admin/v1/*, every org |
| join token | vjt_ + 43 characters |
the body of POST /api/mesh/v1/enroll |
POST /api/admin/v1/join-tokens or the console |
one daemon enrollment; default life 1 hour, at most 7 days |
| SCIM token | vsc_ + 43 characters |
Authorization: Bearer vsc_… |
an org owner (Settings, Single sign-on) | /scim/v2/* for that org |
The cloud stores only the SHA-256 of a key and its first 8 characters (the prefix the console shows). A key is shown once, when it is made. Key lookups are cached per instance for a short time, so a revoked key can work for a few more seconds on another instance.
A client key can carry:
- an allowlist and a denylist of models (
allowed_models,denied_models; the creator's role can narrow them further); rpmandtpmlimits;- a budget, a default project, an expiry (
expires_at) and a trust class (min_trust_class:team, orpublicto allow public daemons); - a pause (set by a spend-anomaly action). A paused key answers
403 key_pauseduntil someone resumes it.
A key that belongs to one of your org's resold customers takes that customer's limits and models, and stops
working (403 customer_inactive) while the customer is suspended or archived.
Who can use the admin API
- Self-hosted operators use
VENOM_CLOUD_ADMIN_TOKEN. Without it every admin route answers503 admin_not_configured. The token sees every org; listing routes take?tenant=<org id>to narrow. - Key group admin keys (
vak_…) act as their key group's admin: the key group's keys, daemons, join tokens, shares, usage and chargeback. A key group holds API keys, daemons, policies and GPU grants, not people (people are in org teams); the API keeps the nameteam, soteam_idis a key group's id. Org-wide routes (customers, MSP, SSO, org settings) refuse them with403 forbidden. Only the operator can mint one. - Members of a hosted org use the console. The console calls the admin API on their behalf with their role, so a page shows exactly what the role allows.
Roles and permissions
Org members have one role. The admin API checks permissions, never role names; a refusal is
403 forbidden with the role and the missing permission in the message (The viewer role cannot do this (keys:write).).
| Role | Permissions |
|---|---|
owner |
all, including billing:manage and sso:manage |
admin |
all except billing:manage and sso:manage |
developer |
the read set, plus keys:write, daemons:enroll, daemons:manage, routing:write, content:read, audit:read |
billing |
org:read, members:read, usage:read, billing:read, billing:manage |
viewer |
the read set: org:read, members:read, keys:read, providers:read, daemons:read, routing:read, logs:read, usage:read |
The full list: org:read, org:manage, members:read, members:manage, billing:read, billing:manage,
keys:read, keys:write, providers:read, providers:write, daemons:read, daemons:enroll,
daemons:manage, routing:read, routing:write, logs:read, content:read, content:settings,
usage:read, audit:read, sso:read, sso:manage. Each api-admin-* page names the permission a route needs.
Errors
Every error is OpenAI-shaped JSON, with cache-control: no-store:
{"error": {"message": "Invalid API key.", "type": "invalid_request_error", "code": "invalid_api_key", "param": null}}On /v1/* the type follows OpenAI (invalid_request_error for 400, 401, 404, 409 and 413,
permission_error for 403, rate_limit_error for 429, api_error for 5xx). On the admin and daemon surfaces
the type is mesh_error. Branch on code, not on message. Some errors add fields next to code
(paused_at, budget, suggested_model, reasons, upgrade_url).
| Status | code |
Meaning |
|---|---|---|
| 400 | invalid_request |
a bad body or query; the message names the field. Also invalid_rerank_request and other route-specific codes |
| 401 | invalid_api_key |
missing, unknown or revoked credential |
| 401 | key_expired |
the key is past its expires_at |
| 403 | forbidden |
the role, the key group scope or the credential type does not allow it |
| 403 | key_paused, customer_inactive |
see Credentials |
| 403 | model_not_allowed |
the key may not call this model (reason says why) |
| 403 | profile_forbidden, prompt_blocked, unpriced_model |
the route profile admits nothing, an org prompt filter refused the request, a model with no price |
| 403 | plan_limit_reached |
the org's plan does not cover it (upgrade_url) |
| 404 | model_not_found, not_found |
no daemon or provider serves the model; an unknown id |
| 409 | idempotency_conflict, conflict |
a finished job for the same Idempotency-Key; a duplicate name |
| 413 | request_too_large |
a body over the route's limit (4 MiB for inference; use the direct path) |
| 429 | rate_limit_exceeded, tpm_limit_exceeded |
the key's RPM or TPM window is full; retry-after says when it resets |
| 429 | budget_exceeded, spend_cap_reached, spend_limit_reached, plan_request_limit, session_paused |
a budget, the org's spend cap, a spend guard, the plan's request allowance, the session guard |
| 500 | internal_error |
a bug; retry once, then report it with the response's x-venom-job if there is one |
| 502 | daemon_error |
every daemon failed before the first byte |
| 503 | no_daemon_available, no_direct_path, mesh_unavailable, admin_not_configured, vault_not_configured |
nothing can serve now (reasons), the database is down, a deployment setting is missing (storing a secret without the vault is 409 vault_not_configured on some admin routes) |
| 504 | dispatch_timeout |
no daemon accepted the job in time |
A relayed stream that fails after the first byte cannot change its status code. It ends with an SSE event
data: {"error": {"code": "daemon_lost", "job_id": "…", "last_seq": 41}} (or daemon_error,
stream_time_limit). Resume a daemon_lost stream for 120 seconds with
GET /v1/mesh/jobs/{job_id}/stream?after=<last_seq> (Inference API).
Rate limits and budgets
- RPM and TPM are per key, in one-minute windows that start on the UTC minute. A request counts its
estimated tokens (prompt plus
max_tokens) up front, and the difference is settled when it ends. Over the limit:429 rate_limit_exceededwithretry-afterin seconds. A single request whose estimate is larger than the whole TPM limit gets429 tpm_limit_exceededand should be split, not retried. - Budgets and spend guards are checked before a request is sent, at the price of the costliest
candidate model. A soft limit adds
x-venom-spend-warning; adowngradeguard moves the request to a cheaper model and addsx-venom-spend-downgrade; a hard limit answers429. - The plan (hosted tier) can cap requests (
429 plan_request_limit, withx-should-retry: false).
Retry 429 rate_limit_exceeded, 502, 503 and 504 with backoff. Do not retry 401, 403, 413, or
a 429 that has x-should-retry: false.
Request and response headers
Optional headers on /v1 requests. None is forwarded to a daemon unless the table says so.
| Header | Effect |
|---|---|
x-venom-session, x-venom-parent-session |
the session id: requests of one session stick to one daemon (prefix-cache affinity); subagents name their parent |
x-venom-gear, x-venom-role, x-venom-project, x-venom-task |
attribution: spend is booked to that gear, role, project or work item (an issue or PR URL, owner/repo#123, ENG-142) |
x-venom-profile |
narrows routing for this request: cloud, cloud-first, daemons, daemons-first |
x-venom-mesh-mode |
auto (default), direct or relay |
x-venom-daemon |
pin a daemon by name or id |
x-venom-networks |
the networks the client can reach (tailnet:<name>,lan:<label>), for the direct path |
x-venom-service-tier, x-venom-urgency: batch |
the provider tier: auto, default, flex, priority, batch |
x-venom-experiment |
the gear experiment and arm the session is in |
x-venom-human-at |
when the person last wrote (epoch ms), for the org's session guard |
Idempotency-Key |
up to 255 characters; the same key within 24 hours re-attaches to the running job |
x-venom-dedup: off |
never join an identical in-flight request |
Response headers tell you what happened:
| Header | Value |
|---|---|
x-venom-job |
the job id: quote it when you report a problem |
x-venom-served-by |
daemon or cloud (the cloud's own providers) |
x-venom-mesh-mode |
direct or relay |
x-venom-daemon, x-venom-daemon-region |
which daemon served |
x-venom-model, x-venom-upstream, x-venom-fallback |
the model and upstream that served, and a fallback if one happened |
x-venom-route-reason |
affinity, p2c, argmin, pinned, session_pin, cloud, hedge, failover:<reason> |
x-venom-auto-tier, x-venom-auto-reason, x-venom-auto-class, x-venom-auto-source |
how venom-auto chose |
x-venom-spend-warning, x-venom-spend-downgrade |
a budget near or at its limit |
x-venom-prompt-filter, x-venom-prompt-filter-warning |
an org prompt filter changed or flagged the request |
x-venom-dedup |
joined when an identical request's job answered this one |
Bodies, pagination and ids
- Bodies are JSON, at most 4 MiB on the inference routes and 64 KiB to 1 MiB on admin routes (the route's
page says when it differs). Anything else:
413 request_too_large. Invalid JSON:400 invalid_request. - Admin listings answer
{"data": [...]}. Most return everything in scope, newest first, with a fixed cap; the routes that page takelimitand a cursor (starting_afterorbefore), named on their page. - Ids are UUIDs (UUIDv7 for jobs, daemons and keys, so they sort by time). Times are RFC 3339 in UTC; money
is in USD, except internal ledgers in nano-dollars (
*_nusd). - Every admin write is recorded in the org's audit log with who made it.
Related
- Inference API, Admin API: orgs, members and keys, SCIM API
- Log queries over the admin API, Incoming webhooks
- Cloud quickstart, Connect a daemon
- Orchestrator: the same
/v1surface, self-hosted, without the cloud