Skip to main content

​
Swarms API

Swarms let you group multiple agents into a coordinated unit. Use swarms to orchestrate multi-agent workflows where agents collaborate on tasks.
All swarm endpoints require session authentication and are scoped to the authenticated user’s data through row-level security.

​
List swarms

GET /api/swarms
Returns all swarms owned by the authenticated user, ordered by creation date (newest first).

​
Response

{
  "swarms": [
    {
      "id": "swarm_abc123",
      "name": "Production Fleet",
      "description": "Main production agent swarm",
      "agents": ["agent_1", "agent_2", "agent_3"],
      "enabled": true,
      "createdAt": "2026-03-21T12:00:00.000Z"
    }
  ],
  "count": 1
}

​
Swarm object

FieldTypeDescription
idstringUnique swarm identifier
namestringSwarm display name
descriptionstring | nullOptional description of the swarm
agentsstring[]Array of agent IDs that belong to this swarm
enabledbooleanWhether the swarm is currently active
createdAtstringISO 8601 creation timestamp

​
Errors

CodeDescription
401Unauthorized
500Failed to fetch swarms

​
Create swarm

POST /api/swarms
Creates a new agent swarm. The swarm is enabled by default.

​
Request body

{
  "name": "Production Fleet",
  "description": "Main production agent swarm",
  "agents": ["agent_1", "agent_2", "agent_3"],
  "config": {}
}
ParameterTypeRequiredDescription
namestringYesSwarm name. Must be between 1 and 100 characters
descriptionstringNoOptional description
agentsstring[]NoArray of agent IDs to include in the swarm. Defaults to an empty array
configobjectNoOptional configuration object

​
Response

Returns 201 Created with the new swarm object: 
{
  "id": "swarm_abc123",
  "name": "Production Fleet",
  "description": "Main production agent swarm",
  "agents": ["agent_1", "agent_2", "agent_3"],
  "enabled": true,
  "createdAt": "2026-03-21T12:00:00.000Z"
}

​
Errors

CodeDescription
400Name is required or exceeds 100 characters
401Unauthorized
500Failed to create swarm