Skip to content
Docs menu

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.

View .md

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);
  • rpm and tpm limits;
  • a budget, a default project, an expiry (expires_at) and a trust class (min_trust_class: team, or public to allow public daemons);
  • a pause (set by a spend-anomaly action). A paused key answers 403 key_paused until 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 answers 503 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 name team, so team_id is a key group's id. Org-wide routes (customers, MSP, SSO, org settings) refuse them with 403 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_exceeded with retry-after in seconds. A single request whose estimate is larger than the whole TPM limit gets 429 tpm_limit_exceeded and 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; a downgrade guard moves the request to a cheaper model and adds x-venom-spend-downgrade; a hard limit answers 429.
  • The plan (hosted tier) can cap requests (429 plan_request_limit, with x-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 take limit and a cursor (starting_after or before), 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.