The REST twin and OpenAPI
Call Venom's workspace products over plain HTTP at /api/v1. Each route runs the MCP tool of the same name, with the same keys, checks and limits, an OpenAPI 3.1 document, If-Match for safe writes and Idempotency-Key for retries.
A script or an app that does not speak MCP gets the same operations over plain HTTP at /api/v1. Every route names
one MCP tool. The request becomes that tool's arguments, the call goes through the same server the MCP endpoint uses,
and the answer becomes JSON. So the two cannot differ: the same credentials, access and add-on checks, rate window,
argument names, limits and refusals. Only the envelope is HTTP.
The APIs
| API | Base path | Operations | Source |
|---|---|---|---|
| REST twin of the MCP tools | /api/v1 |
1079 | GET /api/v1/openapi.json (served, no credential) |
| Flags API | /flags/api/v1 |
42 | services/nodejs-cloud/contracts/flags-openapi.yaml |
| Forms API | /forms/api/v1 |
23 | services/nodejs-cloud/contracts/forms-openapi.yaml |
| Incidents API | /incidents/api/v1 |
51 | services/nodejs-cloud/contracts/incidents-openapi.yaml |
| Experiments API | /experiments/sdk/events |
22 | services/nodejs-cloud/contracts/experiments-openapi.yaml |
| Comms API | /v1/comms |
28 | services/nodejs-cloud/contracts/comms-openapi.yaml |
| Outreach API | /v1/outreach/sequences |
13 | services/nodejs-cloud/contracts/outreach-openapi.yaml |
The REST twin covers Notes, Tasks, People, Funnel (Outreach included), Calendar, Support, Chat, the Status page,
Incidents (/api/v1/incidents), Comms (/api/v1/comms), Org, Admin and the cross-product tools. Flags, Forms and
Experiments are reached over their own APIs, which also serve your app's runtime (SDK keys, event ingest); Incidents
and Comms keep theirs too (/incidents/api/v1, /v1/comms). Each product's page lists its routes, generated from these
sources: see Build with Venom.
The OpenAPI document
GET /api/v1/openapi.json serves the twin's OpenAPI 3.1 document, with no credential needed. It is generated from
the route table and the tools' own input schemas, so a tool that gains an argument gains it there too. Each operation
names its tool in x-mcp-tool. Load it into an OpenAPI client generator, Postman or an agent framework that reads
OpenAPI.
curl "$VENOM_CLOUD/api/v1/openapi.json" -o venom-workspace.jsonHow a request maps to a tool
- Arguments. Query parameters (on
GETandDELETE) and JSON body fields (onPOST,PATCHandPUT) are the tool's arguments under the same snake_case names. A path parameter fills the argument of its name ({id},{person},{deal}). An argument the route does not take is refused with400and the list of those it does. - Lists in a query. An array argument in a query string is comma separated:
?fields=identifier,state. - Answers. Where a tool has a JSON form, the route asks for it and answers the structured result. Other answers
are
{ "text": "…", "id": "…" }with the tool's words and, for a create, the id it made. A create answers201. - Versions. A read's version comes back as the
ETagheader; send it asIf-Matchand it becomes the tool'sexpect_version(412when stale). - Retries.
Idempotency-Keybecomes the tool'sidempotency_key. - Batches.
POST /api/v1/batchtakescallsof MCP tool names and arguments (globe_note_write,tasks_issue_create) and answers each step's text. A later step can use an earlier one's id as$1.id. - CORS. The routes answer browser preflights and expose
ETag,Retry-AfterandWWW-Authenticate, so a browser app with a token can call them.
Errors, rate limits, idempotency and paging are on Errors, limits, idempotency and pagination.
Authentication
Authorization: Bearer <credential>: a Venom API key (vck_…; a personal key acts as its member) or an OAuth access
token issued for the workspace resource, the same ones /workspace/mcp takes. See Authentication and scopes.
Example
# Find issues, then move one, but only if nobody changed it since the read
curl "$VENOM_CLOUD/api/v1/issues?query=login&limit=5" -H "Authorization: Bearer $VENOM_API_KEY"
curl -i "$VENOM_CLOUD/api/v1/issues/ENG-12" -H "Authorization: Bearer $VENOM_API_KEY" # note the ETag header
curl -X PATCH "$VENOM_CLOUD/api/v1/issues/ENG-12" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-H 'If-Match: "2026-11-07T10:00:00.000Z"' \
-d '{"state": "In Review"}'Clients
Thin TypeScript and Python clients for the notes and issues routes live in the Venom source tree
(clients/workspace-ts, @venom/workspace-client; clients/workspace-py, venom-workspace). They are not published
to a package registry. For everything else, fetch or urllib and the OpenAPI document are enough: see the
quick start.
- TypeScript:
new VenomWorkspace({ baseUrl, apiKey });venom.issues.get("ENG-12")answers{ data, version }; pass{ ifMatch: version }or{ idempotencyKey }to a write; a stale write throws aVenomApiErrorwhoseconflictis true. - Python:
VenomWorkspace(base_url, api_key);venom.issues.get("ENG-12")answers aReplywith.dataand.version;if_match=andidempotency_key=on writes;VenomApiError.conflict.
Related
- MCP servers
- Venom Cloud API: the inference and other
/v1routes, generated from their handlers.