---
title: Chats API and MCP tools
description: The routes under /api/workspace/agents, the live event stream, and the agents_* MCP tools with their REST twins under /api/v1/agents.
section: agents
order: 10
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/agents, services/nodejs-cloud/app/api/workspace/agents/chats, services/nodejs-cloud/app/api/workspace/agents/servers, services/nodejs-cloud/app/api/workspace/agents/connections, services/nodejs-cloud/app/api/workspace/agents/projects, services/nodejs-cloud/app/api/workspace/agents/workspaces, services/nodejs-cloud/app/api/workspace/agents/push, services/nodejs-cloud/lib/mcp/rest.ts]
features: []
---

## 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](/docs/agents/quick-chat.md); `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](/docs/agents/app.md#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](/docs/agents/app.md#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`.
