Skip to content
Docs menu

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.

View .md

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 with agents_workspace_create, cloned from a repository), start a chat with agents_chat_create and a prompt, then read agents_transcript_get until the run is done.
  • An approvals bot. Read the transcript or the console's event stream for approval_request events and answer them with agents_approval_decide (allow-once, allow-session, allow-project or deny).
  • A review step. After a run, read the files each turn changed with agents_change_get (turn: a checkpoint's entryId).

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:read for the read tools and agents:write for 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.