Swarms

A swarm is a named group of agents working together on a shared goal. Swarms have their own task queues, metrics, and lifecycle status. The ChiefCoordinator uses swarms internally for multi-agent orchestration.

Base path: /api/swarms

All endpoints require Authorization: Bearer <token>.

---

Swarm Statuses

Status	Description
draft	Configured but not yet deployed
active	Running and accepting tasks
paused	Temporarily halted
completed	Goal achieved, archived
failed	Stopped due to unrecoverable error

---

List Swarms

GET /api/swarms

Query parameters: status, search, limit, offset

Response:

{
  "success": true,
  "data": [
    {
      "id": "sw_01J...",
      "name": "api-refactor-swarm",
      "description": "Refactor all API routes to use Hono middleware",
      "status": "active",
      "agentCount": 4,
      "taskCount": 12,
      "createdAt": "2026-04-01T08:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 5 }
}

curl:

curl "https://api.cortex.acrobi.com/api/swarms?status=active" \
  -H "Authorization: Bearer <token>"

---

Create Swarm

POST /api/swarms

Request body:

{
  "name": "api-refactor-swarm",
  "description": "Refactor all API routes to use Hono middleware",
  "goal": "All routes use consistent Hono patterns with typed responses",
  "coordinatorAgent": "chief",
  "status": "draft"
}

Field	Type	Required	Description
name	string	Yes	Unique swarm name
description	string	No	Human-readable description
goal	string	No	Objective statement for the swarm
coordinatorAgent	string	No	Agent acting as coordinator
status	string	No	Default draft

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "sw_01J...",
    "name": "api-refactor-swarm",
    "status": "draft",
    "createdAt": "2026-04-03T12:00:00Z"
  }
}

---

Get Swarm

GET /api/swarms/:id

Response:

{
  "success": true,
  "data": {
    "id": "sw_01J...",
    "name": "api-refactor-swarm",
    "description": "Refactor all API routes",
    "goal": "All routes use consistent Hono patterns",
    "status": "active",
    "coordinatorAgent": "chief",
    "agents": ["backend-coder", "qa-tester", "architect"],
    "taskCount": 12,
    "completedTasks": 7,
    "createdAt": "2026-04-01T08:00:00Z",
    "updatedAt": "2026-04-03T11:00:00Z"
  }
}

---

Update Swarm

PATCH /api/swarms/:id

Request body:

{
  "description": "Refactor routes and add OpenAPI documentation",
  "goal": "All routes typed, documented, and tested"
}

Response: 200 OK — returns updated swarm object.

---

Delete Swarm

DELETE /api/swarms/:id

Deletes the swarm. Active swarms must be paused or completed first.

Response:

{ "success": true }

---

Change Swarm Status

PATCH /api/swarms/:id/status

Transitions the swarm to a new lifecycle state.

Request body:

{ "status": "active" }

Valid transitions:

From	To
draft	active
active	paused, completed, failed
paused	active, completed

Response: 200 OK

{
  "success": true,
  "data": { "id": "sw_01J...", "status": "active" }
}

curl:

curl -X PATCH "https://api.cortex.acrobi.com/api/swarms/sw_01J.../status" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

---

Get Swarm Metrics

GET /api/swarms/:id/metrics

Query parameters: period (7d, 30d — default 7d)

Response:

{
  "success": true,
  "data": {
    "swarmId": "sw_01J...",
    "period": "7d",
    "tasks": {
      "total": 12,
      "completed": 7,
      "inProgress": 3,
      "blocked": 1,
      "failed": 1,
      "completionRate": 0.583
    },
    "agents": {
      "total": 4,
      "active": 3,
      "idle": 1
    },
    "performance": {
      "avgTaskDurationMs": 142000,
      "totalTokensUsed": 84200
    }
  }
}

---

List Swarm Agents

GET /api/swarms/:id/agents

Response:

{
  "success": true,
  "data": [
    {
      "agentName": "backend-coder",
      "role": "implementer",
      "joinedAt": "2026-04-01T08:05:00Z",
      "tasksCompleted": 4,
      "status": "working"
    }
  ]
}

---

Add Agent to Swarm

POST /api/swarms/:id/agents

Request body:

{
  "agentName": "qa-tester",
  "role": "validator"
}

Response: 201 Created

{ "success": true }

---

Remove Agent from Swarm

DELETE /api/swarms/:id/agents/:agentId

Response:

{ "success": true }

---

List Swarm Tasks

GET /api/swarms/:id/tasks

Returns tasks scoped to this swarm.

Query parameters: status, priority, limit, offset

Response:

{
  "success": true,
  "data": [
    {
      "id": "tk_01J...",
      "title": "Refactor agents route",
      "status": "done",
      "assignedAgent": "backend-coder",
      "priority": "high"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 12 }
}

---

Create Swarm Task

POST /api/swarms/:id/tasks

Creates a task pre-associated with this swarm. Accepts the same body as POST /api/kanban-tasks.

Response: 201 Created — returns the new task object.