Build with Venom
Build on every Venom product from code or an agent. Each product has MCP tools and REST routes behind the same API keys and OAuth scopes, with webhooks for what changed. Start here for auth, conventions, a quick start and a page per product.
Every workspace product in Venom Cloud (Notes, Tasks, People, Funnel, Calendar, Comms, Support, Chat, Incidents, the Status page, Forms, Flags, Experiments, Org, Computers and Admin) can be driven from your own code or an agent. There are two ways in, and they reach the same functions:
- MCP. Each product is its own MCP server at
/workspace/mcp/<product>. Connect Claude Code, Cursor, ChatGPT or your own agent to the products it needs. - REST. Each MCP tool that a script needs has a route under
/api/v1, described by an OpenAPI document. Flags, Forms, Incidents, Experiments and Comms also have APIs of their own for app runtimes (SDK keys, event ingest).
A REST route calls the MCP tool of the same name with the same arguments, access checks and rate window. So what an agent may do and what a script may do cannot drift apart. Changes come back to you as signed webhooks.
Quick start
You need your cloud's address and a Venom API key. Create the key in the console under Settings, API keys, and turn on "This key is mine" so it acts as you (see Authentication and scopes).
export VENOM_CLOUD=https://cloud.usevenom.dev
export VENOM_API_KEY=vck_…curl
List the products, then create an issue and read it back:
curl "$VENOM_CLOUD/api/v1/products" -H "Authorization: Bearer $VENOM_API_KEY"
curl -X POST "$VENOM_CLOUD/api/v1/issues" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"team": "ENG", "title": "Fix the login timeout"}'
curl "$VENOM_CLOUD/api/v1/issues/ENG-12" -H "Authorization: Bearer $VENOM_API_KEY"The same tool over MCP is one JSON-RPC call:
curl -X POST "$VENOM_CLOUD/workspace/mcp/tasks" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "tasks_issue_get", "arguments": {"id": "ENG-12"}}}'TypeScript
No SDK is needed: fetch and a bearer token.
const base = `${process.env.VENOM_CLOUD}/api/v1`;
const headers = { Authorization: `Bearer ${process.env.VENOM_API_KEY}`, "Content-Type": "application/json" };
async function venom(method: string, path: string, body?: unknown, extra: Record<string, string> = {}) {
const res = await fetch(`${base}${path}`, { method, headers: { ...headers, ...extra }, body: body === undefined ? undefined : JSON.stringify(body) });
const json = await res.json();
if (!res.ok) throw new Error(`${res.status} ${json.error?.code}: ${json.error?.message}`);
return { data: json, version: res.headers.get("etag") };
}
const created = await venom("POST", "/issues", { team: "ENG", title: "Fix the login timeout" }, { "Idempotency-Key": crypto.randomUUID() });
const { data, version } = await venom("GET", "/issues/ENG-12");
// Only write if nobody changed the issue since this read: a stale write is 412.
await venom("PATCH", "/issues/ENG-12", { state: "In Review" }, version ? { "If-Match": version } : {});Python
The standard library is enough.
import json, os, urllib.request, uuid
BASE = os.environ["VENOM_CLOUD"] + "/api/v1"
KEY = os.environ["VENOM_API_KEY"]
def venom(method, path, body=None, headers=None):
req = urllib.request.Request(BASE + path, method=method,
data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json", **(headers or {})})
with urllib.request.urlopen(req) as res: # raises HTTPError on 4xx and 5xx; its body is {"error": {...}}
return json.load(res), res.headers.get("ETag")
venom("POST", "/issues", {"team": "ENG", "title": "Fix the login timeout"}, {"Idempotency-Key": str(uuid.uuid4())})
issue, version = venom("GET", "/issues/ENG-12")
venom("PATCH", "/issues/ENG-12", {"state": "In Review"}, {"If-Match": version} if version else None)Products
Each product's page lists what you can build with it, its REST routes, its MCP tools, the scopes they need, a worked example and its webhook events. The counts below come from the code on every docs build.
| Product | What it is for | MCP tools | REST routes | Events | Developer page |
|---|---|---|---|---|---|
| Notes | Notes: markdown notes with wikilinks, databases, vaults, sharing and publishing. | 92 | 94 | 6 | Build on Notes |
| Tasks | Issues, projects, cycles, views and teams; delegate work to agents. | 221 | 228 | 5 | Build on Tasks |
| Flags | Feature flags, environments, targeting and rollouts. | 42 | 42 | 3 | Build on Flags |
| Forms | Build, publish and read forms and their responses. | 19 | 23 | 1 | Build on Forms |
| Incidents | Errors, incidents, alerts and on-call. | 56 | 111 | 7 | Build on Incidents |
| Experiments | Experiments, metrics and results, run through Flags. | 25 | 22 | 5 | Build on Experiments |
| People | Your own relationships: people, notes, circles, follow-ups and warm intros. | 135 | 136 | 3 | Build on People |
| Funnel | Deals, pipelines, forecast and reports; deals link your People. | 38 | 55 | 4 | Build on Funnel |
| Support | The shared support inbox: triage conversations, add notes, draft replies from your notes. | 26 | 27 | 2 | Build on Support |
| Chat | Team chat where people and agents are members: read channels, post, react and follow threads. | 32 | 32 | 3 | Build on Chat |
| Status page | The public status page: uptime checks, maintenance windows, subscribers and incident updates. | 16 | 16 | 7 | Build on Status page |
| Comms | Messages and phone calls to people (SMS, WhatsApp, RCS, Telegram, voice). | 27 | 55 | 7 | Build on Comms |
| Calendar | Your calendars and booking pages: .ics feeds, schedules, event types, free times, booking links and bookings. | 41 | 43 | 5 | Build on Calendar |
| Admin | Console admin: members, budgets, providers, keys, routing, guardrails, webhooks, daemons and the audit log. | 269 | 269 | 34 | Build on Admin |
| Org | The organisation's teams and subteams, their members and roles, shared by every product. | 10 | 10 | 5 | Build on Org |
| Computers | Each agent's own persistent browser on your daemons: start, stop, watch activity, ask a person to take over. | 36 | 0 | 0 | Build on Computers |
| Agents | Chats with coding agents on your daemons' projects and agents on your computers, run on your machines. | 48 | 48 | 0 | Build on Agents |
| Studio | Decks, pages and HTML pages built from blocks and charts, versioned and shared by link. | 30 | 31 | 0 | Build on Studio |
The building blocks
| Page | What it covers |
|---|---|
| Authentication and scopes | API keys (vck_), OAuth for MCP clients (vga_ tokens), scopes per product, service agents |
| The REST twin and OpenAPI | /api/v1, the OpenAPI document, how a request maps to a tool, the product APIs |
| MCP servers | the endpoint per product, the combined endpoint, connecting clients |
| Errors, limits, idempotency and pagination | the error shape and statuses, rate limits, Idempotency-Key, If-Match, cursors |
| Webhooks and events | org webhook endpoints, the signed envelope, retries, every event type |
The inference API (/v1/chat/completions and the rest of the OpenAI-shaped surface) and the admin and mesh APIs are
covered in Build on Admin and the mesh and the generated Venom Cloud API reference.
In this section
- Authentication and scopes: Which credential to use for each Venom API. Personal and team API keys, OAuth 2.1 for MCP clients with its endpoints and token lifetimes, the scopes per product, service agents, and the keys that belong to app runtimes.
- 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.
- MCP servers: Connect an agent to Venom over MCP. One connection at /workspace/mcp whose listed products you switch on, or one server per product at /workspace/mcp/<product>, the connect commands for common clients, and how a raw JSON-RPC call looks.
- Errors, limits, idempotency and pagination: How the workspace APIs answer errors, how many requests they take a minute, how to retry a create without making it twice, how to write only when nothing changed since your read, and how to page through lists.
- Webhooks and events: Get told when something happens in Venom. Add an org webhook endpoint, pick its events, verify the signature, handle retries, and see every event type each product sends.
- Build on Venom Notes: Read, write and search notes and databases from code or an agent. Write meeting notes, file suggestions for a person to review, query databases and follow org vault changes over REST or MCP.
- Build on Venom Tasks: Create, find and update Tasks issues from code, and run agents that claim delegated work, report progress and hand it back, over REST or MCP.
- Build on Venom People: Search, add and update the people a member knows, log interactions and draft follow-ups from code or an agent, over REST or MCP. People is personal, so every call acts for one member.
- Build on Venom Funnel and Outreach: Work with deals, pipelines, products, goals, reports and Outreach sequences from code or an agent, over REST or MCP, as the member whose People the deals link.
- Build on Venom Calendar: Work with a member's calendar from code or an agent. Find free times, book and move meetings, manage event types and schedules, send time offers and group polls over REST or MCP, and put booking pages on your own site.
- Build on Venom Comms: Send messages and place phone calls from your app or an agent. Text people on SMS, WhatsApp, RCS, Telegram or email, run fallback profiles, read conversations and follow replies over the Comms API or MCP.
- Build on Venom Support: Read and triage the support inbox from code or an agent. Assign and tag conversations, add internal notes, draft replies from your notes and send them once a person approves, over REST or MCP.
- Build on Venom Chat: Read channels and DMs, post and reply in threads, react, search, and follow chat with a change cursor from code or an agent, over REST or MCP. A team key joins as an agent member.
- Build on Venom Incidents: Triage errors, run incidents and manage on-call from code or an agent. Read and resolve error issues, declare and update incidents, page people and change alert rules over REST or MCP, and send errors from your apps with an SDK key.
- Build on the Status page: Manage the public status page from code or an agent. Add uptime checks, read their results, schedule maintenance, edit the listed services and manage subscribers over REST or MCP.
- Build on Venom Forms: Build, preview, publish and close forms from code or an agent, read and export their responses, and send each response to Notes, Tasks, Slack, Funnel, Support, Calendar or your own webhook, over REST or MCP.
- Build on Venom Flags: Create, target, roll out, evaluate and revert feature flags from code or an agent, over the Flags REST API, the SDK endpoints or MCP, and receive every flag change as a signed webhook.
- Build on Venom Experiments: Define metrics, propose, start, ramp, read and decide A/B tests and guarded rollouts on Venom Flags flags, run product analytics queries and send events, over the Experiments REST API, the event endpoint or MCP.
- Build on Org and teams: Read and manage the organisation's teams, subteams and team members from code or an agent, over REST or MCP, with the same rules as Settings, Teams.
- Build on Computers: Give agents their own persistent browsers on your daemons from code or an agent. Create, start and stop computers, read what they did, ask a person to take over and manage a shared computer's agents over MCP.
- Build on Agents: Start and drive chats with coding agents on your daemons' projects and with agents on your computers, from code or another agent, over MCP or REST.
- Build on Admin and the mesh: Run the org's console admin pages from code or an agent (members, budgets, provider keys, routing, webhooks, alerts, audit, daemons and more) with your member role, and find the admin, client and daemon APIs.
- Build on Studio: Make decks, pages and HTML pages from code or an agent. Create them from blocks and charts, change one slide or block by id, keep versions, and share by link over MCP and REST.