> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worksong.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Automations reference

> Every trigger, condition and action you can use in a Work automation, with the settings each one needs.

An automation lives on one board. It has a **trigger**, optional **conditions** and one or more **actions**. The live list is always available from `GET /v1/automation-catalog`, or from the MCP tool `boardy_get_automation_catalog`. Use it as the source of truth for the settings of each item.

Each automation can be turned on and off. Its **runs** are listed with the result of each one (`GET /v1/boards/{boardId}/automation-runs`).

## Triggers

| Trigger | Fires when | Settings |
| - | - | - |
| `ItemCreated` | An item is created on the board | none |
| `ItemUpdated` | Any cell of an item changes | none |
| `StatusChanged` | The watched Status column changes | `columnId` |
| `DateArrives` | The date in the watched Date column arrives | `columnId` |
| `Scheduled` | On a recurring schedule | `schedule`, for example `every-day-09:00` |
| `MemberMentioned` | A comment @-mentions the member (not when that member comments) | `memberId` |
| `MemberAssigned` | A Person cell is newly set to the member | `memberId`, optional `columnId` |

Scheduled and date triggers are started by a timer. The others run when the change happens.

## Conditions

A condition compares a cell with a value. The operators are `Equals`, `NotEquals`, `Contains`, `IsEmpty`, `IsNotEmpty`, `GreaterThan` and `LessThan`.

## Actions

| Action | What it does | Settings |
| - | - | - |
| `SetColumnValue` | Sets a cell of the item | `columnId`, `value` |
| `AssignMember` | Puts a member in a Person cell | `columnId`, `memberId` |
| `NotifyMember` | Sends a notification to a member | `memberId` |
| `NotifyManager` | Notifies the member in the item's manager (Person) column | `managerColumnId` |
| `CreateItem` | Creates an item on another board, optionally copying cells | `boardId` |
| `InvokeAgent` | Hands the item to an Agent, which runs with its own authority | `agentMemberId`, `columnId` |
| `ProposeSendEmail` | Proposes an email about the item | `subject`, `body`, and `to` or `toColumnId` |
| `ProposeCreateCalendarEvent` | Proposes a calendar event about the item | `title`, optional `startColumnId`, `durationMinutes` |
| `CallWebhook` | Sends a JSON body to a webhook integration | `integrationConnectionId`, `bodyTemplate` |

`CallWebhook` fills these tokens in `bodyTemplate`: `{{item.name}}`, `{{item.id}}`, `{{board.name}}` and `{{cell:<columnId>}}`. Plain text is sent as `{"text": "..."}`.

The two `Propose` actions only make a request. If a matching [gate](https://docs.worksong.ai/work/people-and-permissions.md#gates) exists, a person must approve it before anything is sent. If no gate matches, the action runs at once.

## Create one through the API

Send `POST /v1/boards/{boardId}/automations` with:

* `name`
* `trigger`: `{ "type": "StatusChanged", "columnId": "<status column id>" }`
* `conditions`: a list, which may be empty
* `actions`: a list of `{ "type": ..., "config": ... }`

The `config` of an action is a JSON string. Turn the automation off with `PATCH /v1/automations/{id}/enabled`. A formula column does not start an automation.

<sub>Source: `worksong-ai/worksong:services/work/src/Boardy.Automation@9f0684f`, `worksong-ai/worksong:services/work/src/Boardy.Api/Program.cs@9f0684f`. Docs version: Worksong 2.0 with Work 1.2.</sub>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.