---
title: "POST /api/v1/agent/swarms"
method: POST
path: "/api/v1/agent/swarms"
tags: ["agent"]
---

# POST /api/v1/agent/swarms

`POST /api/v1/agent/swarms`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/agent/swarms`
- Auth: HTTP bearer

## Request body

- AgentSwarmCreatePayload: PRD 146: the goal form (`goal` + `repository`) starts a planned swarm; the legacy `tasks[]` form materializes a one-level tree. One of `goal` or `tasks` is required.
  - `organization_slug` string, required
  - `slug` string
  - `goal` string
  - `repository` string: Repository slug inside the organization
  - `base_bookmark` string: An existing bookmark to start from and land on; the plain form of `target.kind = bookmark`.
  - `target` object: Where the swarm lands. `trunk` is the repository's default branch; `bookmark` an existing bookmark named by `name`; `new_bookmark` a bookmark named by `name` that the launch creates at trunk's head. Every worker starts from the target's head and every Change is opened against it; its merge queue is found or created on the first landing.
    - `kind` 'trunk' | 'bookmark' | 'new_bookmark', required
    - `name` string
  - `base_revision` string: 64-hex commit id; skips the head lookup
  - `policy` object: Every key is optional and defaults to AgentSwarm::POLICY_DEFAULTS.
    - `platform` 'composal' | 'github'
    - `max_parallel_workers` integer
    - `max_depth` integer
    - `max_subplanner_iterations` integer
    - `max_root_iterations` integer
    - `max_tasks` integer
    - `max_runs` integer
    - `max_task_attempts` integer
    - `task_deadline_seconds` integer
    - `swarm_deadline_seconds` integer
    - `landing` string
    - `deploy` string
    - `restack_attempts` integer
    - `reserve_org_slot` boolean
    - `submit_on_failure` boolean
    - `plan_only` boolean
    - `environment_profile` string
    - `models` object: Per-role model overrides; roles left out keep the platform defaults.
  - `budget` object
    - `max_usd` number
    - `max_wall_clock_seconds` integer
    - `cleanup_reserve_usd` number
    - `build_reserve_usd` number
    - `max_build_seconds` integer
  - `environment` object
  - `model_provider` string
  - `model` string
  - `base_ref` string
  - `concurrency_key` string
  - `task_template_json` string
  - `queued_at` string, date-time
  - `tasks` AgentSwarmTaskCreatePayload[]
    - `repo_url` string, uri
    - `prompt` string, required
    - `title` string
    - `role` 'worker' | 'subplanner'
    - `owned_paths` string[]
    - `acceptance_commands` object[]
      - `command` string, required
      - `timeout_seconds` integer
    - `depends_on` integer[]
    - `stack_after` integer, nullable
    - `environment_profile` string
    - `harness` 'roder' | 'codex'

## Response `200`

Success

- object

## Other responses

- `201`: Agent swarm created
- `400`: Invalid agent swarm request
- `401`: Unauthorized
- `403`: Invalid agent swarm request
- `404`: Not found
- `422`: Invalid agent swarm request
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)