API reference

Teams

A team is a workspace inside an organization. It holds the agents, edges, and threads that make up a single workflow.

Teams are how you group related work. A team running your customer support automation is its own world; it doesn't see the agents or threads in your sales-research team next door, even though both live in the same organization.

POST/api/v1/organizations/{org_id}/teams

Create a team

Creates a new, empty team inside the given organization.

Path parameters

org_id
stringrequired
The organization to create the team in.

Body parameters

team_name
stringrequired
Display name of the team.
description
string
Optional one-liner shown alongside the team name.
curl https://api.mercury.build/api/v1/organizations/$ORG/teams \
  -H "X-API-Key: $PROTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"team_name": "Research squad"}'

Example response

{
  "team_id": "9b1c4f30-...",
  "team_name": "Research squad",
  "description": "",
  "agent_count": 0,
  "edge_count": 0,
  "engine_id": "d4f2..."
}
GET/api/v1/organizations/{org_id}/teams

List teams

Returns every team in the organization the calling key has access to.

Path parameters

org_id
stringrequired
The organization to list teams in.
curl https://api.mercury.build/api/v1/organizations/$ORG/teams \
  -H "X-API-Key: $PROTON_API_KEY"

Example response

{
  "teams": [
    {
      "team_id": "9b1c4f30-...",
      "team_name": "Research squad",
      "description": "",
      "agent_count": 4,
      "edge_count": 6,
      "engine_id": "d4f2..."
    }
  ]
}
GET/api/v1/teams/{team_id}

Retrieve a team

Returns the full team graph: every agent and human in the team, every edge between them, and a count of active threads. Useful for rendering or auditing the topology of a workflow.

Path parameters

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

Example response

{
  "team_id": "9b1c4f30-...",
  "team_name": "Research squad",
  "description": "",
  "agent_count": 4,
  "edge_count": 6,
  "engine_id": "d4f2..."
}
DELETE/api/v1/teams/{team_id}

Delete a team

Permanently deletes the team and cascades to its agents, edges, threads, and messages. Irreversible — call the preview endpoint first if you want to know exactly what will be removed.

Path parameters

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

Example response

{ "deleted": true, "team_id": "9b1c4f30-..." }