Save an automation.
A saved launch (launch, exactly what POST /crews takes, with its budget and time limit) plus what starts it: a schedule (cron in an IANA time zone, or an interval) or a trigger (an address outside programs POST to).
POST/api/v1/automations
Scopeconfig
Every start goes through the same checks as POST /crews: forecast, blockers, budget cap, load-test approval, archived projects. An automation never approves anything. For a trigger the answer carries its secret once (kdt_...). 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.
namestringrequired
The automation's name, shown in the dashboard and on its runs. 1 to 80 characters.
descriptionstring
A note for you; Koidog does not use it. At most 500 characters. Default empty.
launchobjectrequired
The saved launch: exactly what POST /crews takes. Its limits (budget and time limit) are required and bound every crew it starts; text from a trigger never changes the project, limits, placement, models, profiles or size.
ShowHide 11 fields
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 {}.
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 {}.
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 {}.
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.
scheduleobject
What starts an automation on a clock. cron: five fields (minute, hour, day of month, month, day of week; *, lists, ranges and steps) read in timeZone (IANA). interval: every so many minutes from when it was saved.
ShowHide 4 fields
kindenumrequired
cron or interval.
cronstring
Five fields: minute, hour, day of month, month, day of week (*, lists, ranges and steps), such as 0 9 * * 1-5. 9 to 120 characters. With kind cron.
timeZonestring
The IANA time zone the cron is read in, such as Europe/Berlin. 1 to 64 characters. Default UTC. With kind cron.
everyMinutes5–10080
Start every so many minutes, counted from when it was saved. With kind interval.
triggerobject
Who may call the trigger address and how it proves it. - koidog: Koidog's own secret (kdt_...), sent as Authorization: Bearer <secret>, or as an HMAC-SHA256 signature of "<timestamp>.<raw body>" in Koidog-Signature: v1=<hex> with Koidog-Timestamp. - github: a GitHub webhook. GitHub signs the raw body with the same secret (X-Hub-Signature-256); only the listed events (and actions, labels, branches) start a crew.
ShowHide 4 fields
senderenumrequired
koidog: your own program, with the trigger secret. github: a GitHub webhook.
eventsarray
The GitHub events that start it; anything else answers 202 with ignored. 1 to 20 items. With sender github.
ShowHide 2 fields
eventstringrequired
A GitHub event name, as sent in X-GitHub-Event (issues, pull_request, push, ...). 1 to 100 characters. Matches ^[\w.-]+$.
actionsarray
Only these action values of the event. Empty: every action. At most 20 items. Default empty.
labelsarray
Only when the issue or pull request carries one of these labels (or the label just added is one of them). At most 20 items. Default empty. With sender github.
branchesarray
Only for these branches: a push's branch, or a pull request's base branch. At most 20 items. Default empty. With sender github.
inputsobject
{{name}} in the goal or a task's instructions -> a JSON path in the trigger's body, such as issue.title or labels[0].name. Default {}.
guardsobject
The guards every automation has. All have safe defaults; none can be turned off. Default {"maxRunsPerDay":4,"overlap":"skip","disableAfterFailures":3,"missedWindowMinutes":60,"maxInputChars":2000}.
ShowHide 5 fields
maxRunsPerDay1–48
Launch attempts (launched, refused or failed) in any 24 hours. Default 4.
overlapenum
While a crew this automation launched is still active: skip the new start, or keep one start queue_one until it ends. Default skip.
disableAfterFailures1–20
Switched off after this many refused or failed launches in a row. Default 3.
missedWindowMinutes0–1440
After a restart, a run time missed by less than this runs once; an older one is recorded as missed. Default 60.
maxInputChars1–8000
Each placeholder's value is cut to this many characters. Default 2000.
enabledboolean
Off: saved paused. Nothing starts until it is resumed. Default true.
Response.
201 Created: a JSON object. The example has placeholder values.
- 422 validation_failed
- The body does not match its schema; each problem is in
details.