Create an automation of a project (tenant:forge:write and maintainer, or tenant:forge:admin)
POST /api/forge/v1/projects/{key}/automations
Module: Forge · operationId: createForgeAutomation · Tag: Automations · Auth: access token (Authorization: Bearer <accessToken>)
Requires tenant:forge:admin, or tenant:forge:write and project role maintainer or admin; an archived project is 409 project_archived. An automation is a definition in the flow language (ADR 0044, the YAML of flows): triggers that listen to forge's item events (GET …/automations/catalog lists them with their payload, which is trigger.data), an optional filter, and nodes – if, switch, set, end, mail and the actions forge.item.transition, forge.item.add_label, forge.item.remove_label, forge.item.assign and forge.comment.add. It runs immediately, in the transaction of the item change that triggered it, as actor kind automation (ref automation:<id>, name = the automation's name) and through the normal item rules (workflow transitions, scoped labels, auto-watch); member roles are not checked, and it changes only items of its own project (another project's key fails the action with out_of_scope). Without yaml the automation starts from a skeleton named name; key and name come from the definition, the key is unique per project (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 (422 invalid_definition). Everything only a flow in the background can run (wait, human tasks, schedules, other modules' actions, …) is the finding needs_durable. An action the item rules refuse (e.g. a transition the workflow does not allow) fails the run: its changes are rolled back and the failure is in the log (GET …/{id}/runs), the triggering change is kept – unless the automation is blocking, then the change is refused with 422 automation_blocked (changes made by scm or the system are never refused). A trigger ignores changes made by automations unless it says includeAutomated: true; then automations start each other at most 4 levels deep, each at most once per item per change, at most 20 per event.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key |
path | string | yes | Project key (e.g. APP) |
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: neue-fehler-label-bug\nname: Neue Fehler bekommen das Label bug\ndescription: Setzt auf jedem neuen Element vom Typ Fehler das Label bug.\ntriggers:\n - { id: neu, kind: event, event: forge.item.created, filter: 'trigger.data.typeKey == \"fehler\"' }\nnodes:\n etikettieren:\n kind: action\n name: Label setzen\n action: forge.item.add_label\n params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", label: bug }\nedges:\n - neu -\u003e etikettieren\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 it 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): Automation idkey(string, required): The key of the definition, unique per projectmanual(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:project:<project id>updatedAt(string (date-time), required): When it was changed lastupdatedBy(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): The 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 in millisecondsid(string (uuid), required): Run idoutcome(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): What started it: an event or a manual start (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): Failed runs: the error textevent(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-09-23T09:00:00Z",
"createdBy": "emma.maier@muster-it.example",
"description": "Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.",
"enabled": true,
"events": [
"forge.item.children_done"
],
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
"key": "unteraufgaben-erledigt",
"lastRun": {
"actorKind": "person",
"automationId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
"createdAt": "2026-10-28T15:00:02Z",
"depth": 1,
"durationMs": 14,
"event": "forge.item.children_done",
"id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f01",
"outcome": "succeeded",
"startedBy": "marie.wagner@muster-it.example",
"steps": 1,
"subject": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
"triggerKind": "event",
"version": 2
},
"manual": false,
"name": "Unteraufgaben erledigt → Eltern erledigt",
"position": 0,
"scope": "project:0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
"updatedAt": "2026-09-23T09:30:00Z",
"updatedBy": "emma.maier@muster-it.example",
"valid": true,
"version": 2,
"yaml": "schemaVersion: 1\nkey: unteraufgaben-erledigt\nname: \"Unteraufgaben erledigt → Eltern erledigt\"\ndescription: Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.\ntriggers:\n - { id: kinder_erledigt, kind: event, event: forge.item.children_done, includeAutomated: true }\nnodes:\n erledigen:\n kind: action\n name: Auf Erledigt setzen\n action: forge.item.transition\n params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", category: done }\nedges:\n - kinder_erledigt -\u003e erledigen\n"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"blocking":false,"enabled":true,"yaml":"schemaVersion: 1\nkey: neue-fehler-label-bug\nname: Neue Fehler bekommen das Label bug\ndescription: Setzt auf jedem neuen Element vom Typ Fehler das Label bug.\ntriggers:\n - { id: neu, kind: event, event: forge.item.created, filter: '\''trigger.data.typeKey == \"fehler\"'\'' }\nnodes:\n etikettieren:\n kind: action\n name: Label setzen\n action: forge.item.add_label\n params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", label: bug }\nedges:\n - neu -\u003e etikettieren\n"}'