Review Swarms

Base path /api/v1/swarms on https://ionwarp.com. Authenticate with Authorization: Bearer $DASH_API_KEY and name the project with the Project-ID header. Writes are validated in declared mode; an operation this resource does not declare answers 405 operation_not_supported.

List review swarms

GET /api/v1/swarms

curl "https://ionwarp.com/api/v1/swarms?status=template" \
  -H "Authorization: Bearer $DASH_API_KEY" \
  -H "Project-ID: pr_acme"

Show me the review swarms filtered by status

data_query {
  "collection": "swarms",
  "where": {
    "status": "template"
  }
}

Returns a paginated list of swarm objects, newest first.

{
  "object": "list",
  "data": [
    {
      "object": "swarm",
      "id": "obj_123",
      "name": "Full Review",
      "kind": "pr_review",
      "status": "running",
      "created_at": "2026-07-25T12:00:00.000Z",
      "updated_at": "2026-07-25T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Parameters

Parameter	Type	Kind	Description
`status`	string	filter	`template` is a reusable lineup that has not been run; the rest are one live execution of it. One of `template`, `queued`, `running`, `done`, `failed`.
`kind`	string	filter	What the swarm is for — e.g. `pr_review` for the lineup that reviews a pull request.
`related_pr`	string	filter	Pull request this swarm is reviewing, when it is a PR review.
`related_scorecard`	string	filter	Scorecard this swarm is scanning, when it is a scorecard run.
`q`	string	search	Free-text search across `name`, `goal`.
`sort`	string	sort	One of `name`; prefix with `-` to reverse.
`limit`	number	page	Rows to return, 1–100. Defaults to 20.
`cursor`	string	page	`next_cursor` from the previous page.

Retrieve a swarm

GET /api/v1/swarms/learning-tests-run-under-bun

curl "https://ionwarp.com/api/v1/swarms/learning-tests-run-under-bun" \
  -H "Authorization: Bearer $DASH_API_KEY" \
  -H "Project-ID: pr_acme"

What is swarm {id} working on right now?

data_get {
  "collection": "swarms",
  "object_id": "learning-tests-run-under-bun"
}

Returns the swarm object.

{
  "object": "swarm",
  "id": "obj_123",
  "name": "Full Review",
  "kind": "pr_review",
  "status": "running",
  "created_at": "2026-07-25T12:00:00.000Z",
  "updated_at": "2026-07-25T12:00:00.000Z"
}

Parameters

Parameter	Type	Kind	Description
`id`	string	path	The swarm's id or slug.

What comes back (read-only)

Every swarm carries the envelope below. The fields under it are computed or stamped by the platform — they are returned, never sent.

Field	Type	Description
`object`	string	Always `swarm`.
`id`	string	Stable object id. Also accepted in place of `slug` on any path.
`slug`	string	URL-safe name, unique within the collection.
`created_at`	string	ISO-8601 timestamp of the first write.
`updated_at`	string	ISO-8601 timestamp of the most recent write. The cursor sorts on this.
`name`	string	Name of the swarm.
`kind`	string	What the swarm is for — e.g. `pr_review` for the lineup that reviews a pull request.
`status`	string	`template` is a reusable lineup that has not been run; the rest are one live execution of it.
`goal`	string	What the swarm is coordinating toward, in one line.
`agent_ids`	array	Teammates taking part, by `agents` (teammate) id.
`skill_ids`	array	Reviewer skills the swarm runs. Matches `agent_ids` for the seeded lineups, where a teammate is its skill.
`related_pr`	string	Pull request this swarm is reviewing, when it is a PR review.
`related_scorecard`	string	Scorecard this swarm is scanning, when it is a scorecard run.
`active_task_id`	string	Task carrying the swarm's current execution, while one is running.

Errors

Failures use { error: { type, code, message, param } }. The full code table is generated at Error Codes.

List review swarms

Response 200

Retrieve a swarm

Response 200

What comes back (read-only)

Errors

On this page