## Create an automation (desk:admin, or a maintainer of the space)

`POST /api/desk/v1/automations`

Module: Desk · operationId: `createDeskAutomation` · Tag: Automation · Auth: access token (`Authorization: Bearer <accessToken>`)

Scope `tenant`: `desk:admin`. Scope `space:<id>`: `desk:admin` or a maintainer of the space – the same people who manage the flows scoped to the space; others get 403. An automation is a definition in the flow language (YAML, the format of flows; ADR 0044) that may use desk's ticket events as triggers (`trigger.data` is the event's payload, see `x-flows-events`), a manual trigger (the ticket's „Aktionen“, `GET /items/{ref}/actions`; `trigger.data` is the ticket's event payload, and a `filter` on the trigger says on which tickets the action is offered), the nodes `if`, `switch`, `set`, `end`, `mail` and the actions `desk.item.update`, `desk.item.transition`, `desk.item.create`, `desk.entry.add`, `desk.link.add`, `desk.item.assign`, `desk.item.unassign`, `desk.item.add_label`, `desk.item.remove_label`, `desk.item.set_due`, `desk.item.set_follow_up`, `desk.item.comment_linked` and `desk.item.ai_suggest`. It runs immediately, in the transaction of the ticket change that triggered it – the tenant's automations before the space's, each scope in position order – as an internal writer named after the automation (author kind `rule`, actor kind `automation`; customers see the mailbox, never its name) and through the normal ticket rules (workflow transitions, required fields, SLA, history, outbox). **Scope rule:** an automation of a space acts only on tickets of that space – another space's ticket, another tenant's or an unknown one fails the action with `out_of_scope`; `desk.item.create` creates only in the space, `desk.item.comment_linked` leaves linked tickets of other spaces out. Tenant-wide automations act on every ticket of the tenant. The `mail` node sends the tenant's own text through comms (`tenant.message`, the tenant's default channel or `channel:<id>`); a confidential ticket reaches only the people on it, and a requester gets a mail only about a ticket they are on and can see – other recipients are dropped. Without `yaml` the automation starts from a skeleton named `name`; key and name come from the definition, the key is unique per scope (409 `key_taken`). A definition that cannot be read is 422 `invalid_definition` (`details.diagnostics`); one with errors is stored as a draft (`valid: false`) and cannot be enabled. Everything only a flow in the background can run (wait, human tasks, schedules, other modules' actions, …) is the finding `needs_durable`. An action the ticket rules refuse fails the run: its changes are rolled back and the failure is in the log (`GET /automations/{id}/runs`), the triggering change is kept – unless the automation is `blocking`, then the change is refused with 422 `automation_blocked` (only requests on this API; changes from mail, feeds, timers and the customer portal are never refused). A trigger ignores changes made by automations and the AI unless it says `includeAutomated: true`; then automations start each other at most 4 levels deep, each at most once per ticket per change, at most 20 per event. Nothing starts for the tombstone of a converted ticket.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |

### Request body

`application/json` (required)

- `blocking` (boolean): A failure refuses the triggering change (422 `automation_blocked`) (default `false`)
- `enabled` (boolean): Needs a definition without errors (default `false`)
- `name` (string): Without `yaml`: the name of the new automation (its key is derived from it) (max length 200)
- `yaml` (string): The definition (YAML of the flow language, at most 256 KiB); key and name are read from it

Example:

```json
{
  "blocking": false,
  "enabled": true,
  "yaml": "schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\"vip\" in trigger.data.labels \u0026\u0026 trigger.data.priority in [\"niedrig\", \"normal\"]' }\nnodes:\n  hochstufen:\n    kind: action\n    name: Priorität hoch\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\nedges:\n  - label -\u003e hochstufen\n"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 201 answer:

- `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
- `createdAt` (string (date-time), required): When the automation was created
- `createdBy` (string, required): E-mail of who created it
- `description` (string, required): The description of the definition
- `enabled` (boolean, required): Only an enabled automation with a valid definition runs
- `events` (array of string, required): The event types its triggers listen to
- `id` (string (uuid), required): Id of the automation
- `key` (string, required): The key of the definition, unique per scope
- `manual` (boolean, required): Whether the definition has a manual trigger
- `name` (string, required): The name of the definition (the actor name of the automation's changes)
- `position` (integer, required): Automations that listen to the same event run in position order
- `scope` (string, required): What the automation belongs to: `tenant` or `space:<space id>`
- `updatedAt` (string (date-time), required): When the automation was last changed
- `updatedBy` (string, required): E-mail of who changed it last
- `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
- `version` (integer, required): Name it when changing or deleting the automation
- `yaml` (string, required): The definition (YAML of the flow language)
- `lastRun` (AutomationRun): One execution of an automation in its log.
  - `automationId` (string (uuid), required): Automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration of the run in milliseconds
  - `id` (string (uuid), required): Id of the run
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): event: started by an event; manual: started by a person on a ticket (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Why the run failed (only on failure)
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id

Example 201 answer:

```json
{
  "blocking": false,
  "createdAt": "2026-10-05T09:00:00Z",
  "createdBy": "elias.gruber@muster-it.example",
  "description": "Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.",
  "enabled": true,
  "events": [
    "desk.item.created"
  ],
  "id": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
  "key": "kritische-stoerung-1st-level",
  "lastRun": {
    "actorKind": "person",
    "automationId": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
    "createdAt": "2026-11-17T12:05:01Z",
    "depth": 1,
    "durationMs": 21,
    "event": "desk.item.created",
    "id": "9e6f7a8b-0c1d-4e2f-9a4b-6c7d8e9f0a01",
    "outcome": "succeeded",
    "startedBy": "elias.gruber@muster-it.example",
    "steps": 1,
    "subject": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c02",
    "triggerKind": "event",
    "version": 1
  },
  "manual": false,
  "name": "Kritische Störung an den Service Desk",
  "position": 1,
  "scope": "tenant",
  "updatedAt": "2026-10-05T09:00:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "valid": true,
  "version": 1,
  "yaml": "schemaVersion: 1\nkey: kritische-stoerung-1st-level\nname: Kritische Störung an den Service Desk\ndescription: Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.\ntriggers:\n  - { id: neu, kind: event, event: desk.item.created, filter: 'trigger.data.typeKey == \"stoerung\" \u0026\u0026 trigger.data.priority == \"kritisch\"' }\nnodes:\n  zuweisen:\n    kind: action\n    name: Team Service Desk hinzufügen\n    action: desk.item.assign\n    params: { ref: \"{{ trigger.data.itemId }}\", team: first-level, teamRole: collaborating }\nedges:\n  - neu -\u003e zuweisen\n"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/automations?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"blocking":false,"enabled":true,"yaml":"schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\''\"vip\" in trigger.data.labels \u0026\u0026 trigger.data.priority in [\"niedrig\", \"normal\"]'\'' }\nnodes:\n  hochstufen:\n    kind: action\n    name: Priorität hoch\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\nedges:\n  - label -\u003e hochstufen\n"}'
```
