Docs
Sign in

Change an automation.

A new schedule takes effect from now.

PATCH/api/v1/automations/{id}

Scopeconfig

A schedule cannot become a trigger or the other way round. When an API key calls it, the timeline records who did what and the outcome. No query parameters.

Path parameters.

idstringrequired

The automation's id.

Body.

namestring

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.

launchobject

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.

guardsobject

Only the fields given change; a field left out keeps its value (no default is filled in).

ShowHide 5 fields

maxRunsPerDay1–48

Launch attempts (launched, refused or failed) in any 24 hours.

overlapenum

While a crew this automation launched is still active: skip the new start, or keep one start queue_one until it ends.

disableAfterFailures1–20

Switched off after this many refused or failed launches in a row.

missedWindowMinutes0–1440

After a restart, a run time missed by less than this runs once; an older one is recorded as missed.

maxInputChars1–8000

Each placeholder's value is cut to this many characters.

Response.

200 OK: a JSON object. The example has placeholder values.

422 validation_failed
The body does not match its schema; each problem is in details.