Launch a crew.
Writes the crew and its tasks, then schedules agents.
POST/api/v1/crews
Scopecrews
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.
Idempotency-Keystring
Makes a retry safe: the same key with the same request returns the first answer and does nothing else.
Body.
projectIdstringrequired
The project the crew works on. At least 5 characters.
goalstringrequired
What the crew should do. At least 1 character.
modeenumrequired
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.
requestedSize1–100 | "auto"required
Requested workers. auto lets a managed crew's plan decide.
tasksarray
Direct mode: the jobs. Empty in managed mode, where the manager plans them. Default empty.
ShowHide 4 fields
titlestringrequired
A short name for the task, shown on the timeline and the pull request. At least 1 character.
instructionsstringrequired
What the agent should do: the whole brief it is given for this task. At least 1 character.
roleenum
The kind of agent that does it. One of manager, builder, tester, reviewer, researcher, integrator. Default builder.
requiresobject
What the machine must have to run it. Left out, any machine the crew may use. Default {"tools":[]}.
ShowHide 3 fields
osenum
Only machines with this operating system. One of macos, linux.
xcodeboolean
Only machines with Xcode installed.
toolsarray
Command names the machine must have (as the node reports them), such as xcodebuild or docker. Default empty.
repeatGoalboolean
Direct mode shortcut: run the goal itself as N identical independent jobs. Default false.
profilesobjectrequired
Connection ids per role: builder (required), and manager and reviewer when used.
ShowHide 3 fields
managerstring
The connection id a managed crew's manager uses. Left out, the manager uses the builders' connection. At least 5 characters.
builderstringrequired
The connection id the builders use. At least 5 characters.
reviewerstring
The connection id the reviewer uses (managed crews). At least 5 characters.
modelsobject
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.
ShowHide 3 fields
managerobject
A model picked for a role: which model on the role's connection, with which options.
ShowHide 2 fields
modelstringrequired
A model id on the role's connection, as GET /connections/{id}/models lists it. At least 1 character.
optionsobject
Per-run settings chosen alongside a model. Unset means the harness's own default. Default {}.
ShowHide 1 field
effortenum
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.
builderobject
A model picked for a role: which model on the role's connection, with which options.
ShowHide 2 fields
modelstringrequired
A model id on the role's connection, as GET /connections/{id}/models lists it. At least 1 character.
optionsobject
Per-run settings chosen alongside a model. Unset means the harness's own default. Default {}.
ShowHide 1 field
effortenum
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.
reviewerobject
A model picked for a role: which model on the role's connection, with which options.
ShowHide 2 fields
modelstringrequired
A model id on the role's connection, as GET /connections/{id}/models lists it. At least 1 character.
optionsobject
Per-run settings chosen alongside a model. Unset means the harness's own default. Default {}.
ShowHide 1 field
effortenum
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.
placementobject
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.
ShowHide 5 fields
policyenum
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.
pinnedNodeIdstring
Run every agent on this one machine (a machine id). No cloud worker is used. At least 5 characters.
deniedNodeIdsarray
Machine ids the crew may not use. Default empty.
allowCloudboolean
The crew may start cloud VMs, within its limits. Default true.
allowLocalboolean
The crew may use your paired machines. Default true.
limitsobjectrequired
budgetUsd and maxVms are hard caps on cloud compute for this crew; timeoutMinutes is its time limit.
ShowHide 5 fields
budgetUsdnumberrequired
Hard cap on cloud compute spend for this crew, in dollars. ≥ 0.
maxVms0–100required
The most cloud VMs this crew may have open at once. 0 starts none.
timeoutMinutesintegerrequired
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.
maxRetries0–5
How many times a failed agent is run again before its task fails. Default 1.
reviewobject
Review, re-plan and reviewer bounds. Absent: each bound takes the default shown below.
ShowHide 8 fields
managerReviewboolean
Managed crews: the manager reviews the merged, checked result before anything is delivered. Default true.
reviewerenum
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.
followUpRounds0–5
How many times the crew may go back for follow-up work (a manager review or a reviewer asking for changes). Default 2.
replans0–3
Managed crews: re-plan turns after a task fails for good or its merge cannot be resolved. Default 1.
maxAddedTasks0–20
Tasks the crew may add after its first plan, by review, re-plan and reviewer together. Default 5.
planApprovalboolean
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.
planRevisions0–10
With planApproval: how many times the founder may send the plan back for changes. Absent: 3.
steers0–50
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.
presetstring
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 indetails) when the forecast has blockers. - 422 validation_failed
- The body does not match its schema; each problem is in
details.