# Create an automation (/docs/api-reference/create_automation)

`POST /v1/automations` · operation `create_automation`

Has SMB do something on its own, as you: on a schedule ("every Monday at 9am"), when something happens (an event like file.viewed in a Room), or only when run by hand. For an event, where narrows it: "when a task is done" is task.updated where changes.status.to is done; "when a file is added" is file.created. list_event_types shows each kind's changes. instruction is what SMB should do each time, in plain words; each run is an SMB chat, and anything that sends or changes something still asks you first. (Or action: one listed operation run as you, or a message to one of your webhooks, e.g. "every morning, send my CRM this Room's changes".) Confirm the details with the person before creating one.

**Sign-in:** a signed-in person's access token (`Authorization: Bearer …`), which AI apps get through MCP sign-in; or a Workspace API key in the `X-SMB-API-Key` header.

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `SMB-Workspace-Id` | string (uuid) | yes | Workspace where this operation runs. Required for user tokens and Workspace API keys. |
| `Idempotency-Key` | string | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `instruction` | string | no | What SMB should do each time it runs, in plain words. |
| `action` | object or object or object | no | What it does: ask SMB's agent (kind agent, with an instruction), run one listed operation as you (kind operation), or send a signed automation.run message to one of your webhooks (kind webhook). Give this or instruction. |
| `trigger` | object or object or object or object or object or object or object | yes | When it runs: a schedule (every N hours, or a day, weekdays, week or month at a time, in a time zone; every 5, 10, 15 or 30 minutes for an operation or webhook), an event (types from list_event_types; set where, room_id or business_id to narrow it), or manual (only when run by hand). |
| `where` | array of object | no | Event must match ALL (max 10): {field, is\|is_not\|in\|changed}. e.g. [{"field":"changes.status.to","is":"done"}] |
| `where[].field` | string | yes | changes.status.to, data.x, subject.id, about |
| `where[].is` | any | no |  |
| `where[].is_not` | any | no |  |
| `where[].in` | array of any | no |  |
| `where[].changed` | any | no |  |
| `room_id` | string | no | Its Room: for an event, only events here. |
| `business_id` | string | no | For an event, only events about this business. |
| `notify` | one of `when_reporting`, `every_run`, `failures`, `never` | no | When to tell you: when there's something to report (default), every run, only failures, or never. |

### Response

**201** The resource was created.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.id` | string | yes |  |
| `data.name` | string | yes |  |
| `data.action` | object | yes |  |
| `data.trigger` | object | yes |  |
| `data.where` | array of object | no | The conditions every event must match; empty for none. |
| `data.room_id` | string or null | yes |  |
| `data.business_id` | string or null | yes |  |
| `data.notify` | string | yes |  |
| `data.status` | one of `active`, `paused`, `needs_attention` | yes |  |
| `data.attention_reason` | one of `failing`, `access_lost`, `webhook_gone` or null | yes |  |
| `data.next_run_at` | string or null | yes |  |
| `data.last_run_at` | string or null | yes |  |
| `data.latest_run_at` | string or null | no |  |
| `data.last_run_status` | one of `queued`, `starting`, `running`, `waiting_approval`, `succeeded`, `nothing_new`, `failed`, `skipped` or null | no |  |
| `data.runs_as` | object or object | yes | Who it runs as: a person, or a platform service account. |
| `data.created_at` | string | yes |  |
| `data.updated_at` | string | yes |  |
| `request_id` | string | yes |  |

### Errors

- `400` The request is invalid.
- `401` Authentication is required.
- `403` The caller is not authorized.
- `404` The resource was not found.
- `409` The resource revision or idempotency input conflicts.
- `413` The request body is too large.
- `415` The request must be JSON.
- `422` Required evidence is missing.
- `429` Rate limit reached; honor Retry-After.
- `500` The request could not be completed.
- `502` A dependency returned an invalid response.
- `503` The service is temporarily unavailable.

### Example

```bash
curl --request POST "https://api.smb.co/v1/automations" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "SMB-Workspace-Id: $WORKSPACE_ID" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"…","trigger":"…"}'
```