ConnectCloud Developers

Read an automation of a project (tenant:forge:read)

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

Module: Forge · operationId: getForgeAutomation · Tag: Automations · Auth: access token (Authorization: Bearer <accessToken>)

Requires tenant:forge:read and a project the caller sees. An automation of another project or tenant is 404.

Parameters

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

Responses

  • 200 The automation (application/json)
  • 404 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 GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI