Chats API and MCP tools
The routes under /api/workspace/agents, the live event stream, and the agents_* MCP tools with their REST twins under /api/v1/agents.
Console routes
The console's routes take the signed-in session; a change must come from the console's own origin. Errors are
{"error": {message, type, code}}.
| Route | Does |
|---|---|
GET /api/workspace/agents/chats |
Your chats, newest first. all=1 (admins) lists every member's; include_archived=1, kind=code|computer|quick, limit. extras=1 (the Agents app) adds daemons (those that serve sessions: id, name, live), gears (name, description) and default_gear. |
POST /api/workspace/agents/chats |
Start a chat. Quick (the default without daemon_id or seat_id): {kind: "quick", servers?}, no computer at all (Quick chats; servers defaults to ["globe"], gear is one of the org's). Code: {daemon_id, project}, or {daemon_id, scratch: true} for a new scratch folder the daemon deletes when the chat is archived (the chat's workspace_id names it). Computer: {kind: "computer", seat_id}, or {kind: "computer"} alone for your own computer (a dedicated browser computer, made on first use and reused after; it needs the right to create a computer). Optional title, gear (a gear from GET …/gears: the session runs on the model it resolves to on that daemon, with its thinking level) or model (a model id; not with gear), mode (plan, default, accept-edits, auto), prompt (the first message), origin (the item the chat works on: ENG-12, issue:<id>, a page URL, a project or a note; resolved as you before anything starts, 400 origin_not_found when it doesn't exist or you can't see it; the chat is linked to it, worked_in an issue or project, discussed_in a note, and every chat read returns origin as {ref, kind, id, key, title, url, state} while you can see it). 201 with the chat. A session the daemon refuses keeps no chat and answers the daemon's error. |
GET /api/workspace/agents/chats/{id} |
One chat. |
PATCH /api/workspace/agents/chats/{id} |
{title?, mode?, gear?, servers?}: servers is a quick chat's list (from its next turn). Rename, change the permission mode, or shift to another gear (the agent switches to its model now when idle, else at its next turn). 400 invalid_gear names the gears on offer. |
DELETE /api/workspace/agents/chats/{id} |
Archive: a running turn is stopped, the session closed on the daemon, and a scratch chat's folder deleted there. |
POST …/{id}/prompt |
{message}: start a run. 409 busy while one runs. |
POST …/{id}/steer, POST …/{id}/follow_up |
{message}: reach the running turn, or wait until it would stop. |
POST …/{id}/abort |
Stop the running turn. |
POST …/{id}/mode |
{mode}. |
POST …/{id}/approvals/{aid} |
{action, feedback?, rule?}: allow-once, allow-session, allow-project or deny. |
POST …/{id}/questions/{qid} |
{answers: [{selected: [...], text?}]}. |
GET …/{id}/changes |
The turns that changed files; with turn=<entryId>, each file's text before and after. |
GET …/{id}/transcript |
The conversation so far (limit, default 200). |
GET …/{id}/events |
The session's events as Server-Sent Events (below). |
GET /api/workspace/agents/projects?daemon=<id> |
The project directories a daemon offers. A project that is a workspace has workspace: {id, origin, created_by, git_url}; the answer's workspaces lists the durable workspaces (null on a daemon too old to make them). |
GET /api/workspace/agents/workspaces?daemon=<id> |
The workspaces on a daemon: {daemon_id, root, workspaces: [{id, name, kind, path, origin, created_by, git_url, created_at}], max_durable, max_scratch, scratch_ttl_hours}. |
POST /api/workspace/agents/workspaces |
{daemon_id, kind?, name?, git_url?}: make one. kind is durable (the default; name required, git_url an optional https URL with no credentials in it) or scratch. 201 with {daemon_id, workspace}. A clone can take up to 4 minutes. 409 workspace_exists, 409 workspace_limit, 413 repository_too_large, 422 clone_failed, 501 workspaces_unavailable on a daemon too old to make them. |
DELETE /api/workspace/agents/workspaces/{id}?daemon=<id> |
Delete a workspace and its files: the member who made it, or an org admin. A folder the daemon's owner put there is deleted only on the daemon (403). |
GET /api/workspace/agents/gears[?daemon=<id>] |
The gears a chat can run in: gears (each name, key, description, model, resolved, thinking, available, source: org, daemon or venom), locked, default (the org's default gear) and daemon_id (set when the daemon listed its own; null: venom's built-ins). The org's gears come first; with locked, only they are listed. |
GET /api/workspace/agents/servers |
The MCP servers a quick chat can use: data: [{id, kind, title, description, available, connection, sign_in, default_on, error}] (Venom's globe, tasks, …; the catalog's catalog:<id> with your connection: none, pending, connected, error). |
POST /api/workspace/agents/connections |
{server}: connect a catalog server for your quick chats. 201 {server, state, authorize_url}: connected at once for a server without sign-in; pending with the sign-in page's URL for an OAuth one. 503 vault_unavailable without a vault key. |
DELETE /api/workspace/agents/connections/{server} |
Disconnect it; its sealed tokens are deleted. |
GET /api/workspace/agents/connections/callback |
Where the sign-in page sends the browser back (code, state); redirects to /agents?connected=<server> or ?connect_error=. No MCP tool: it is the browser's half of a sign-in. |
GET /api/workspace/agents/push |
Notifications: enabled (the install has VAPID keys), public_key (the browser's applicationServerKey) and your devices. ?endpoint= marks this browser's device current. |
POST /api/workspace/agents/push |
This browser's PushSubscription ({endpoint, keys: {p256dh, auth}}): turn notifications on for it. The endpoint must be https. 201 with the device; 409 push_disabled without VAPID keys. |
DELETE /api/workspace/agents/push |
{id} or {endpoint}: turn one of your devices off. |
POST /api/workspace/agents/push/test |
{id?}: a test notification to one of your devices, or all of them. Answers {sent, removed, failed}. |
The push routes have no MCP tool: notifications go to a person's own browser or phone, which an agent does not have (Notifications).
yolo and sudo modes can't be chosen for a chat: a chat started from a browser always keeps its approval prompts.
The event stream
GET /api/workspace/agents/chats/{id}/events passes the session's events through as the daemon sends them:
id: <seq>, event: <type>, data: <json>. The cloud keeps none of them. A connection lasts at most 800 seconds;
reconnect with Last-Event-ID (or ?after=<seq>) and the daemon replays what you missed while it still holds it. The
chat's last_event_id is the last id its member's stream saw. An approval or a question arrives as an
approval_request or question_request event; answer it with the routes above.
MCP tools
Connect venom-agents with claude mcp add --transport http venom-agents https://<your cloud>/workspace/mcp/agents
(scopes agents:read, agents:write). A member's personal key or an OAuth grant acts as that member; other keys have no
access, because a chat belongs to a person.
| Tool | REST twin (/api/v1) |
|---|---|
agents_chat_list |
GET /agents/chats |
agents_chat_get |
GET /agents/chats/{chat_id} |
agents_chat_create |
POST /agents/chats |
agents_chat_update |
PATCH /agents/chats/{chat_id} |
agents_chat_archive |
DELETE /agents/chats/{chat_id} |
agents_chat_send (delivery: prompt, steer, follow_up) |
POST /agents/chats/{chat_id}/messages |
agents_chat_stop |
POST /agents/chats/{chat_id}/abort |
agents_approval_decide |
POST /agents/chats/{chat_id}/approvals/{approval_id} |
agents_question_respond |
POST /agents/chats/{chat_id}/questions/{question_id} |
agents_transcript_get |
GET /agents/chats/{chat_id}/transcript |
agents_change_get |
GET /agents/chats/{chat_id}/changes |
agents_project_list |
GET /agents/projects |
agents_gear_list |
GET /agents/gears |
agents_workspace_list |
GET /agents/workspaces |
agents_workspace_create |
POST /agents/workspaces |
agents_workspace_delete |
DELETE /agents/workspaces/{workspace_id} |
agents_server_list |
GET /agents/servers |
agents_connection_create |
POST /agents/connections |
agents_connection_delete |
DELETE /agents/connections/{server} |
There is no tool for the live stream; an agent reads agents_transcript_get.