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.
A chat is one conversation with one agent that runs on your organisation's own machines: a coding agent in a project directory a daemon offers, or an agent on one of your computers. The cloud relays messages and events; the repository and the conversation stay on the daemon. See Venom Agents.
What you can build
- A script that hands work to a coding agent. List a daemon's projects with
agents_project_list(or make one withagents_workspace_create, cloned from a repository), start a chat withagents_chat_createand aprompt, then readagents_transcript_getuntil the run is done. - An approvals bot. Read the transcript or the console's event stream for
approval_requestevents and answer them withagents_approval_decide(allow-once,allow-session,allow-projectordeny). - A review step. After a run, read the files each turn changed with
agents_change_get(turn: a checkpoint'sentryId).
At a glance
Generated from the code on every docs build.
| MCP endpoint | https://cloud.usevenom.dev/workspace/mcp/agents, server name venom-agents |
| Connect | claude mcp add --transport http venom-agents https://cloud.usevenom.dev/workspace/mcp/agents |
| MCP tools | 48 (21 read, 27 write) |
| OAuth scopes | agents:read agents:write |
| REST twin | 48 routes under https://cloud.usevenom.dev/api/v1 |
| Webhook events | none yet |
Authentication and scopes
Agents needs the agents add-on (the Team plan and up). Without it every call answers 403 addon_required.
- A personal API key or an OAuth grant acts as the member. OAuth apps need
agents:readfor the read tools andagents:writefor the rest; a computer chat also needs the member's right to use that computer. - Any other key has no access: a chat belongs to a person.
Only the member who started a chat sends to it. Org owners and admins read every member's chats (all: true).
Worked example
curl -X POST "$VENOM_CLOUD/workspace/mcp/agents" \
-H "Authorization: Bearer $VENOM_PERSONAL_KEY" \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "agents_chat_create", "arguments": {"daemon_id": "<daemon-id>", "project": "/home/me/src/app", "prompt": "Fix the failing tests", "format": "json"}}}'Then, with the chat's id:
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": { "name": "agents_transcript_get", "arguments": { "chat_id": "<chat-id>" } } }While a run is active a new prompt answers 409 busy: send it with delivery: "steer" or "follow_up" instead.
Errors worth handling: 501 projects_unavailable (the daemon is too old to list projects), 503 session_daemon_unavailable (the chat's daemon is offline), 409 chat_archived, 409 member_gone.
Events
This product sends no org webhook events yet. Follow its changes with workspace_change_list where it has a change feed, or poll its list routes.
The live stream (GET /api/workspace/agents/chats/{id}/events) is for the signed-in browser; an agent reads the
transcript.
REST routes
The REST twin: 48 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/agents/chats |
Your chats with agents (admins: all for every member's) | agents_chat_list |
| POST | /api/v1/agents/chats |
Start a chat: a coding agent in a daemon's project (or a new scratch folder), or an agent on a computer, with an optional first prompt | agents_chat_create |
| GET | /api/v1/agents/chats/{chat_id} |
One chat | agents_chat_get |
| PATCH | /api/v1/agents/chats/{chat_id} |
Rename a chat, change its permission mode or shift its gear; a quick chat's servers | agents_chat_update |
| DELETE | /api/v1/agents/chats/{chat_id} |
Archive a chat; its session is closed | agents_chat_archive |
| POST | /api/v1/agents/chats/{chat_id}/messages |
Send a message: a prompt, or steer or follow up a running turn | agents_chat_send |
| POST | /api/v1/agents/attachments |
Upload a file or picture for your next quick-chat message (base64) | agents_attachment_upload |
| DELETE | /api/v1/agents/attachments/{file_id} |
Remove a file you uploaded and have not sent | agents_attachment_delete |
| GET | /api/v1/agents/chats/{chat_id}/attachments |
A chat's files and pictures | agents_attachment_list |
| POST | /api/v1/agents/chats/{chat_id}/abort |
Stop the running turn | agents_chat_stop |
| POST | /api/v1/agents/chats/{chat_id}/approvals/{approval_id} |
Answer an approval the agent asked for | agents_approval_decide |
| POST | /api/v1/agents/chats/{chat_id}/questions/{question_id} |
Answer a question the agent asked | agents_question_respond |
| GET | /api/v1/agents/chats/{chat_id}/transcript |
The conversation so far | agents_transcript_get |
| GET | /api/v1/agents/chats/{chat_id}/changes |
The turns that changed files, or one turn's file changes (turn) | agents_change_get |
| GET | /api/v1/agents/gears |
The gears a chat can run in: the org's, then the daemon's own or venom's built-ins | agents_gear_list |
| GET | /api/v1/agents/projects |
The project directories a daemon offers | agents_project_list |
| GET | /api/v1/agents/workspaces |
The workspaces on a daemon (durable and scratch) | agents_workspace_list |
| POST | /api/v1/agents/workspaces |
Make a workspace on a daemon: empty, cloned from an https URL, or scratch | agents_workspace_create |
| GET | /api/v1/agents/servers |
The MCP servers a quick chat can use, and your catalog connections | agents_server_list |
| GET | /api/v1/agents/skills |
The organisation's skills a quick chat can use | agents_skill_list |
| POST | /api/v1/agents/connections |
Connect a catalog MCP server for quick chats (an OAuth server answers the sign-in link) | agents_connection_create |
| DELETE | /api/v1/agents/connections/{server} |
Disconnect a catalog MCP server | agents_connection_delete |
| GET | /api/v1/agents/bots |
Your bots: named agents with an avatar and standing instructions | agents_bot_list |
| POST | /api/v1/agents/bots |
Make a bot, or a ready-made one with its routines (template) | agents_bot_create |
| GET | /api/v1/agents/bots/{bot_id} |
One of your bots, with its instructions | agents_bot_get |
| PATCH | /api/v1/agents/bots/{bot_id} |
Change a bot | agents_bot_update |
| DELETE | /api/v1/agents/bots/{bot_id} |
Delete a bot and its routines (its chats stay) | agents_bot_delete |
| GET | /api/v1/agents/bots/{bot_id}/memory |
A bot's memory note | agents_bot_memory_get |
| PUT | /api/v1/agents/bots/{bot_id}/memory |
Rewrite a bot's memory note | agents_bot_memory_update |
| GET | /api/v1/agents/bots/{bot_id}/outreach |
How a bot reaches out: mode, channels, caps and today's counts, pacing, quiet hours, who it may contact, what waits for you, its ledger | agents_bot_outreach_get |
| PATCH | /api/v1/agents/bots/{bot_id}/outreach |
Change how a bot reaches out (owner only) | agents_bot_outreach_update |
| POST | /api/v1/agents/bots/{bot_id}/outreach/decide |
Approve or decline what a bot's runs left waiting, all or some | agents_bot_outreach_decide |
| POST | /api/v1/agents/bots/{bot_id}/outreach/release |
Let a bot write again to someone who replied to it | agents_bot_outreach_release |
| GET | /api/v1/agents/bots/summary |
Your bots at a glance: next and last run, needs-you count, spend, working now | agents_bot_summary_list |
| GET | /api/v1/agents/bots/brief |
What your bots did since you last looked | agents_bot_brief_get |
| DELETE | /api/v1/agents/bots/brief |
Dismiss the brief | agents_bot_brief_dismiss |
| GET | /api/v1/agents/routines |
Your bots' routines | agents_bot_routine_list |
| POST | /api/v1/agents/routines |
Make a bot run by itself on a schedule, an email, a webhook or events in the workspace | agents_bot_routine_create |
| GET | /api/v1/agents/routines/{routine_id} |
One of your bots' routines | agents_bot_routine_get |
| PATCH | /api/v1/agents/routines/{routine_id} |
Change a bot's routine | agents_bot_routine_update |
| DELETE | /api/v1/agents/routines/{routine_id} |
Delete a bot's routine | agents_bot_routine_delete |
| POST | /api/v1/agents/routines/{routine_id}/run |
Run a bot's routine now | agents_bot_routine_run |
| POST | /api/v1/agents/routines/{routine_id}/secret |
A new secret for a bot's webhook or email routine | agents_bot_secret_rotate |
| GET | /api/v1/agents/routines/runs |
Your bots' runs, newest first | agents_bot_run_list |
| GET | /api/v1/agents/routines/runs/{run_id} |
One of your bots' runs | agents_bot_run_get |
| GET | /api/v1/agents/routines/runs/{run_id}/events |
Every item one of your bots' event runs took | agents_bot_run_event_list |
| POST | /api/v1/agents/routines/runs/{run_id}/decide |
Approve or decline what a waiting run asks | agents_bot_run_decide |
| DELETE | /api/v1/agents/workspaces/{workspace_id} |
Delete a workspace and its files on the daemon | agents_workspace_delete |
The console's own API under /api/workspace/agents mirrors the tools for the signed-in browser session; it does not
take API keys. Its routes are listed in Chats API and MCP tools.
MCP tools
48 tools: 21 read, 27 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.
| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
agents_approval_decide |
Answer an agent's approval | write | agents:write |
POST /api/v1/agents/chats/{chat_id}/approvals/{approval_id} |
agents_attachment_delete |
Remove an unsent upload | write (destructive) | agents:write |
DELETE /api/v1/agents/attachments/{file_id} |
agents_attachment_list |
List a chat's files | read | agents:read |
GET /api/v1/agents/chats/{chat_id}/attachments |
agents_attachment_upload |
Upload a file for a quick chat | write | agents:write |
POST /api/v1/agents/attachments |
agents_bot_brief_dismiss |
Dismiss the brief | write | agents:write |
DELETE /api/v1/agents/bots/brief |
agents_bot_brief_get |
What your bots did | read | agents:read |
GET /api/v1/agents/bots/brief |
agents_bot_create |
Make a bot | write | agents:write |
POST /api/v1/agents/bots |
agents_bot_delete |
Delete a bot | write (destructive) | agents:write |
DELETE /api/v1/agents/bots/{bot_id} |
agents_bot_get |
Read a bot | read | agents:read |
GET /api/v1/agents/bots/{bot_id} |
agents_bot_list |
List your bots | read | agents:read |
GET /api/v1/agents/bots |
agents_bot_memory_get |
Read a bot's memory | read | agents:read |
GET /api/v1/agents/bots/{bot_id}/memory |
agents_bot_memory_update |
Rewrite a bot's memory | write | agents:write |
PUT /api/v1/agents/bots/{bot_id}/memory |
agents_bot_outreach_decide |
Answer a bot's approval card | write | agents:write |
POST /api/v1/agents/bots/{bot_id}/outreach/decide |
agents_bot_outreach_get |
How a bot reaches out | read | agents:read |
GET /api/v1/agents/bots/{bot_id}/outreach |
agents_bot_outreach_release |
Let a bot write to someone again | write | agents:write |
POST /api/v1/agents/bots/{bot_id}/outreach/release |
agents_bot_outreach_update |
Change how a bot reaches out | write | agents:write |
PATCH /api/v1/agents/bots/{bot_id}/outreach |
agents_bot_routine_create |
Make a bot's routine | write | agents:write |
POST /api/v1/agents/routines |
agents_bot_routine_delete |
Delete a bot's routine | write (destructive) | agents:write |
DELETE /api/v1/agents/routines/{routine_id} |
agents_bot_routine_get |
Read a bot's routine | read | agents:read |
GET /api/v1/agents/routines/{routine_id} |
agents_bot_routine_list |
List a bot's routines | read | agents:read |
GET /api/v1/agents/routines |
agents_bot_routine_run |
Run a bot's routine now | write | agents:write |
POST /api/v1/agents/routines/{routine_id}/run |
agents_bot_routine_update |
Change a bot's routine | write | agents:write |
PATCH /api/v1/agents/routines/{routine_id} |
agents_bot_run_decide |
Answer what a bot asks | write | agents:write |
POST /api/v1/agents/routines/runs/{run_id}/decide |
agents_bot_run_event_list |
List what started an event run | read | agents:read |
GET /api/v1/agents/routines/runs/{run_id}/events |
agents_bot_run_get |
Read a bot's run | read | agents:read |
GET /api/v1/agents/routines/runs/{run_id} |
agents_bot_run_list |
List your bots' runs | read | agents:read |
GET /api/v1/agents/routines/runs |
agents_bot_secret_rotate |
Rotate a bot routine's secret | write | agents:write |
POST /api/v1/agents/routines/{routine_id}/secret |
agents_bot_summary_list |
Your bots at a glance | read | agents:read |
GET /api/v1/agents/bots/summary |
agents_bot_update |
Change a bot | write | agents:write |
PATCH /api/v1/agents/bots/{bot_id} |
agents_change_get |
List a chat's file changes | read | agents:read |
GET /api/v1/agents/chats/{chat_id}/changes |
agents_chat_archive |
Archive a chat | write (destructive) | agents:write |
DELETE /api/v1/agents/chats/{chat_id} |
agents_chat_create |
Start a chat | write | agents:write |
POST /api/v1/agents/chats |
agents_chat_get |
Read a chat | read | agents:read |
GET /api/v1/agents/chats/{chat_id} |
agents_chat_list |
List chats | read | agents:read |
GET /api/v1/agents/chats |
agents_chat_send |
Send a message to a chat | write | agents:write |
POST /api/v1/agents/chats/{chat_id}/messages |
agents_chat_stop |
Stop a chat's run | write | agents:write |
POST /api/v1/agents/chats/{chat_id}/abort |
agents_chat_update |
Rename a chat, change its mode, gear or servers | write | agents:write |
PATCH /api/v1/agents/chats/{chat_id} |
agents_connection_create |
Connect a catalog server | write | agents:write |
POST /api/v1/agents/connections |
agents_connection_delete |
Disconnect a catalog server | write (destructive) | agents:write |
DELETE /api/v1/agents/connections/{server} |
agents_gear_list |
List the gears a chat can run in | read | agents:read |
GET /api/v1/agents/gears |
agents_project_list |
List a daemon's projects | read | agents:read |
GET /api/v1/agents/projects |
agents_question_respond |
Answer an agent's question | write | agents:write |
POST /api/v1/agents/chats/{chat_id}/questions/{question_id} |
agents_server_list |
List the servers a quick chat can use | read | agents:read |
GET /api/v1/agents/servers |
agents_skill_list |
List the skills a quick chat can use | read | agents:read |
GET /api/v1/agents/skills |
agents_transcript_get |
Read a chat's transcript | read | agents:read |
GET /api/v1/agents/chats/{chat_id}/transcript |
agents_workspace_create |
Make a workspace on a daemon | write | agents:write |
POST /api/v1/agents/workspaces |
agents_workspace_delete |
Delete a workspace | write (destructive) | agents:write |
DELETE /api/v1/agents/workspaces/{workspace_id} |
agents_workspace_list |
List a daemon's workspaces | read | agents:read |
GET /api/v1/agents/workspaces |
Every tool takes format: "json" for structured content and refuses arguments it does not list.