# Launch a crew.

> Writes the crew and its tasks, then schedules agents.
> https://koi.dog/docs/api/crews/launch-crew/

`POST /api/v1/crews` · Scope: `crews`

The crew then runs on its own: follow `GET /events/stream?crewId=` and read `GET /crews/{id}`. When an API key calls it, the timeline records who did what and the outcome. No path or query parameters.

## Headers.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | `string` | no | Makes a retry safe: the same key with the same request returns the first answer and does nothing else. |

## Body.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | The project the crew works on. At least 5 characters. |
| `goal` | `string` | yes | What the crew should do. At least 1 character. |
| `mode` | `enum` | yes | `direct` runs the tasks you list (or the goal, with `repeatGoal`); `managed` lets a manager plan the tasks and merge them into one pull request. |
| `requestedSize` | `1–100 \| "auto"` | yes | Requested workers. `auto` lets a managed crew's plan decide. |
| `tasks` | `array` | no | Direct mode: the jobs. Empty in managed mode, where the manager plans them. Default empty. |
| `tasks[].title` | `string` | yes | A short name for the task, shown on the timeline and the pull request. At least 1 character. |
| `tasks[].instructions` | `string` | yes | What the agent should do: the whole brief it is given for this task. At least 1 character. |
| `tasks[].role` | `enum` | no | The kind of agent that does it. One of `manager`, `builder`, `tester`, `reviewer`, `researcher`, `integrator`. Default `builder`. |
| `tasks[].requires` | `object` | no | What the machine must have to run it. Left out, any machine the crew may use. Default `{"tools":[]}`. |
| `tasks[].requires.os` | `enum` | no | Only machines with this operating system. One of `macos`, `linux`. |
| `tasks[].requires.xcode` | `boolean` | no | Only machines with Xcode installed. |
| `tasks[].requires.tools` | `array` | no | Command names the machine must have (as the node reports them), such as `xcodebuild` or `docker`. Default empty. |
| `repeatGoal` | `boolean` | no | Direct mode shortcut: run the goal itself as N identical independent jobs. Default `false`. |
| `profiles` | `object` | yes | Connection ids per role: `builder` (required), and `manager` and `reviewer` when used. |
| `profiles.manager` | `string` | no | The connection id a managed crew's manager uses. Left out, the manager uses the builders' connection. At least 5 characters. |
| `profiles.builder` | `string` | yes | The connection id the builders use. At least 5 characters. |
| `profiles.reviewer` | `string` | no | The connection id the reviewer uses (managed crews). At least 5 characters. |
| `models` | `object` | no | Model and options per role; a role left out uses its connection's default. Default `{}`. Left out, every role uses its connection's default model. |
| `models.manager` | `object` | no | A model picked for a role: which model on the role's connection, with which options. |
| `models.manager.model` | `string` | yes | A model id on the role's connection, as `GET /connections/{id}/models` lists it. At least 1 character. |
| `models.manager.options` | `object` | no | Per-run settings chosen alongside a model. Unset means the harness's own default. Default `{}`. |
| `models.manager.options.effort` | `enum` | no | How much reasoning the model spends, where its harness lets you choose. Left out, the harness's default. One of `low`, `medium`, `high`, `xhigh`, `max`. |
| `models.builder` | `object` | no | A model picked for a role: which model on the role's connection, with which options. |
| `models.builder.model` | `string` | yes | A model id on the role's connection, as `GET /connections/{id}/models` lists it. At least 1 character. |
| `models.builder.options` | `object` | no | Per-run settings chosen alongside a model. Unset means the harness's own default. Default `{}`. |
| `models.builder.options.effort` | `enum` | no | How much reasoning the model spends, where its harness lets you choose. Left out, the harness's default. One of `low`, `medium`, `high`, `xhigh`, `max`. |
| `models.reviewer` | `object` | no | A model picked for a role: which model on the role's connection, with which options. |
| `models.reviewer.model` | `string` | yes | A model id on the role's connection, as `GET /connections/{id}/models` lists it. At least 1 character. |
| `models.reviewer.options` | `object` | no | Per-run settings chosen alongside a model. Unset means the harness's own default. Default `{}`. |
| `models.reviewer.options.effort` | `enum` | no | How much reasoning the model spends, where its harness lets you choose. Left out, the harness's default. One of `low`, `medium`, `high`, `xhigh`, `max`. |
| `placement` | `object` | no | `allowLocal` and `allowCloud` choose paired machines, cloud VMs or both; `deniedNodeIds` leaves machines out. Default `{"policy":"lowest_cost","deniedNodeIds":[],"allowCloud":true,"allowLocal":true}`. Left out, the crew may use cloud VMs, which cost money within `limits.budgetUsd`, and your paired machines. |
| `placement.policy` | `enum` | no | `pinned` runs only on `pinnedNodeId`. `lowest_cost` and `fastest` place the same way today: paired machines before cloud workers, the one with the most free slots first. Default `lowest_cost`. |
| `placement.pinnedNodeId` | `string` | no | Run every agent on this one machine (a machine id). No cloud worker is used. At least 5 characters. |
| `placement.deniedNodeIds` | `array` | no | Machine ids the crew may not use. Default empty. |
| `placement.allowCloud` | `boolean` | no | The crew may start cloud VMs, within its `limits`. Default `true`. |
| `placement.allowLocal` | `boolean` | no | The crew may use your paired machines. Default `true`. |
| `limits` | `object` | yes | `budgetUsd` and `maxVms` are hard caps on cloud compute for this crew; `timeoutMinutes` is its time limit. |
| `limits.budgetUsd` | `number` | yes | Hard cap on cloud compute spend for this crew, in dollars. ≥ 0. |
| `limits.maxVms` | `0–100` | yes | The most cloud VMs this crew may have open at once. 0 starts none. |
| `limits.timeoutMinutes` | `integer` | yes | The crew's time limit in minutes. When it passes, the crew fails with "Timed out". Time spent waiting for your approval of a plan is not counted. > 0. |
| `limits.maxRetries` | `0–5` | no | How many times a failed agent is run again before its task fails. Default `1`. |
| `limits.review` | `object` | no | Review, re-plan and reviewer bounds. Absent: each bound takes the default shown below. |
| `limits.review.managerReview` | `boolean` | no | Managed crews: the manager reviews the merged, checked result before anything is delivered. Default `true`. |
| `limits.review.reviewer` | `enum` | no | An independent reviewer agent before the crew's pull request (managed) or each task's pull request (direct). "auto": only when the launch named a reviewer connection or reviewer model. One of `auto`, `on`, `off`. Default `auto`. |
| `limits.review.followUpRounds` | `0–5` | no | How many times the crew may go back for follow-up work (a manager review or a reviewer asking for changes). Default `2`. |
| `limits.review.replans` | `0–3` | no | Managed crews: re-plan turns after a task fails for good or its merge cannot be resolved. Default `1`. |
| `limits.review.maxAddedTasks` | `0–20` | no | Tasks the crew may add after its first plan, by review, re-plan and reviewer together. Default `5`. |
| `limits.review.planApproval` | `boolean` | no | Managed crews: after the manager's plan is checked, the crew waits for the founder to approve it before any task starts or any builder machine is used. Absent: off. Refused on a direct crew. |
| `limits.review.planRevisions` | `0–10` | no | With planApproval: how many times the founder may send the plan back for changes. Absent: 3. |
| `limits.review.steers` | `0–50` | no | Managed crews: how many steering messages the founder may send the manager after the plan is made (`POST /crews/{id}/steer`). Absent: 10. 0 turns steering off. |
| `preset` | `string` | no | A name kept with the crew. The server stores it and does nothing else with it. |

## Response.

201 Created: a `CrewView`. The example has placeholder values.

- **409 launch_blocked**: Refused with `409 launch_blocked` (every blocker in `details`) when the forecast has blockers.
- **422 validation_failed**: The body does not match its schema; each problem is in `details`.

## Request.

```sh
curl -X POST https://app.koi.dog/api/v1/crews \
    -H "Authorization: Bearer $KOIDOG_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "projectId": "prj_1m7h5x2kdq8wv3tfa7c",
      "goal": "Add a dark mode to the settings page",
      "mode": "direct",
      "requestedSize": 1,
      "tasks": [
        {
          "title": "Dark mode",
          "instructions": "Add a dark mode switch to the settings page and keep the choice after a reload."
        }
      ],
      "profiles": {
        "builder": "con_1m7h5y0nb4rkz9pqe2h"
      },
      "placement": {
        "allowCloud": false
      },
      "limits": {
        "budgetUsd": 0,
        "maxVms": 0,
        "timeoutMinutes": 60
      }
    }'
```

```js
const res = await fetch("https://app.koi.dog/api/v1/crews", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOIDOG_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    projectId: "prj_1m7h5x2kdq8wv3tfa7c",
    goal: "Add a dark mode to the settings page",
    mode: "direct",
    requestedSize: 1,
    tasks: [
      {
        title: "Dark mode",
        instructions: "Add a dark mode switch to the settings page and keep the choice after a reload.",
      },
    ],
    profiles: {
      builder: "con_1m7h5y0nb4rkz9pqe2h",
    },
    placement: {
      allowCloud: false,
    },
    limits: {
      budgetUsd: 0,
      maxVms: 0,
      timeoutMinutes: 60,
    },
  }),
});
console.log(await res.json());
```

```python
import os
import uuid

import requests

r = requests.post(
    "https://app.koi.dog/api/v1/crews",
    headers={
        "Authorization": f"Bearer {os.environ['KOIDOG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "projectId": "prj_1m7h5x2kdq8wv3tfa7c",
        "goal": "Add a dark mode to the settings page",
        "mode": "direct",
        "requestedSize": 1,
        "tasks": [
            {
                "title": "Dark mode",
                "instructions": "Add a dark mode switch to the settings page and keep the choice after a reload.",
            },
        ],
        "profiles": {
            "builder": "con_1m7h5y0nb4rkz9pqe2h",
        },
        "placement": {
            "allowCloud": False,
        },
        "limits": {
            "budgetUsd": 0,
            "maxVms": 0,
            "timeoutMinutes": 60,
        },
    },
)
r.raise_for_status()
print(r.json())
```

## Response example.

```json
{
  "crew": {
    "id": "string",
    "projectId": "string",
    "goal": "string",
    "mode": "direct",
    "requestedSize": 0,
    "maxAgents": 0,
    …
  },
  "projectName": "string",
  "agents": { … },
  "tasks": {
    "total": 0,
    "done": 0,
    "failed": 0,
    "blocked": 0
  },
  "vmsRunning": 0,
  "spentUsd": 0,
  "managerNote": "string",
  …
}
```

```json
{
  "error": {
    "type": "conflict",
    "code": "launch_blocked",
    "message": "Project \"Landing page\" is archived. Unarchive it to launch a crew on it.",
    "requestId": "req_q8M2x7C4k9TzWb3n",
    "details": [
      {
        "message": "Project \"Landing page\" is archived. Unarchive it to launch a crew on it."
      }
    ]
  }
}
```
