ConnectCloud Developers

Change an automation (tenant:forge:write and maintainer, or tenant:forge:admin)

PATCH /api/forge/v1/projects/{key}/automations/{id}

Module: Forge · operationId: patchForgeAutomation · 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. Changes what is set: the definition (yaml; key and name follow it), enabled, blocking. version is required (409 version_conflict). Enabling needs a definition without errors (422 invalid_definition with details.diagnostics); a definition saved with errors switches the automation off. A key another automation of the project has is 409 key_taken.

Parameters

Name In Type Required Description
key path string yes Project key (e.g. APP)
id path string (uuid) yes

Request body

application/json (required)

  • version (integer, required): The version the caller read
  • blocking (boolean): A failure refuses the triggering change (422 automation_blocked)
  • enabled (boolean): Switch the automation on or off (on needs a definition without errors)
  • yaml (string): The new definition

Example:

{
  "enabled": false,
  "version": 2
}

Responses

  • 200 Changed (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 200 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 200 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 PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"enabled":false,"version":2}'

View as Markdown · Interactive reference · OpenAPI