---
title: Venom Cloud APIs overview
description: The four HTTP surfaces of Venom Cloud, the credentials each takes, the error shape, rate limits, request headers and where every route is documented.
section: cloud
order: 200
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/lib/auth/keys.ts, services/nodejs-cloud/lib/http/errors.ts, services/nodejs-cloud/lib/limits/index.ts, services/nodejs-cloud/proxy.ts, services/nodejs-cloud/components/console/rbac.ts, docs/cloud-mesh.md]
features: []
---

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](/docs/cloud.md).

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 {#first-request}

Create a client key in the console (Settings, API keys) and call the OpenAI-compatible surface:

```bash
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"}]}'
```

```ts
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);
```

```python
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 {#surfaces}

| Prefix | Who calls it | Credential | Page |
|---|---|---|---|
| `/v1/*` | apps, agents, the venom CLI | client key `vck_…` | [Inference API](/docs/cloud/api-inference.md), [Agent and CLI API](/docs/cloud/api-agent.md), [Sessions API](/docs/cloud/api-sessions.md), [Knowledge and tools API](/docs/cloud/api-knowledge.md) |
| `/api/admin/v1/*` | the console, org automation, the operator | admin token or key group admin key `vak_…` | [access](/docs/cloud/api-admin-access.md), [routing](/docs/cloud/api-admin-routing.md), [spend](/docs/cloud/api-admin-spend.md), [fleet](/docs/cloud/api-admin-fleet.md), [logs and audit](/docs/cloud/api-admin-observability.md), [knowledge and tools](/docs/cloud/api-admin-content.md), [customers and MSP](/docs/cloud/api-admin-msp.md) |
| `/api/mesh/v1/*` | daemons (the Go orchestrator in mesh mode) | join token `vjt_…`, then a signed daemon JWT | [Daemon API](/docs/mesh/daemon-api.md) |
| `/scim/v2/*` | your identity provider | a SCIM token | [SCIM API](/docs/cloud/api-scim.md) |
| `/api/cli/v1/*`, `/auth/*` | the venom CLI, browsers | none (device code), then a key | [Sign-in flows](/docs/cloud/api-auth-flows.md) |
| `/api/billing/*`, `/api/integrations/*`, `/api/clerk/*` | Stripe, Slack, Linear, Jira, Clerk | the sender's signature | [Webhooks](/docs/cloud/api-webhooks.md) |
| `/api/status`, `/api/audit/v1/*`, `/download/*`, `/docs/*` | anyone, auditors | none, or an auditor token | [Public endpoints](/docs/cloud/api-public.md) |

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 {#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 {#admin-credentials}

- **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](/docs/cloud/teams.md)); 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 {#roles}

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 {#errors}

Every error is OpenAI-shaped JSON, with `cache-control: no-store`:

```json
{"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](#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](/docs/cloud/api-inference.md#resume)).

## Rate limits and budgets {#limits}

- **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 {#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 {#conventions}

- 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.

## Related {#related}

- [Inference API](/docs/cloud/api-inference.md), [Admin API: orgs, members and keys](/docs/cloud/api-admin-access.md), [SCIM API](/docs/cloud/api-scim.md)
- [Log queries over the admin API](/docs/cloud/api-log-query.md), [Incoming webhooks](/docs/cloud/api-webhooks.md)
- [Cloud quickstart](/docs/getting-started/cloud-quickstart.md), [Connect a daemon](/docs/mesh/connect-daemon.md)
- [Orchestrator](/docs/orchestrator.md): the same `/v1` surface, self-hosted, without the cloud
