Docs
Sign in

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 in details) when the forecast has blockers.
422 validation_failed
The body does not match its schema; each problem is in details.