Skip to content
Docs menu

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.

View .md

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.