# 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).
> https://koi.dog/docs/api/automations/create-automation/

`POST /api/v1/automations` · Scope: `config`

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.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | `string` | no | Makes a retry safe: the same key with the same request returns the first answer and does nothing else. |

## Body.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | 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. Default empty. |
| `launch` | `object` | yes | 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`. Default `{}`. |
| `guards` | `object` | no | 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}`. |
| `guards.maxRunsPerDay` | `1–48` | no | Launch attempts (launched, refused or failed) in any 24 hours. Default `4`. |
| `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. Default `skip`. |
| `guards.disableAfterFailures` | `1–20` | no | Switched off after this many refused or failed launches in a row. Default `3`. |
| `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. Default `60`. |
| `guards.maxInputChars` | `1–8000` | no | Each placeholder's value is cut to this many characters. Default `2000`. |
| `enabled` | `boolean` | no | 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`.

## Request.

```sh
curl -X POST https://app.koi.dog/api/v1/automations \
    -H "Authorization: Bearer $KOIDOG_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Nightly dependency check",
      "launch": {
        "projectId": "prj_1m7h5x2kdq8wv3tfa7c",
        "goal": "Update outdated dependencies and run the tests",
        "mode": "direct",
        "requestedSize": 1,
        "tasks": [
          {
            "title": "Dependencies",
            "instructions": "Update outdated dependencies, run the tests and fix what breaks."
          }
        ],
        "profiles": {
          "builder": "con_1m7h5y0nb4rkz9pqe2h"
        },
        "placement": {
          "allowCloud": false
        },
        "limits": {
          "budgetUsd": 0,
          "maxVms": 0,
          "timeoutMinutes": 60
        }
      },
      "schedule": {
        "kind": "cron",
        "cron": "0 2 * * 1-5",
        "timeZone": "Europe/Berlin"
      }
    }'
```

```js
const res = await fetch("https://app.koi.dog/api/v1/automations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOIDOG_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Nightly dependency check",
    launch: {
      projectId: "prj_1m7h5x2kdq8wv3tfa7c",
      goal: "Update outdated dependencies and run the tests",
      mode: "direct",
      requestedSize: 1,
      tasks: [
        {
          title: "Dependencies",
          instructions: "Update outdated dependencies, run the tests and fix what breaks.",
        },
      ],
      profiles: {
        builder: "con_1m7h5y0nb4rkz9pqe2h",
      },
      placement: {
        allowCloud: false,
      },
      limits: {
        budgetUsd: 0,
        maxVms: 0,
        timeoutMinutes: 60,
      },
    },
    schedule: {
      kind: "cron",
      cron: "0 2 * * 1-5",
      timeZone: "Europe/Berlin",
    },
  }),
});
console.log(await res.json());
```

```python
import os
import uuid

import requests

r = requests.post(
    "https://app.koi.dog/api/v1/automations",
    headers={
        "Authorization": f"Bearer {os.environ['KOIDOG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Nightly dependency check",
        "launch": {
            "projectId": "prj_1m7h5x2kdq8wv3tfa7c",
            "goal": "Update outdated dependencies and run the tests",
            "mode": "direct",
            "requestedSize": 1,
            "tasks": [
                {
                    "title": "Dependencies",
                    "instructions": "Update outdated dependencies, run the tests and fix what breaks.",
                },
            ],
            "profiles": {
                "builder": "con_1m7h5y0nb4rkz9pqe2h",
            },
            "placement": {
                "allowCloud": False,
            },
            "limits": {
                "budgetUsd": 0,
                "maxVms": 0,
                "timeoutMinutes": 60,
            },
        },
        "schedule": {
            "kind": "cron",
            "cron": "0 2 * * 1-5",
            "timeZone": "Europe/Berlin",
        },
    },
)
r.raise_for_status()
print(r.json())
```

## Response example.

```json
{
  "automation": {
    "id": "string",
    "name": "string",
    "description": "string",
    "projectId": "string",
    "kind": "schedule",
    "state": "active",
    …
  },
  "secret": "string"
}
```
