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 (422automation_blocked) (defaultfalse)enabled(boolean): Needs a definition without errors (defaultfalse)name(string): Withoutyaml: 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:
{
"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 (422automation_blocked); false (default): the failure is logged and the change is keptcreatedAt(string (date-time), required): When the automation was createdcreatedBy(string, required): E-mail of who created itdescription(string, required): The description of the definitionenabled(boolean, required): Only an enabled automation with a valid definition runsevents(array of string, required): The event types its triggers listen toid(string (uuid), required): Id of the automationkey(string, required): The key of the definition, unique per scopemanual(boolean, required): Whether the definition has a manual triggername(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 orderscope(string, required): What the automation belongs to:tenantorspace:<space id>updatedAt(string (date-time), required): When the automation was last changedupdatedBy(string, required): E-mail of who changed it lastvalid(boolean, required): The definition had no error when it was saved; a draft with errors (false) cannot be enabledversion(integer, required): Name it when changing or deleting the automationyaml(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 rancreatedAt(string (date-time), required): When the run happeneddepth(integer, required): 1 when a person's (or another service's) change started it, n when automations started each otherdurationMs(integer, required): Duration of the run in millisecondsid(string (uuid), required): Id of the runoutcome(string, required): skipped: a limit stopped it (too many automations for one event) (one ofsucceeded,failed,skipped)steps(integer, required): The number of nodes that rantriggerKind(string, required): event: started by an event; manual: started by a person on a ticket (one ofevent,manual)version(integer, required): The version of the automation that ranactorKind(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_failederrorMessage(string): Why the run failed (only on failure)event(string): The event type that started itnode(string): The id of the node that failedstartedBy(string): The person or actor behind the triggering changesubject(string): What the event was about: the item's id
Example 201 answer:
{
"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
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"}'