Skip to content
Docs menu

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.

View .md

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

How a request maps to a tool

  • Arguments. Query parameters (on GET and DELETE) and JSON body fields (on POST, PATCH and PUT) 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 with 400 and 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 answers 201.
  • Versions. A read's version comes back as the ETag header; send it as If-Match and it becomes the tool's expect_version (412 when stale).
  • Retries. Idempotency-Key becomes the tool's idempotency_key.
  • Batches. POST /api/v1/batch takes calls of 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-After and WWW-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 a VenomApiError whose conflict is true.
  • Python: VenomWorkspace(base_url, api_key); venom.issues.get("ENG-12") answers a Reply with .data and .version; if_match= and idempotency_key= on writes; VenomApiError.conflict.