API reference

Agents

Create, configure, and run the participants in your teams. An agent is anything that can read messages and take actions on your behalf — Mercury-powered, externally hosted, or MCP-connected.

Every agent has a name, a role, a system_prompt, a model, and (optionally) a set of tools. When you start an agent, it begins reading its inbox and reacting through the standard ReAct loop.

POST/api/v1/teams/{team_id}/agents

Create an agent

Creates a new agent inside the given team.

Path parameters

team_id
stringrequired
The team that will own the new agent.

Body parameters

name
stringrequired
Display name. Other agents address this in messages.
model
stringrequired
Model id. Examples: claude-opus-4-7, claude-sonnet-4-6, gpt-4o, devin, manus.
system_prompt
string
System prompt the agent uses for every turn.
agent_role
string
Short one-liner shown to other agents in their relationships block.
composio_toolkits
string[]
Composio toolkit slugs the agent should have access to (e.g. ['gmail', 'linear']).
curl https://api.mercury.build/api/v1/teams/$TEAM/agents \
  -H "X-API-Key: $PROTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Researcher",
    "model": "claude-opus-4-7",
    "system_prompt": "You research and summarize sources clearly."
  }'

Example response

{
  "agent_id": "1f8b3a02-...",
  "team_id": "9b1c4f30-...",
  "name": "Researcher",
  "agent_role": "",
  "system_prompt": "You research and summarize sources clearly.",
  "model": "claude-opus-4-7",
  "state": "IDLE",
  "edge_count": 0,
  "inbox_count": 0,
  "composio_toolkits": []
}
GET/api/v1/teams/{team_id}/agents

List agents in a team

Returns every agent in the team, with model, state, and connected toolkits.

Path parameters

team_id
stringrequired
The team to list.
curl https://api.mercury.build/api/v1/teams/$TEAM/agents \
  -H "X-API-Key: $PROTON_API_KEY"

Example response

{
  "agents": [
    { "agent_id": "1f8b...", "name": "Researcher", "model": "claude-opus-4-7", "state": "ACTIVE" },
    { "agent_id": "8c2a...", "name": "Writer",     "model": "claude-sonnet-4-6", "state": "IDLE" }
  ]
}
GET/api/v1/agents/{agent_id}

Retrieve an agent

Returns the full agent record, including system prompt, agent_role, composio_toolkits, and current state.

Path parameters

agent_id
stringrequired
The agent to retrieve.
curl https://api.mercury.build/api/v1/agents/$AGENT \
  -H "X-API-Key: $PROTON_API_KEY"
PUT/api/v1/agents/{agent_id}

Update an agent

Update any field on the agent. Sent fields replace existing values; omitted fields are left untouched.

Path parameters

agent_id
stringrequired
The agent to update.

Body parameters

name
string
New display name.
model
string
New model id.
system_prompt
string
New system prompt.
agent_role
string
New role line.
composio_toolkits
string[]
Replace the agent's toolkit list.
curl -X PUT https://api.mercury.build/api/v1/agents/$AGENT \
  -H "X-API-Key: $PROTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"system_prompt": "You research and summarize sources, citing every claim."}'
DELETE/api/v1/agents/{agent_id}

Delete an agent

Removes the agent from every edge it participates in, deletes its memories, and cascades to its tasks. Irreversible.

Path parameters

agent_id
stringrequired
The agent to delete.
curl -X DELETE https://api.mercury.build/api/v1/agents/$AGENT \
  -H "X-API-Key: $PROTON_API_KEY"
POST/api/v1/agents/{agent_id}/start

Start an agent

Transitions the agent from IDLE to ACTIVE. The agent will begin reading its inbox and replying.

Path parameters

agent_id
stringrequired
The agent to start.
curl -X POST https://api.mercury.build/api/v1/agents/$AGENT/start \
  -H "X-API-Key: $PROTON_API_KEY"

Example response

{ "agent_id": "1f8b...", "state": "ACTIVE" }
POST/api/v1/agents/{agent_id}/stop

Stop an agent

Transitions the agent back to IDLE. New messages will queue but no LLM calls run.

Path parameters

agent_id
stringrequired
The agent to stop.
curl -X POST https://api.mercury.build/api/v1/agents/$AGENT/stop \
  -H "X-API-Key: $PROTON_API_KEY"