Beta

Create an automation

Last updated Nov 19, 2026View as MarkdownAgent setup / MCP
POST
/v1/automations

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.

Authorization

headerAuthorizationBearer <token>

A signed-in SMB user's access token. Workspace-scoped operations also require SMB-Workspace-Id.

Header Parameters

SMB-Workspace-Id*string

Workspace where this operation runs. Required for user tokens and Workspace API keys.

Formatuuid
Idempotency-Key*string
Length8 <= length <= 200

Request Body

application/json
  1. body
name*string
Length1 <= length <= 120
instruction?string

What SMB should do each time it runs, in plain words.

Length1 <= length <= 4000
action?||

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*||||||

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<>

Event must match ALL (max 10): {field, is|is_not|in|changed}. e.g. [{"field":"changes.status.to","is":"done"}]

Itemsitems <= 10
room_id?string

Its Room: for an event, only events here.

Match^rom_[0-7][0-9A-HJKMNP-TV-Z]{25}$
business_id?string

For an event, only events about this business.

Match^biz_[0-7][0-9A-HJKMNP-TV-Z]{25}$
notify?Notify

When to tell you: when there's something to report (default), every run, only failures, or never.

Value in"when_reporting""every_run""failures""never"

Response Body

The resource was created.

application/json
  1. response
data*
request_id*string
curl -X POST 'https://example.com/v1/automations' \  -H 'SMB-Workspace-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Idempotency-Key: stringst' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "trigger": {    "kind": "schedule",    "every": "minutes",    "minutes": 5,    "timezone": "string"  }}'
{  "data": {    "id": "string",    "name": "string",    "action": {      "property1": null,      "property2": null    },    "trigger": {      "property1": null,      "property2": null    },    "where": [      {        "property1": null,        "property2": null      }    ],    "room_id": "string",    "business_id": "string",    "notify": "string",    "status": "active",    "attention_reason": "failing",    "next_run_at": "string",    "last_run_at": "string",    "latest_run_at": "string",    "last_run_status": "queued",    "runs_as": {      "type": "person",      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",      "name": "string"    },    "created_at": "string",    "updated_at": "string"  },  "request_id": "string"}