> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-spec-sync-1774445910.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Swarms API

> Create and manage agent swarms for coordinated multi-agent workflows

# Swarms API

Swarms let you group multiple agents into a coordinated unit. Use swarms to orchestrate multi-agent workflows where agents collaborate on tasks.

<Note>All swarm endpoints require session authentication and are scoped to the authenticated user's data through [row-level security](/security#row-level-security).</Note>

## List swarms

```http theme={null}
GET /api/swarms
```

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

### Response

```json theme={null}
{
  "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

| Field         | Type           | Description                                  |
| ------------- | -------------- | -------------------------------------------- |
| `id`          | string         | Unique swarm identifier                      |
| `name`        | string         | Swarm display name                           |
| `description` | string \| null | Optional description of the swarm            |
| `agents`      | string\[]      | Array of agent IDs that belong to this swarm |
| `enabled`     | boolean        | Whether the swarm is currently active        |
| `createdAt`   | string         | ISO 8601 creation timestamp                  |

### Errors

| Code | Description            |
| ---- | ---------------------- |
| 401  | Unauthorized           |
| 500  | Failed to fetch swarms |

## Create swarm

```http theme={null}
POST /api/swarms
```

Creates a new agent swarm. The swarm is enabled by default.

### Request body

```json theme={null}
{
  "name": "Production Fleet",
  "description": "Main production agent swarm",
  "agents": ["agent_1", "agent_2", "agent_3"],
  "config": {}
}
```

| Parameter     | Type      | Required | Description                                                            |
| ------------- | --------- | -------- | ---------------------------------------------------------------------- |
| `name`        | string    | Yes      | Swarm name. Must be between 1 and 100 characters                       |
| `description` | string    | No       | Optional description                                                   |
| `agents`      | string\[] | No       | Array of agent IDs to include in the swarm. Defaults to an empty array |
| `config`      | object    | No       | Optional configuration object                                          |

### Response

Returns `201 Created` with the new swarm object:

```json theme={null}
{
  "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

| Code | Description                                |
| ---- | ------------------------------------------ |
| 400  | Name is required or exceeds 100 characters |
| 401  | Unauthorized                               |
| 500  | Failed to create swarm                     |