ConnectCloud Developers

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

{
  "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 (422 automation_blocked); false (default): the failure is logged and the change is kept
  • createdAt (string (date-time), required): When it 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): Automation id
  • key (string, required): The key of the definition, unique per project
  • 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: project:<project id>
  • updatedAt (string (date-time), required): When it was changed last
  • 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): The 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 in milliseconds
    • id (string (uuid), required): Run id
    • 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): What started it: an event or a manual start (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): Failed runs: the error text
    • 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:

{
  "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"}'

View as Markdown · Interactive reference · OpenAPI