# Change an automation.

> A new schedule takes effect from now.
> https://koi.dog/docs/api/automations/update-automation/

`PATCH /api/v1/automations/{id}` · Scope: `config`

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.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | The automation's id. |

## Body.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | no | The automation's name, shown in the dashboard and on its runs. 1 to 80 characters. |
| `description` | `string` | no | A note for you; Koidog does not use it. At most 500 characters. |
| `launch` | `object` | no | 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. |
| `launch.projectId` | `string` | yes | The project the crew works on. At least 5 characters. |
| `launch.goal` | `string` | yes | What the crew should do. At least 1 character. |
| `launch.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. |
| `launch.requestedSize` | `1–100 \| "auto"` | yes | Requested workers. `auto` lets a managed crew's plan decide. |
| `launch.tasks` | `array` | no | Direct mode: the jobs. Empty in managed mode, where the manager plans them. Default empty. |
| `launch.tasks[].title` | `string` | yes | A short name for the task, shown on the timeline and the pull request. At least 1 character. |
| `launch.tasks[].instructions` | `string` | yes | What the agent should do: the whole brief it is given for this task. At least 1 character. |
| `launch.tasks[].role` | `enum` | no | The kind of agent that does it. One of `manager`, `builder`, `tester`, `reviewer`, `researcher`, `integrator`. Default `builder`. |
| `launch.tasks[].requires` | `object` | no | What the machine must have to run it. Left out, any machine the crew may use. Default `{"tools":[]}`. |
| `launch.tasks[].requires.os` | `enum` | no | Only machines with this operating system. One of `macos`, `linux`. |
| `launch.tasks[].requires.xcode` | `boolean` | no | Only machines with Xcode installed. |
| `launch.tasks[].requires.tools` | `array` | no | Command names the machine must have (as the node reports them), such as `xcodebuild` or `docker`. Default empty. |
| `launch.repeatGoal` | `boolean` | no | Direct mode shortcut: run the goal itself as N identical independent jobs. Default `false`. |
| `launch.profiles` | `object` | yes | Connection ids per role: `builder` (required), and `manager` and `reviewer` when used. |
| `launch.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. |
| `launch.profiles.builder` | `string` | yes | The connection id the builders use. At least 5 characters. |
| `launch.profiles.reviewer` | `string` | no | The connection id the reviewer uses (managed crews). At least 5 characters. |
| `launch.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. |
| `launch.models.manager` | `object` | no | A model picked for a role: which model on the role's connection, with which options. |
| `launch.models.manager.model` | `string` | yes | A model id on the role's connection, as `GET /connections/{id}/models` lists it. At least 1 character. |
| `launch.models.manager.options` | `object` | no | Per-run settings chosen alongside a model. Unset means the harness's own default. Default `{}`. |
| `launch.models.builder` | `object` | no | A model picked for a role: which model on the role's connection, with which options. |
| `launch.models.builder.model` | `string` | yes | A model id on the role's connection, as `GET /connections/{id}/models` lists it. At least 1 character. |
| `launch.models.builder.options` | `object` | no | Per-run settings chosen alongside a model. Unset means the harness's own default. Default `{}`. |
| `launch.models.reviewer` | `object` | no | A model picked for a role: which model on the role's connection, with which options. |
| `launch.models.reviewer.model` | `string` | yes | A model id on the role's connection, as `GET /connections/{id}/models` lists it. At least 1 character. |
| `launch.models.reviewer.options` | `object` | no | Per-run settings chosen alongside a model. Unset means the harness's own default. Default `{}`. |
| `launch.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. |
| `launch.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`. |
| `launch.placement.pinnedNodeId` | `string` | no | Run every agent on this one machine (a machine id). No cloud worker is used. At least 5 characters. |
| `launch.placement.deniedNodeIds` | `array` | no | Machine ids the crew may not use. Default empty. |
| `launch.placement.allowCloud` | `boolean` | no | The crew may start cloud VMs, within its `limits`. Default `true`. |
| `launch.placement.allowLocal` | `boolean` | no | The crew may use your paired machines. Default `true`. |
| `launch.limits` | `object` | yes | `budgetUsd` and `maxVms` are hard caps on cloud compute for this crew; `timeoutMinutes` is its time limit. |
| `launch.limits.budgetUsd` | `number` | yes | Hard cap on cloud compute spend for this crew, in dollars. ≥ 0. |
| `launch.limits.maxVms` | `0–100` | yes | The most cloud VMs this crew may have open at once. 0 starts none. |
| `launch.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. |
| `launch.limits.maxRetries` | `0–5` | no | How many times a failed agent is run again before its task fails. Default `1`. |
| `launch.limits.review` | `object` | no | Review, re-plan and reviewer bounds. Absent: each bound takes the default shown below. |
| `launch.limits.review.managerReview` | `boolean` | no | Managed crews: the manager reviews the merged, checked result before anything is delivered. Default `true`. |
| `launch.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`. |
| `launch.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`. |
| `launch.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`. |
| `launch.limits.review.maxAddedTasks` | `0–20` | no | Tasks the crew may add after its first plan, by review, re-plan and reviewer together. Default `5`. |
| `launch.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. |
| `launch.limits.review.planRevisions` | `0–10` | no | With planApproval: how many times the founder may send the plan back for changes. Absent: 3. |
| `launch.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. |
| `launch.preset` | `string` | no | A name kept with the crew. The server stores it and does nothing else with it. |
| `schedule` | `object` | no | 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. |
| `schedule.kind` | `enum` | yes | `cron` or `interval`. |
| `schedule.cron` | `string` | no | 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`. |
| `schedule.timeZone` | `string` | no | The IANA time zone the cron is read in, such as `Europe/Berlin`. 1 to 64 characters. Default `UTC`. With `kind` `cron`. |
| `schedule.everyMinutes` | `5–10080` | no | Start every so many minutes, counted from when it was saved. With `kind` `interval`. |
| `trigger` | `object` | no | 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. |
| `trigger.sender` | `enum` | yes | `koidog`: your own program, with the trigger secret. `github`: a GitHub webhook. |
| `trigger.events` | `array` | no | The GitHub events that start it; anything else answers `202` with `ignored`. 1 to 20 items. With `sender` `github`. |
| `trigger.events[].event` | `string` | yes | A GitHub event name, as sent in `X-GitHub-Event` (`issues`, `pull_request`, `push`, ...). 1 to 100 characters. Matches `^[\w.-]+$`. |
| `trigger.events[].actions` | `array` | no | Only these `action` values of the event. Empty: every action. At most 20 items. Default empty. |
| `trigger.labels` | `array` | no | 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`. |
| `trigger.branches` | `array` | no | Only for these branches: a push's branch, or a pull request's base branch. At most 20 items. Default empty. With `sender` `github`. |
| `inputs` | `object` | no | `{{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`. |
| `guards` | `object` | no | Only the fields given change; a field left out keeps its value (no default is filled in). |
| `guards.maxRunsPerDay` | `1–48` | no | Launch attempts (launched, refused or failed) in any 24 hours. |
| `guards.overlap` | `enum` | no | While a crew this automation launched is still active: `skip` the new start, or keep one start `queue_one` until it ends. |
| `guards.disableAfterFailures` | `1–20` | no | Switched off after this many refused or failed launches in a row. |
| `guards.missedWindowMinutes` | `0–1440` | no | After a restart, a run time missed by less than this runs once; an older one is recorded as missed. |
| `guards.maxInputChars` | `1–8000` | no | 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`.

## Request.

```sh
curl -X PATCH "https://app.koi.dog/api/v1/automations/$ID" \
    -H "Authorization: Bearer $KOIDOG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
```

```js
const res = await fetch(`https://app.koi.dog/api/v1/automations/${process.env.ID}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.KOIDOG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
console.log(await res.json());
```

```python
import os

import requests

r = requests.patch(
    f"https://app.koi.dog/api/v1/automations/{os.environ['ID']}",
    headers={
        "Authorization": f"Bearer {os.environ['KOIDOG_API_KEY']}",
    },
    json={},
)
r.raise_for_status()
print(r.json())
```

## Response example.

```json
{
  "id": "string",
  "name": "string",
  "description": "string",
  "projectId": "string",
  "kind": "schedule",
  "state": "active",
  "disabledReason": "string",
  "disabledAt": "string",
  "launch": {
    "projectId": "string",
    "goal": "string",
    "mode": "direct",
    "requestedSize": 0,
    "tasks": [],
    "repeatGoal": false,
    …
  },
  "schedule": {
  },
  "trigger": {
  },
  "inputs": { … },
  "guards": {
    "maxRunsPerDay": 0,
    "overlap": "skip",
    "disableAfterFailures": 0,
    "missedWindowMinutes": 0,
    "maxInputChars": 0
  },
  "nextRunAt": "string",
  …
}
```
