Skip to content
Docs menu

Venom Cloud API

Every public /v1 route of Venom Cloud (115 operations): what it does, its client-key auth and a curl line.

View .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), 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.

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 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 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 Speech to English text, served and booked like transcriptions.
GET /v1/audio/voices The voices of a text-to-speech model (?model=), from the provider that would serve it.
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 Recent calls, newest first (conversation_id, limit, cursor).
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} One call: status, duration, cost and the digits gathered.
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 Cancel an agent's pending_approval call; the same rule as approving a message.
GET /v1/comms/conversations Threads with contacts, newest first (channel, contact); session_open for WhatsApp's 24-hour window.
GET /v1/comms/conversations/{id} One conversation with its messages and calls.
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 Acknowledge a profile run so no further step goes out.
GET /v1/comms/events The Comms event feed (message.received, message.status, call.*, dispatch.acknowledged) after a cursor (after).
GET /v1/comms/messages Recent messages, newest first (status, conversation_id, limit, cursor).
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} One message: status, provider, segments and cost.
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 Cancel an agent's pending_approval message (status canceled); the same rule as approve.
DELETE /v1/comms/optouts Lift an opt-out (?contact=…&channel=…); 204.
GET /v1/comms/optouts Contacts who must not be messaged or called, per channel (contact filters).
POST /v1/comms/optouts Opt a contact out ({contact, channel, note}; channel * for all).
GET /v1/comms/profiles Routing profiles: the org's own and the built-in page, support and notify.
GET /v1/comms/senders The org's numbers and sender ids, with their channels and countries.
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 Message templates with their approval state (channel, status); WhatsApp outside its 24-hour window sends an approved one.
POST /v1/comms/templates/sync Read the providers' templates and their approval state again; answers how many were synced.
POST /v1/completions Legacy text completions, OpenAI-compatible, routed like chat completions.
GET /v1/deprecations The org's gears that name a model its provider retires soon or has retired, for venom doctor.
POST /v1/embeddings Embeddings, OpenAI-compatible.
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 Finish an eval run: its key is revoked and the paired comparison computed.
POST /v1/evals/runners An eval runner's hello and heartbeat, one per team and name.
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 The team's fleet: the agents its machines published in the last 60 s (?repo= filters).
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 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 The CLI's report on one session of a gear experiment, at its end or when the user opts out.
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 Draft one of the member's own guardrails from a sentence ({text, gear?}). Nothing is saved.
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 The key's handoff inbox (?box=inbox) or what it sent (?box=sent).
POST /v1/handoffs Hand a session to a teammate or a team.
DELETE /v1/handoffs/{id} Cancel a handoff you sent.
GET /v1/handoffs/{id} One handoff; ?trace=1 adds the shared transcript.
POST /v1/handoffs/{id}/accept Take a handoff; 409 already_accepted when someone else took it first.
POST /v1/handoffs/{id}/decline Decline a handoff ({reason?}).
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 Finish an intake job: its key is revoked and the issue gets a comment.
POST /v1/intake/runners An intake runner's hello and heartbeat, one per team and name.
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 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 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 Join a session to a library prompt A/B test ({session_id, arm}).
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 Start a live share of a venom session (201), or update this team's live share of it (200).
DELETE /v1/live-sessions/{id} Stop a live share.
PATCH /v1/live-sessions/{id} Change a live share's grants, audience or title, or extend it.
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 The org's approved plugins, skills and MCP packages (venom plugin search). Supports If-None-Match (304).
GET /v1/marketplace/{name} The signed manifest of a marketplace package (?version=), verified by venom plugin install org:<name>.
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 Count an install or removal ({name, version, event}).
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 Propose a fact for the org's memory ({text, scope?, repo?, reason?, session_id?}); pending until an admin approves it.
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 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 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 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…} One model from the list above, by id (ids may contain slashes).
GET /v1/onboarding The org's onboarding paths with the key's member's progress, for venom onboard.
POST /v1/onboarding/steps Mark a manual onboarding step done or undo it ({path_id, step_id, done?}).
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 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 A sequence's enrollments (sequence_id).
POST /v1/outreach/enrollments Enroll people (sequenceId, personIds, dealId, consentBasis); 201 with enrolled and skipped (each with its reason).
POST /v1/outreach/enrollments/{id} Pause, resume or stop one enrollment (action).
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 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 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 Skip a step; the enrollment moves on to the next one.
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 Your sequences with their steps and counts (status); a team key lists every sequence.
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} Archive a sequence: every live enrollment stops (archived); 204.
GET /v1/outreach/sequences/{id} One sequence: settings, steps and counts.
PUT /v1/outreach/sequences/{id} Replace one of your sequences; the steps replace its steps in order.
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 The public key that signs this tenant's policies; 503 policy_signing_not_configured when there is none.
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 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 Rerank documents against a query (results by relevance). A malformed body is 400 invalid_rerank_request before anything is spent.
POST /v1/responses The OpenAI Responses API, routed like chat completions; background: true starts a background response.
DELETE /v1/responses/{id} Delete a background response your team started.
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 Stop a queued or running background response. Idempotent: an ended one comes back as it ended.
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 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 Create a venom serve session on one of the team's daemons and bind it there.
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…}] Any harness server GET route of a bound session (events, state), relayed to its daemon.
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…}] Any harness server POST route of a bound session (prompt, approvals); …/resume moves it to another daemon.
PUT /v1/serve/sessions/{id}[/{rest…}] Any harness server PUT route of a bound session, relayed to its daemon.
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 Whether the org takes session outcome reports ({enabled}).
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} Remove a shared session (the sharing team only).
POST /v1/session-summaries Upload a session's redacted summary when the org opted in (403 summaries_off otherwise).
GET /v1/session-summaries/settings Whether the org collects session summaries ({enabled}), so venom asks first.
POST /v1/systemone A decision model's fast classification call, routed like chat completions.
POST /v1/task-outcomes Report that a task's pull request merged or its issue closed, for cost per outcome.
GET /v1/usage Usage for the key, the same body as the orchestrator's venom.usage, from the cloud ledger.
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

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_…).

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

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

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

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

POST /v1/embeddings

Embeddings, OpenAI-compatible.

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

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

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_…).

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

GET /v1/models/{id…}

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

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

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

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_…).

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

POST /v1/responses

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

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

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}

Delete a background response your team started.

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

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

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_…).

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

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_…).

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

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

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

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

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_…).

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

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_…).

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

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_…).

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

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_…).

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

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_…).

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

Gears, policy and guardrails

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_…).

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

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_…).

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

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_…).

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

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_…).

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

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_…).

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

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_…).

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

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_…).

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

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_…).

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

Library, memory and marketplace

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_…).

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

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_…).

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

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_…).

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

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

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

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

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

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

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

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_…).

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

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_…).

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

POST /v1/marketplace/installs

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

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

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

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_…).

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

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_…).

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

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

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

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

POST /v1/onboarding/steps

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

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

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

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

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

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

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

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

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

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_…).

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

Sessions

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_…).

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

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_…).

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

GET /v1/handoffs

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

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

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

POST /v1/handoffs

Hand a session to a teammate or a team.

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

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}

Cancel a handoff you sent.

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

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

GET /v1/handoffs/{id}

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

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

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

POST /v1/handoffs/{id}/accept

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

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

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

Decline a handoff ({reason?}).

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

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

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_…).

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}

Stop a live share.

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

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

PATCH /v1/live-sessions/{id}

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

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

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

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

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

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

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

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

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…}]

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

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

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

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_…).

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

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_…).

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…}]

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

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

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…}]

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

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

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

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

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

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

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

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

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

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_…).

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}

Remove a shared session (the sharing team only).

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

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

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_…).

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

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

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

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

Org tools

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_…).

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

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_…).

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

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_…).

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

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

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

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

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

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

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

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

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

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

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_…).

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

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

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

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

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

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

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

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

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

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

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_…).

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

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

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

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

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_…).

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}

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

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

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

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_…).

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

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

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

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

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

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

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

GET /v1/comms/conversations/{id}

One conversation with its messages and calls.

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

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

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_…).

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

POST /v1/comms/dispatches/{id}/ack

Acknowledge a profile run so no further step goes out.

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

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

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

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

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

GET /v1/comms/messages

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

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

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

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_…).

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}

One message: status, provider, segments and cost.

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

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

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_…).

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

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

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

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

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

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

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

GET /v1/comms/optouts

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

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

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

POST /v1/comms/optouts

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

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

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

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

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

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

GET /v1/comms/senders

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

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

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

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_…).

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

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

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

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

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_…).

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

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_…).

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

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_…).

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

Speech to English text, served and booked like transcriptions.

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

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

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

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

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

GET /v1/outreach/enrollments

A sequence's enrollments (sequence_id).

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

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

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_…).

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}

Pause, resume or stop one enrollment (action).

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

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

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

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

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

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_…).

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

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_…).

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

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

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

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

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

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

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

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

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

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

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_…).

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}

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

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

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

GET /v1/outreach/sequences/{id}

One sequence: settings, steps and counts.

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

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

PUT /v1/outreach/sequences/{id}

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

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

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

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_…).

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