---
title: Venom Cloud API
description: "Every public /v1 route of Venom Cloud (115 operations): what it does, its client-key auth and a curl line."
section: api
order: 40
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/v1, services/nodejs-cloud/contracts, docs/cloud-mesh.md]
---
Generated from the cloud's `/v1` route handlers. Base URL: `https://cloud.usevenom.dev/v1`. The inference routes take the same paths and bodies as the orchestrator's OpenAI-compatible surface ([Orchestrator API](/docs/api/orchestrator)), so any OpenAI SDK works with `base_url` set to it.

## Authentication

Every route takes a client key: `Authorization: Bearer vck_…`. Create one in the console under Settings, API keys (it is shown once). A key belongs to one team; it sees that team's daemons, gears, library and sessions, and its spend counts against its own budget and the org's limits. A missing or wrong key is `401`. There are no unauthenticated `/v1` routes.

```bash
export VENOM_BASE_URL=https://cloud.usevenom.dev/v1
export VENOM_API_KEY=vck_…
curl "$VENOM_BASE_URL/models" -H "Authorization: Bearer $VENOM_API_KEY"
```

## Errors

Errors are OpenAI-shaped JSON: `{"error": {"message": "…", "type": "…", "code": "…", "param": null}}` with a matching HTTP status. `code` is stable and machine-readable (for example `policy_not_found`, `summaries_off`, `invalid_rerank_request`); `message` is for people.

## Operations

115 operations.

| Method | Path | Summary |
|---|---|---|
| POST | [`/v1/audio/speech`](#v1-post-v1-audio-speech) | Text to speech, OpenAI-compatible (`stream`, `stream_format: "sse"`, `x-venom-sample-rate`, `venom_options`). Served by the org's provider keys and the cloud's own, never by daemons; booked per character. |
| POST | [`/v1/audio/transcriptions`](#v1-post-v1-audio-transcriptions) | Speech to text, OpenAI-compatible multipart upload (up to 4.5 MB). Served by provider keys only; booked per second of audio. |
| POST | [`/v1/audio/translations`](#v1-post-v1-audio-translations) | Speech to English text, served and booked like transcriptions. |
| GET | [`/v1/audio/voices`](#v1-get-v1-audio-voices) | The voices of a text-to-speech model (`?model=`), from the provider that would serve it. |
| POST | [`/v1/chat/completions`](#v1-post-v1-chat-completions) | Chat completions, OpenAI-compatible (streaming with `stream: true`). Routed to one of the org's daemons, a trusted public node or the cloud's own providers. |
| GET | [`/v1/comms/calls`](#v1-get-v1-comms-calls) | Recent calls, newest first (`conversation_id`, `limit`, `cursor`). |
| POST | [`/v1/comms/calls`](#v1-post-v1-comms-calls) | Place a call that runs a script (`say`, `play`, `gather`, `pause`, `transfer`, `hangup`), or start a profile whose first step is a call; 201 with the call. |
| GET | [`/v1/comms/calls/{id}`](#v1-get-v1-comms-calls-id) | One call: status, duration, cost and the digits gathered. |
| POST | [`/v1/comms/calls/{id}/approve`](#v1-post-v1-comms-calls-id-approve) | Place an agent's `pending_approval` call now; the same rule as approving a message. |
| POST | [`/v1/comms/calls/{id}/reject`](#v1-post-v1-comms-calls-id-reject) | Cancel an agent's `pending_approval` call; the same rule as approving a message. |
| GET | [`/v1/comms/conversations`](#v1-get-v1-comms-conversations) | Threads with contacts, newest first (`channel`, `contact`); `session_open` for WhatsApp's 24-hour window. |
| GET | [`/v1/comms/conversations/{id}`](#v1-get-v1-comms-conversations-id) | One conversation with its messages and calls. |
| GET | [`/v1/comms/dispatches/{id}`](#v1-get-v1-comms-dispatches-id) | A profile run: its steps, the current one, when the next goes and who acknowledged. |
| POST | [`/v1/comms/dispatches/{id}/ack`](#v1-post-v1-comms-dispatches-id-ack) | Acknowledge a profile run so no further step goes out. |
| GET | [`/v1/comms/events`](#v1-get-v1-comms-events) | The Comms event feed (`message.received`, `message.status`, `call.*`, `dispatch.acknowledged`) after a cursor (`after`). |
| GET | [`/v1/comms/messages`](#v1-get-v1-comms-messages) | Recent messages, newest first (`status`, `conversation_id`, `limit`, `cursor`). |
| POST | [`/v1/comms/messages`](#v1-post-v1-comms-messages) | Send a message on `sms`, `whatsapp`, `rcs` or `telegram`, or start a profile (`profile`). Honours opt-outs, quiet hours and `Idempotency-Key`; 201 with the message and its status. |
| GET | [`/v1/comms/messages/{id}`](#v1-get-v1-comms-messages-id) | One message: status, provider, segments and cost. |
| POST | [`/v1/comms/messages/{id}/approve`](#v1-post-v1-comms-messages-id-approve) | Send an agent's `pending_approval` message now. A person's credential only (an OAuth token with `comms:write`, or your own personal key) whose role manages Comms; never the credential that asked, nor another of the same member's. |
| POST | [`/v1/comms/messages/{id}/reject`](#v1-post-v1-comms-messages-id-reject) | Cancel an agent's `pending_approval` message (status `canceled`); the same rule as approve. |
| DELETE | [`/v1/comms/optouts`](#v1-delete-v1-comms-optouts) | Lift an opt-out (`?contact=…&channel=…`); 204. |
| GET | [`/v1/comms/optouts`](#v1-get-v1-comms-optouts) | Contacts who must not be messaged or called, per channel (`contact` filters). |
| POST | [`/v1/comms/optouts`](#v1-post-v1-comms-optouts) | Opt a contact out (`{contact, channel, note}`; channel `*` for all). |
| GET | [`/v1/comms/profiles`](#v1-get-v1-comms-profiles) | Routing profiles: the org's own and the built-in `page`, `support` and `notify`. |
| GET | [`/v1/comms/senders`](#v1-get-v1-comms-senders) | The org's numbers and sender ids, with their channels and countries. |
| POST | [`/v1/comms/simulate`](#v1-post-v1-comms-simulate) | Make the org's fake provider report an inbound message, a status, an answered call, a key press or a hang-up; 409 `no_fake_provider` without one. |
| GET | [`/v1/comms/templates`](#v1-get-v1-comms-templates) | Message templates with their approval state (`channel`, `status`); WhatsApp outside its 24-hour window sends an `approved` one. |
| POST | [`/v1/comms/templates/sync`](#v1-post-v1-comms-templates-sync) | Read the providers' templates and their approval state again; answers how many were synced. |
| POST | [`/v1/completions`](#v1-post-v1-completions) | Legacy text completions, OpenAI-compatible, routed like chat completions. |
| GET | [`/v1/deprecations`](#v1-get-v1-deprecations) | The org's gears that name a model its provider retires soon or has retired, for `venom doctor`. |
| POST | [`/v1/embeddings`](#v1-post-v1-embeddings) | Embeddings, OpenAI-compatible. |
| POST | [`/v1/evals/jobs/{id}/progress`](#v1-post-v1-evals-jobs-id-progress) | Report trials done and renew the lease; answers stop when the run was cancelled or hit its cap. |
| POST | [`/v1/evals/jobs/{id}/result`](#v1-post-v1-evals-jobs-id-result) | Finish an eval run: its key is revoked and the paired comparison computed. |
| POST | [`/v1/evals/runners`](#v1-post-v1-evals-runners) | An eval runner's hello and heartbeat, one per team and name. |
| POST | [`/v1/evals/runners/{id}/claim`](#v1-post-v1-evals-runners-id-claim) | Claim the oldest eval run queued to this runner, with a key budgeted at its cap; 204 when there is none. |
| GET | [`/v1/fleet`](#v1-get-v1-fleet) | The team's fleet: the agents its machines published in the last 60 s (`?repo=` filters). |
| PUT | [`/v1/fleet`](#v1-put-v1-fleet) | Publish this machine's full list of running agents for one repository to the team's fleet view (optional `inbox_url`). |
| GET | [`/v1/gears`](#v1-get-v1-gears) | The org's gears for the venom CLI, filtered by the key's allowed models; the same body the orchestrator serves. |
| POST | [`/v1/gears/experiments/{id}/sessions`](#v1-post-v1-gears-experiments-id-sessions) | The CLI's report on one session of a gear experiment, at its end or when the user opts out. |
| GET | [`/v1/guardrails`](#v1-get-v1-guardrails) | The guardrails that apply to the key's member: org and team rules with their locks, the member's switches and own rules, the catalog. |
| POST | [`/v1/guardrails/draft`](#v1-post-v1-guardrails-draft) | Draft one of the member's own guardrails from a sentence (`{text, gear?}`). Nothing is saved. |
| PUT | [`/v1/guardrails/overrides`](#v1-put-v1-guardrails-overrides) | Switch an org or team guardrail for the key's member (`{code, enabled?, action?, clear?}`), as far as the rule's lock allows. |
| GET | [`/v1/handoffs`](#v1-get-v1-handoffs) | The key's handoff inbox (`?box=inbox`) or what it sent (`?box=sent`). |
| POST | [`/v1/handoffs`](#v1-post-v1-handoffs) | Hand a session to a teammate or a team. |
| DELETE | [`/v1/handoffs/{id}`](#v1-delete-v1-handoffs-id) | Cancel a handoff you sent. |
| GET | [`/v1/handoffs/{id}`](#v1-get-v1-handoffs-id) | One handoff; `?trace=1` adds the shared transcript. |
| POST | [`/v1/handoffs/{id}/accept`](#v1-post-v1-handoffs-id-accept) | Take a handoff; `409 already_accepted` when someone else took it first. |
| POST | [`/v1/handoffs/{id}/decline`](#v1-post-v1-handoffs-id-decline) | Decline a handoff (`{reason?}`). |
| POST | [`/v1/intake/jobs/{id}/progress`](#v1-post-v1-intake-jobs-id-progress) | Renew an intake job's lease; answers stop on cancel, cap or loss. |
| POST | [`/v1/intake/jobs/{id}/result`](#v1-post-v1-intake-jobs-id-result) | Finish an intake job: its key is revoked and the issue gets a comment. |
| POST | [`/v1/intake/runners`](#v1-post-v1-intake-runners) | An intake runner's hello and heartbeat, one per team and name. |
| POST | [`/v1/intake/runners/{id}/claim`](#v1-post-v1-intake-runners-id-claim) | Claim the org's oldest queued intake job for a repository this runner has; 204 when there is none. |
| POST | [`/v1/knowledge/ask`](#v1-post-v1-knowledge-ask) | Ask the org's knowledge (`{question, gear?, local?}`): an answer from memory, the library and session summaries the key may read, with sources. |
| GET | [`/v1/library`](#v1-get-v1-library) | The org's published prompts and skills in the key's team's scope. Supports `If-None-Match` (304). |
| POST | [`/v1/library/experiments/{id}/sessions`](#v1-post-v1-library-experiments-id-sessions) | Join a session to a library prompt A/B test (`{session_id, arm}`). |
| POST | [`/v1/library/usage`](#v1-post-v1-library-usage) | How often the CLI ran library items since its last report (`{counts: [{kind, name, count}]}`). Counts only. |
| POST | [`/v1/live-sessions`](#v1-post-v1-live-sessions) | Start a live share of a venom session (201), or update this team's live share of it (200). |
| DELETE | [`/v1/live-sessions/{id}`](#v1-delete-v1-live-sessions-id) | Stop a live share. |
| PATCH | [`/v1/live-sessions/{id}`](#v1-patch-v1-live-sessions-id) | Change a live share's grants, audience or title, or extend it. |
| POST | [`/v1/live-sessions/{id}/sync`](#v1-post-v1-live-sessions-id-sync) | Push transcript items and get back viewers, grants and queued co-driver inputs; `410 live_ended` once stopped. |
| GET | [`/v1/marketplace`](#v1-get-v1-marketplace) | The org's approved plugins, skills and MCP packages (`venom plugin search`). Supports `If-None-Match` (304). |
| GET | [`/v1/marketplace/{name}`](#v1-get-v1-marketplace-name) | The signed manifest of a marketplace package (`?version=`), verified by `venom plugin install org:<name>`. |
| GET | [`/v1/marketplace/{name}/bundle`](#v1-get-v1-marketplace-name-bundle) | An approved version's `.tgz` (`?version=`); the CLI checks its SHA-256 against the signed manifest. |
| POST | [`/v1/marketplace/installs`](#v1-post-v1-marketplace-installs) | Count an install or removal (`{name, version, event}`). |
| GET | [`/v1/memory`](#v1-get-v1-memory) | The org's approved memory facts in the key's team's scope, for the CLI's prompt. Supports `If-None-Match` (304). |
| POST | [`/v1/memory/proposals`](#v1-post-v1-memory-proposals) | Propose a fact for the org's memory (`{text, scope?, repo?, reason?, session_id?}`); pending until an admin approves it. |
| GET | [`/v1/mesh/daemons`](#v1-get-v1-mesh-daemons) | The daemons this key can use: name, region, models, state and load. No endpoints and no owners' private labels. |
| GET | [`/v1/mesh/jobs/{job_id}/stream`](#v1-get-v1-mesh-jobs-job_id-stream) | Resume a relayed stream after `?after=<seq>`, then follow it live. Same key only; kept for 120 s after the end. |
| POST | [`/v1/mesh/route`](#v1-post-v1-mesh-route) | For mesh-aware clients: pick a daemon for a model and session and get its address and ticket, without sending the request. |
| GET | [`/v1/models`](#v1-get-v1-models) | The models this key may use: the union over the org's live daemons, trusted public nodes and the cloud's providers. |
| GET | [`/v1/models/{id…}`](#v1-get-v1-models-id) | One model from the list above, by id (ids may contain slashes). |
| GET | [`/v1/onboarding`](#v1-get-v1-onboarding) | The org's onboarding paths with the key's member's progress, for `venom onboard`. |
| POST | [`/v1/onboarding/steps`](#v1-post-v1-onboarding-steps) | Mark a manual onboarding step done or undo it (`{path_id, step_id, done?}`). |
| GET | [`/v1/org/backup`](#v1-get-v1-org-backup) | Export the org (`venom cloud backup`, `?members=1` adds members). The key's creator must be an owner or admin. |
| POST | [`/v1/org/restore`](#v1-post-v1-org-restore) | Restore an org backup (`venom cloud restore`; `dry_run`, `on_conflict`, `sections`). The key's creator must be an owner or admin. |
| GET | [`/v1/outreach/enrollments`](#v1-get-v1-outreach-enrollments) | A sequence's enrollments (`sequence_id`). |
| POST | [`/v1/outreach/enrollments`](#v1-post-v1-outreach-enrollments) | Enroll people (`sequenceId`, `personIds`, `dealId`, `consentBasis`); 201 with `enrolled` and `skipped` (each with its reason). |
| POST | [`/v1/outreach/enrollments/{id}`](#v1-post-v1-outreach-enrollments-id) | Pause, resume or stop one enrollment (`action`). |
| GET | [`/v1/outreach/queue`](#v1-get-v1-outreach-queue) | Drafts waiting for your approval (`kind=approval`) or steps to send yourself (`kind=manual`), oldest first (`limit`). |
| POST | [`/v1/outreach/runs/{id}/approve`](#v1-post-v1-outreach-runs-id-approve) | Approve a draft, optionally with an edited `subject` or `body`; it goes out inside the send window. Keys are agents: 403 `approval_required` unless the sequence sends without approval. |
| POST | [`/v1/outreach/runs/{id}/hold`](#v1-post-v1-outreach-runs-id-hold) | Hold a timed draft: its auto-send time is removed and it waits for you in the approval queue. |
| POST | [`/v1/outreach/runs/{id}/skip`](#v1-post-v1-outreach-runs-id-skip) | Skip a step; the enrollment moves on to the next one. |
| POST | [`/v1/outreach/runs/{id}/tapped`](#v1-post-v1-outreach-runs-id-tapped) | Mark a tap-to-send step or task as sent by you; the next step is scheduled. |
| GET | [`/v1/outreach/sequences`](#v1-get-v1-outreach-sequences) | Your sequences with their steps and counts (`status`); a team key lists every sequence. |
| POST | [`/v1/outreach/sequences`](#v1-post-v1-outreach-sequences) | Create a sequence (`name`, `purpose`, `steps`, and optionally `status`, `approval`, `tone`, `sender`, `stopOn`, `sendWindow`, `dailyCap`); 201. |
| DELETE | [`/v1/outreach/sequences/{id}`](#v1-delete-v1-outreach-sequences-id) | Archive a sequence: every live enrollment stops (`archived`); 204. |
| GET | [`/v1/outreach/sequences/{id}`](#v1-get-v1-outreach-sequences-id) | One sequence: settings, steps and counts. |
| PUT | [`/v1/outreach/sequences/{id}`](#v1-put-v1-outreach-sequences-id) | Replace one of your sequences; the steps replace its steps in order. |
| GET | [`/v1/policy`](#v1-get-v1-policy) | The caller's team's current signed org policy envelope (`venom.policy/v1`, Ed25519), or `404 policy_not_found`. |
| GET | [`/v1/policy-key`](#v1-get-v1-policy-key) | The public key that signs this tenant's policies; `503 policy_signing_not_configured` when there is none. |
| POST | [`/v1/prewarm`](#v1-post-v1-prewarm) | Ask the team's live daemons that advertise these models (`{models, keep_alive_s?}`) to load them on their next heartbeat. |
| POST | [`/v1/redteam/runs`](#v1-post-v1-redteam-runs) | Run the red-team corpus against the key's guardrails (`venom redteam run`); kept for the console's trend unless `dry_run`. |
| POST | [`/v1/rerank`](#v1-post-v1-rerank) | Rerank documents against a query (results by relevance). A malformed body is `400 invalid_rerank_request` before anything is spent. |
| POST | [`/v1/responses`](#v1-post-v1-responses) | The OpenAI Responses API, routed like chat completions; `background: true` starts a background response. |
| DELETE | [`/v1/responses/{id}`](#v1-delete-v1-responses-id) | Delete a background response your team started. |
| GET | [`/v1/responses/{id}`](#v1-get-v1-responses-id) | A background response your team started; `?stream=true&starting_after=N` replays and follows its events. |
| POST | [`/v1/responses/{id}/cancel`](#v1-post-v1-responses-id-cancel) | Stop a queued or running background response. Idempotent: an ended one comes back as it ended. |
| GET | [`/v1/routing`](#v1-get-v1-routing) | The routing table as this key sees it (`targets` are daemons), the same body as the orchestrator's `venom.routing`. |
| POST | [`/v1/search`](#v1-post-v1-search) | Venom Search: the org's own metasearch over official APIs and open data (`docs/public/cloud/search.md`). `404 search_disabled` until an owner or admin turns it on in Settings, Search; no engine is asked before. |
| POST | [`/v1/serve/sessions`](#v1-post-v1-serve-sessions) | Create a `venom serve` session on one of the team's daemons and bind it there. |
| DELETE | [`/v1/serve/sessions/{id}[/{rest…}]`](#v1-delete-v1-serve-sessions-id-rest) | Any harness server `DELETE` route of a bound session, relayed to its daemon. |
| GET | [`/v1/serve/sessions/{id}[/{rest…}]`](#v1-get-v1-serve-sessions-id-rest) | Any harness server `GET` route of a bound session (events, state), relayed to its daemon. |
| PATCH | [`/v1/serve/sessions/{id}[/{rest…}]`](#v1-patch-v1-serve-sessions-id-rest) | Any harness server `PATCH` route of a bound session, relayed to its daemon. |
| POST | [`/v1/serve/sessions/{id}[/{rest…}]`](#v1-post-v1-serve-sessions-id-rest) | Any harness server `POST` route of a bound session (prompt, approvals); `…/resume` moves it to another daemon. |
| PUT | [`/v1/serve/sessions/{id}[/{rest…}]`](#v1-put-v1-serve-sessions-id-rest) | Any harness server `PUT` route of a bound session, relayed to its daemon. |
| POST | [`/v1/session-outcomes`](#v1-post-v1-session-outcomes) | Report how a session went, counts only (`403 outcomes_off` when the org turned reports off). |
| GET | [`/v1/session-outcomes/settings`](#v1-get-v1-session-outcomes-settings) | Whether the org takes session outcome reports (`{enabled}`). |
| POST | [`/v1/session-shares`](#v1-post-v1-session-shares) | Share a redacted venom session trace with the org; a re-share of the same session replaces it. |
| DELETE | [`/v1/session-shares/{id}`](#v1-delete-v1-session-shares-id) | Remove a shared session (the sharing team only). |
| POST | [`/v1/session-summaries`](#v1-post-v1-session-summaries) | Upload a session's redacted summary when the org opted in (`403 summaries_off` otherwise). |
| GET | [`/v1/session-summaries/settings`](#v1-get-v1-session-summaries-settings) | Whether the org collects session summaries (`{enabled}`), so venom asks first. |
| POST | [`/v1/systemone`](#v1-post-v1-systemone) | A decision model's fast classification call, routed like chat completions. |
| POST | [`/v1/task-outcomes`](#v1-post-v1-task-outcomes) | Report that a task's pull request merged or its issue closed, for cost per outcome. |
| GET | [`/v1/usage`](#v1-get-v1-usage) | Usage for the key, the same body as the orchestrator's `venom.usage`, from the cloud ledger. |
| GET | [`/v1/usage/summary`](#v1-get-v1-usage-summary) | The calling key's spend by day, gear, role and model, and its costliest sessions, for `venom cost`. |

## Inference

### POST /v1/chat/completions {#v1-post-v1-chat-completions}

Chat completions, OpenAI-compatible (streaming with `stream: true`). Routed to one of the org's daemons, a trusted public node or the cloud's own providers.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/chat/completions' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/completions {#v1-post-v1-completions}

Legacy text completions, OpenAI-compatible, routed like chat completions.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/completions' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/embeddings {#v1-post-v1-embeddings}

Embeddings, OpenAI-compatible.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/embeddings' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/models {#v1-get-v1-models}

The models this key may use: the union over the org's live daemons, trusted public nodes and the cloud's providers.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/models' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/models/{id…} {#v1-get-v1-models-id}

One model from the list above, by id (ids may contain slashes).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/models/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/rerank {#v1-post-v1-rerank}

Rerank documents against a query (results by relevance). A malformed body is `400 invalid_rerank_request` before anything is spent.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/rerank' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/responses {#v1-post-v1-responses}

The OpenAI Responses API, routed like chat completions; `background: true` starts a background response.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/responses' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### DELETE /v1/responses/{id} {#v1-delete-v1-responses-id}

Delete a background response your team started.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X DELETE 'https://cloud.usevenom.dev/v1/responses/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/responses/{id} {#v1-get-v1-responses-id}

A background response your team started; `?stream=true&starting_after=N` replays and follows its events.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/responses/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/responses/{id}/cancel {#v1-post-v1-responses-id-cancel}

Stop a queued or running background response. Idempotent: an ended one comes back as it ended.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/responses/<id>/cancel' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/systemone {#v1-post-v1-systemone}

A decision model's fast classification call, routed like chat completions.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/systemone' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

## Routing and the mesh

### GET /v1/mesh/daemons {#v1-get-v1-mesh-daemons}

The daemons this key can use: name, region, models, state and load. No endpoints and no owners' private labels.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/mesh/daemons' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/mesh/jobs/{job_id}/stream {#v1-get-v1-mesh-jobs-job_id-stream}

Resume a relayed stream after `?after=<seq>`, then follow it live. Same key only; kept for 120 s after the end.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/mesh/jobs/<job_id>/stream' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/mesh/route {#v1-post-v1-mesh-route}

For mesh-aware clients: pick a daemon for a model and session and get its address and ticket, without sending the request.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/mesh/route' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/prewarm {#v1-post-v1-prewarm}

Ask the team's live daemons that advertise these models (`{models, keep_alive_s?}`) to load them on their next heartbeat.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/prewarm' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/routing {#v1-get-v1-routing}

The routing table as this key sees it (`targets` are daemons), the same body as the orchestrator's `venom.routing`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/routing' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

## Gears, policy and guardrails

### GET /v1/deprecations {#v1-get-v1-deprecations}

The org's gears that name a model its provider retires soon or has retired, for `venom doctor`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/deprecations' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/gears {#v1-get-v1-gears}

The org's gears for the venom CLI, filtered by the key's allowed models; the same body the orchestrator serves.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/gears' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/gears/experiments/{id}/sessions {#v1-post-v1-gears-experiments-id-sessions}

The CLI's report on one session of a gear experiment, at its end or when the user opts out.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/gears/experiments/<id>/sessions' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/guardrails {#v1-get-v1-guardrails}

The guardrails that apply to the key's member: org and team rules with their locks, the member's switches and own rules, the catalog.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/guardrails' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/guardrails/draft {#v1-post-v1-guardrails-draft}

Draft one of the member's own guardrails from a sentence (`{text, gear?}`). Nothing is saved.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/guardrails/draft' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### PUT /v1/guardrails/overrides {#v1-put-v1-guardrails-overrides}

Switch an org or team guardrail for the key's member (`{code, enabled?, action?, clear?}`), as far as the rule's lock allows.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X PUT 'https://cloud.usevenom.dev/v1/guardrails/overrides' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/policy {#v1-get-v1-policy}

The caller's team's current signed org policy envelope (`venom.policy/v1`, Ed25519), or `404 policy_not_found`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/policy' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/policy-key {#v1-get-v1-policy-key}

The public key that signs this tenant's policies; `503 policy_signing_not_configured` when there is none.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/policy-key' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

## Library, memory and marketplace

### POST /v1/knowledge/ask {#v1-post-v1-knowledge-ask}

Ask the org's knowledge (`{question, gear?, local?}`): an answer from memory, the library and session summaries the key may read, with sources.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/knowledge/ask' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/library {#v1-get-v1-library}

The org's published prompts and skills in the key's team's scope. Supports `If-None-Match` (304).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/library' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/library/experiments/{id}/sessions {#v1-post-v1-library-experiments-id-sessions}

Join a session to a library prompt A/B test (`{session_id, arm}`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/library/experiments/<id>/sessions' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/library/usage {#v1-post-v1-library-usage}

How often the CLI ran library items since its last report (`{counts: [{kind, name, count}]}`). Counts only.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/library/usage' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/marketplace {#v1-get-v1-marketplace}

The org's approved plugins, skills and MCP packages (`venom plugin search`). Supports `If-None-Match` (304).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/marketplace' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/marketplace/{name} {#v1-get-v1-marketplace-name}

The signed manifest of a marketplace package (`?version=`), verified by `venom plugin install org:<name>`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/marketplace/<name>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/marketplace/{name}/bundle {#v1-get-v1-marketplace-name-bundle}

An approved version's `.tgz` (`?version=`); the CLI checks its SHA-256 against the signed manifest.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/marketplace/<name>/bundle' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/marketplace/installs {#v1-post-v1-marketplace-installs}

Count an install or removal (`{name, version, event}`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/marketplace/installs' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/memory {#v1-get-v1-memory}

The org's approved memory facts in the key's team's scope, for the CLI's prompt. Supports `If-None-Match` (304).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/memory' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/memory/proposals {#v1-post-v1-memory-proposals}

Propose a fact for the org's memory (`{text, scope?, repo?, reason?, session_id?}`); pending until an admin approves it.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/memory/proposals' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/onboarding {#v1-get-v1-onboarding}

The org's onboarding paths with the key's member's progress, for `venom onboard`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/onboarding' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/onboarding/steps {#v1-post-v1-onboarding-steps}

Mark a manual onboarding step done or undo it (`{path_id, step_id, done?}`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/onboarding/steps' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

## Usage

### POST /v1/task-outcomes {#v1-post-v1-task-outcomes}

Report that a task's pull request merged or its issue closed, for cost per outcome.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/task-outcomes' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/usage {#v1-get-v1-usage}

Usage for the key, the same body as the orchestrator's `venom.usage`, from the cloud ledger.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/usage' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/usage/summary {#v1-get-v1-usage-summary}

The calling key's spend by day, gear, role and model, and its costliest sessions, for `venom cost`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/usage/summary' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

## Sessions

### GET /v1/fleet {#v1-get-v1-fleet}

The team's fleet: the agents its machines published in the last 60 s (`?repo=` filters).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/fleet' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### PUT /v1/fleet {#v1-put-v1-fleet}

Publish this machine's full list of running agents for one repository to the team's fleet view (optional `inbox_url`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X PUT 'https://cloud.usevenom.dev/v1/fleet' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/handoffs {#v1-get-v1-handoffs}

The key's handoff inbox (`?box=inbox`) or what it sent (`?box=sent`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/handoffs' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/handoffs {#v1-post-v1-handoffs}

Hand a session to a teammate or a team.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/handoffs' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### DELETE /v1/handoffs/{id} {#v1-delete-v1-handoffs-id}

Cancel a handoff you sent.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X DELETE 'https://cloud.usevenom.dev/v1/handoffs/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/handoffs/{id} {#v1-get-v1-handoffs-id}

One handoff; `?trace=1` adds the shared transcript.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/handoffs/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/handoffs/{id}/accept {#v1-post-v1-handoffs-id-accept}

Take a handoff; `409 already_accepted` when someone else took it first.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/handoffs/<id>/accept' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/handoffs/{id}/decline {#v1-post-v1-handoffs-id-decline}

Decline a handoff (`{reason?}`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/handoffs/<id>/decline' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/live-sessions {#v1-post-v1-live-sessions}

Start a live share of a venom session (201), or update this team's live share of it (200).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/live-sessions' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### DELETE /v1/live-sessions/{id} {#v1-delete-v1-live-sessions-id}

Stop a live share.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X DELETE 'https://cloud.usevenom.dev/v1/live-sessions/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### PATCH /v1/live-sessions/{id} {#v1-patch-v1-live-sessions-id}

Change a live share's grants, audience or title, or extend it.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X PATCH 'https://cloud.usevenom.dev/v1/live-sessions/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/live-sessions/{id}/sync {#v1-post-v1-live-sessions-id-sync}

Push transcript items and get back viewers, grants and queued co-driver inputs; `410 live_ended` once stopped.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/live-sessions/<id>/sync' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/serve/sessions {#v1-post-v1-serve-sessions}

Create a `venom serve` session on one of the team's daemons and bind it there.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/serve/sessions' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### DELETE /v1/serve/sessions/{id}[/{rest…}] {#v1-delete-v1-serve-sessions-id-rest}

Any harness server `DELETE` route of a bound session, relayed to its daemon.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X DELETE 'https://cloud.usevenom.dev/v1/serve/sessions/<id>/<rest>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/serve/sessions/{id}[/{rest…}] {#v1-get-v1-serve-sessions-id-rest}

Any harness server `GET` route of a bound session (events, state), relayed to its daemon.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/serve/sessions/<id>/<rest>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### PATCH /v1/serve/sessions/{id}[/{rest…}] {#v1-patch-v1-serve-sessions-id-rest}

Any harness server `PATCH` route of a bound session, relayed to its daemon.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X PATCH 'https://cloud.usevenom.dev/v1/serve/sessions/<id>/<rest>' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/serve/sessions/{id}[/{rest…}] {#v1-post-v1-serve-sessions-id-rest}

Any harness server `POST` route of a bound session (prompt, approvals); `…/resume` moves it to another daemon.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/serve/sessions/<id>/<rest>' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### PUT /v1/serve/sessions/{id}[/{rest…}] {#v1-put-v1-serve-sessions-id-rest}

Any harness server `PUT` route of a bound session, relayed to its daemon.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X PUT 'https://cloud.usevenom.dev/v1/serve/sessions/<id>/<rest>' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/session-outcomes {#v1-post-v1-session-outcomes}

Report how a session went, counts only (`403 outcomes_off` when the org turned reports off).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/session-outcomes' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/session-outcomes/settings {#v1-get-v1-session-outcomes-settings}

Whether the org takes session outcome reports (`{enabled}`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/session-outcomes/settings' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/session-shares {#v1-post-v1-session-shares}

Share a redacted venom session trace with the org; a re-share of the same session replaces it.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/session-shares' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### DELETE /v1/session-shares/{id} {#v1-delete-v1-session-shares-id}

Remove a shared session (the sharing team only).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X DELETE 'https://cloud.usevenom.dev/v1/session-shares/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/session-summaries {#v1-post-v1-session-summaries}

Upload a session's redacted summary when the org opted in (`403 summaries_off` otherwise).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/session-summaries' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/session-summaries/settings {#v1-get-v1-session-summaries-settings}

Whether the org collects session summaries (`{enabled}`), so venom asks first.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/session-summaries/settings' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

## Org tools

### GET /v1/org/backup {#v1-get-v1-org-backup}

Export the org (`venom cloud backup`, `?members=1` adds members). The key's creator must be an owner or admin.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/org/backup' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/org/restore {#v1-post-v1-org-restore}

Restore an org backup (`venom cloud restore`; `dry_run`, `on_conflict`, `sections`). The key's creator must be an owner or admin.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/org/restore' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/redteam/runs {#v1-post-v1-redteam-runs}

Run the red-team corpus against the key's guardrails (`venom redteam run`); kept for the console's trend unless `dry_run`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/redteam/runs' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

## Runners

### POST /v1/evals/jobs/{id}/progress {#v1-post-v1-evals-jobs-id-progress}

Report trials done and renew the lease; answers stop when the run was cancelled or hit its cap.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/evals/jobs/<id>/progress' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/evals/jobs/{id}/result {#v1-post-v1-evals-jobs-id-result}

Finish an eval run: its key is revoked and the paired comparison computed.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/evals/jobs/<id>/result' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/evals/runners {#v1-post-v1-evals-runners}

An eval runner's hello and heartbeat, one per team and name.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/evals/runners' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/evals/runners/{id}/claim {#v1-post-v1-evals-runners-id-claim}

Claim the oldest eval run queued to this runner, with a key budgeted at its cap; 204 when there is none.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/evals/runners/<id>/claim' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/intake/jobs/{id}/progress {#v1-post-v1-intake-jobs-id-progress}

Renew an intake job's lease; answers stop on cancel, cap or loss.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/intake/jobs/<id>/progress' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/intake/jobs/{id}/result {#v1-post-v1-intake-jobs-id-result}

Finish an intake job: its key is revoked and the issue gets a comment.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/intake/jobs/<id>/result' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/intake/runners {#v1-post-v1-intake-runners}

An intake runner's hello and heartbeat, one per team and name.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/intake/runners' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/intake/runners/{id}/claim {#v1-post-v1-intake-runners-id-claim}

Claim the org's oldest queued intake job for a repository this runner has; 204 when there is none.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/intake/runners/<id>/claim' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

## Comms

### GET /v1/comms/calls {#v1-get-v1-comms-calls}

Recent calls, newest first (`conversation_id`, `limit`, `cursor`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/calls' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/calls {#v1-post-v1-comms-calls}

Place a call that runs a script (`say`, `play`, `gather`, `pause`, `transfer`, `hangup`), or start a profile whose first step is a call; 201 with the call.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/calls' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/comms/calls/{id} {#v1-get-v1-comms-calls-id}

One call: status, duration, cost and the digits gathered.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/calls/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/calls/{id}/approve {#v1-post-v1-comms-calls-id-approve}

Place an agent's `pending_approval` call now; the same rule as approving a message.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/calls/<id>/approve' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/comms/calls/{id}/reject {#v1-post-v1-comms-calls-id-reject}

Cancel an agent's `pending_approval` call; the same rule as approving a message.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/calls/<id>/reject' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/comms/conversations {#v1-get-v1-comms-conversations}

Threads with contacts, newest first (`channel`, `contact`); `session_open` for WhatsApp's 24-hour window.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/conversations' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/comms/conversations/{id} {#v1-get-v1-comms-conversations-id}

One conversation with its messages and calls.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/conversations/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/comms/dispatches/{id} {#v1-get-v1-comms-dispatches-id}

A profile run: its steps, the current one, when the next goes and who acknowledged.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/dispatches/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/dispatches/{id}/ack {#v1-post-v1-comms-dispatches-id-ack}

Acknowledge a profile run so no further step goes out.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/dispatches/<id>/ack' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/comms/events {#v1-get-v1-comms-events}

The Comms event feed (`message.received`, `message.status`, `call.*`, `dispatch.acknowledged`) after a cursor (`after`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/events' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/comms/messages {#v1-get-v1-comms-messages}

Recent messages, newest first (`status`, `conversation_id`, `limit`, `cursor`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/messages' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/messages {#v1-post-v1-comms-messages}

Send a message on `sms`, `whatsapp`, `rcs` or `telegram`, or start a profile (`profile`). Honours opt-outs, quiet hours and `Idempotency-Key`; 201 with the message and its status.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/messages' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/comms/messages/{id} {#v1-get-v1-comms-messages-id}

One message: status, provider, segments and cost.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/messages/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/messages/{id}/approve {#v1-post-v1-comms-messages-id-approve}

Send an agent's `pending_approval` message now. A person's credential only (an OAuth token with `comms:write`, or your own personal key) whose role manages Comms; never the credential that asked, nor another of the same member's.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/messages/<id>/approve' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/comms/messages/{id}/reject {#v1-post-v1-comms-messages-id-reject}

Cancel an agent's `pending_approval` message (status `canceled`); the same rule as approve.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/messages/<id>/reject' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### DELETE /v1/comms/optouts {#v1-delete-v1-comms-optouts}

Lift an opt-out (`?contact=…&channel=…`); 204.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X DELETE 'https://cloud.usevenom.dev/v1/comms/optouts' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/comms/optouts {#v1-get-v1-comms-optouts}

Contacts who must not be messaged or called, per channel (`contact` filters).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/optouts' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/optouts {#v1-post-v1-comms-optouts}

Opt a contact out (`{contact, channel, note}`; channel `*` for all).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/optouts' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/comms/profiles {#v1-get-v1-comms-profiles}

Routing profiles: the org's own and the built-in `page`, `support` and `notify`.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/profiles' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/comms/senders {#v1-get-v1-comms-senders}

The org's numbers and sender ids, with their channels and countries.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/senders' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/simulate {#v1-post-v1-comms-simulate}

Make the org's fake provider report an inbound message, a status, an answered call, a key press or a hang-up; 409 `no_fake_provider` without one.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/simulate' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/comms/templates {#v1-get-v1-comms-templates}

Message templates with their approval state (`channel`, `status`); WhatsApp outside its 24-hour window sends an `approved` one.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/comms/templates' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/comms/templates/sync {#v1-post-v1-comms-templates-sync}

Read the providers' templates and their approval state again; answers how many were synced.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/comms/templates/sync' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

## Other

### POST /v1/audio/speech {#v1-post-v1-audio-speech}

Text to speech, OpenAI-compatible (`stream`, `stream_format: "sse"`, `x-venom-sample-rate`, `venom_options`). Served by the org's provider keys and the cloud's own, never by daemons; booked per character.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/audio/speech' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/audio/transcriptions {#v1-post-v1-audio-transcriptions}

Speech to text, OpenAI-compatible multipart upload (up to 4.5 MB). Served by provider keys only; booked per second of audio.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/audio/transcriptions' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/audio/translations {#v1-post-v1-audio-translations}

Speech to English text, served and booked like transcriptions.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/audio/translations' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/audio/voices {#v1-get-v1-audio-voices}

The voices of a text-to-speech model (`?model=`), from the provider that would serve it.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/audio/voices' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/outreach/enrollments {#v1-get-v1-outreach-enrollments}

A sequence's enrollments (`sequence_id`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/outreach/enrollments' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/outreach/enrollments {#v1-post-v1-outreach-enrollments}

Enroll people (`sequenceId`, `personIds`, `dealId`, `consentBasis`); 201 with `enrolled` and `skipped` (each with its reason).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/outreach/enrollments' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/outreach/enrollments/{id} {#v1-post-v1-outreach-enrollments-id}

Pause, resume or stop one enrollment (`action`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/outreach/enrollments/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/outreach/queue {#v1-get-v1-outreach-queue}

Drafts waiting for your approval (`kind=approval`) or steps to send yourself (`kind=manual`), oldest first (`limit`).

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/outreach/queue' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/outreach/runs/{id}/approve {#v1-post-v1-outreach-runs-id-approve}

Approve a draft, optionally with an edited `subject` or `body`; it goes out inside the send window. Keys are agents: 403 `approval_required` unless the sequence sends without approval.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/outreach/runs/<id>/approve' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/outreach/runs/{id}/hold {#v1-post-v1-outreach-runs-id-hold}

Hold a timed draft: its auto-send time is removed and it waits for you in the approval queue.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/outreach/runs/<id>/hold' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/outreach/runs/{id}/skip {#v1-post-v1-outreach-runs-id-skip}

Skip a step; the enrollment moves on to the next one.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/outreach/runs/<id>/skip' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/outreach/runs/{id}/tapped {#v1-post-v1-outreach-runs-id-tapped}

Mark a tap-to-send step or task as sent by you; the next step is scheduled.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/outreach/runs/<id>/tapped' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### GET /v1/outreach/sequences {#v1-get-v1-outreach-sequences}

Your sequences with their steps and counts (`status`); a team key lists every sequence.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/outreach/sequences' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### POST /v1/outreach/sequences {#v1-post-v1-outreach-sequences}

Create a sequence (`name`, `purpose`, `steps`, and optionally `status`, `approval`, `tone`, `sender`, `stopOn`, `sendWindow`, `dailyCap`); 201.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/outreach/sequences' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### DELETE /v1/outreach/sequences/{id} {#v1-delete-v1-outreach-sequences-id}

Archive a sequence: every live enrollment stops (`archived`); 204.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X DELETE 'https://cloud.usevenom.dev/v1/outreach/sequences/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### GET /v1/outreach/sequences/{id} {#v1-get-v1-outreach-sequences-id}

One sequence: settings, steps and counts.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl 'https://cloud.usevenom.dev/v1/outreach/sequences/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

### PUT /v1/outreach/sequences/{id} {#v1-put-v1-outreach-sequences-id}

Replace one of your sequences; the steps replace its steps in order.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X PUT 'https://cloud.usevenom.dev/v1/outreach/sequences/<id>' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```

### POST /v1/search {#v1-post-v1-search}

Venom Search: the org's own metasearch over official APIs and open data (`docs/public/cloud/search.md`). `404 search_disabled` until an owner or admin turns it on in Settings, Search; no engine is asked before.

Auth: client key (`Authorization: Bearer vck_…`).

```bash
curl -X POST 'https://cloud.usevenom.dev/v1/search' \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{...}'
```
