Executions

Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.

GET `/api/v1/executions`

List my executions

Newest first, paginated by cursor (nextCursor, null at the end). Filters by workflow, mailbox, status and simulation. The mailbox filter is intersected with the mailboxes of the member: another member’s mailbox yields an empty page.

Access — Member session or API key with scope executions:read.

Parameters

Name	In	Type	Required
`workflowId`	query	`string`	no
`mailboxId`	query	`string`	no
`status`	query	`"queued" \| "running" \| "waiting" \| "succeeded" \| "failed" \| "cancelled"`	no
`simulated`	query	`string`	no
`q`	query	`string`	no
`cursor`	query	`string`	no
`limit`	query	`integer`	no

Responses

200 — A page of executions.

Field	Type	Required
`executions`	`object[]`	yes
`nextCursor`	`string \| null`	yes

JSON Schema

json

{
  "type": "object",
  "properties": {
    "executions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "workflowId": { "type": "string" },
          "workflowVersionId": { "type": "string" },
          "mailboxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "messageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "waiting",
              "succeeded",
              "failed",
              "cancelled"
            ]
          },
          "simulated": { "type": "boolean" },
          "parentExecutionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "triggerNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "triggerType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "retryOfExecutionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "messageHeadline": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "subject": { "type": "string" },
                  "fromName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
                  "fromEmail": { "type": "string" }
                },
                "required": [ "subject", "fromName", "fromEmail" ],
                "additionalProperties": false
              },
              { "type": "null" }
            ]
          },
          "error": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "code": { "type": "string" },
                  "message": { "type": "string" },
                  "nodeId": { "type": "string" },
                  "kind": { "type": "string", "enum": [ "transient", "permanent" ] },
                  "attempts": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "nodeType": { "type": "string" },
                  "details": {
                    "type": "object",
                    "propertyNames": { "type": "string" },
                    "additionalProperties": {}
                  },
                  "at": { "type": "string" }
                },
                "required": [ "code", "message" ],
                "additionalProperties": false
              },
              { "type": "null" }
            ]
          },
          "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "finishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "createdAt": { "type": "string" }
        },
        "required": [
          "id",
          "workflowId",
          "workflowVersionId",
          "mailboxId",
          "messageId",
          "status",
          "simulated",
          "error",
          "startedAt",
          "finishedAt",
          "createdAt"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
  },
  "required": [ "executions", "nextCursor" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET `/api/v1/executions/{id}`

Read an execution step by step

The execution, its steps with their attempts and data, the attachments it produced, and the workflow name (empty if the workflow was deleted since). An execution of another member is a 404.

Access — Member session or API key with scope executions:read.

Parameters

Name	In	Type	Required
`id`	path	`string`	yes

Responses

200 — The execution.

Field	Type	Required
`id`	`string`	yes
`workflowId`	`string`	yes
`workflowVersionId`	`string`	yes
`mailboxId`	`string \| null`	yes
`messageId`	`string \| null`	yes
`status`	`"queued" \| "running" \| "waiting" \| "succeeded" \| "failed" \| "cancelled"`	yes
`simulated`	`boolean`	yes
`parentExecutionId`	`string \| null`	no
`triggerNodeId`	`string \| null`	no
`triggerType`	`string \| null`	no
`retryOfExecutionId`	`string \| null`	no
`messageHeadline`	`object \| null`	no
`error`	`object \| null`	yes
`startedAt`	`string \| null`	yes
`finishedAt`	`string \| null`	yes
`createdAt`	`string`	yes
`workflowName`	`string`	yes
`triggerData`	`object \| null`	no
`steps`	`object[]`	yes
`attachments`	`object[]`	no

JSON Schema

json

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "workflowId": { "type": "string" },
    "workflowVersionId": { "type": "string" },
    "mailboxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "messageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "status": {
      "type": "string",
      "enum": [ "queued", "running", "waiting", "succeeded", "failed", "cancelled" ]
    },
    "simulated": { "type": "boolean" },
    "parentExecutionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "triggerNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "triggerType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "retryOfExecutionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "messageHeadline": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "subject": { "type": "string" },
            "fromName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
            "fromEmail": { "type": "string" }
          },
          "required": [ "subject", "fromName", "fromEmail" ],
          "additionalProperties": false
        },
        { "type": "null" }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": { "type": "string" },
            "message": { "type": "string" },
            "nodeId": { "type": "string" },
            "kind": { "type": "string", "enum": [ "transient", "permanent" ] },
            "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
            "nodeType": { "type": "string" },
            "details": {
              "type": "object",
              "propertyNames": { "type": "string" },
              "additionalProperties": {}
            },
            "at": { "type": "string" }
          },
          "required": [ "code", "message" ],
          "additionalProperties": false
        },
        { "type": "null" }
      ]
    },
    "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "finishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "createdAt": { "type": "string" },
    "workflowName": { "type": "string" },
    "triggerData": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": { "type": "string" },
          "additionalProperties": {}
        },
        { "type": "null" }
      ]
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "nodeId": { "type": "string" },
          "status": {
            "type": "string",
            "enum": [ "queued", "running", "waiting", "succeeded", "failed", "skipped" ]
          },
          "attempt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "data": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": { "type": "string" },
                "additionalProperties": {}
              },
              { "type": "null" }
            ]
          },
          "dataTruncated": { "type": "boolean" },
          "durationMs": {
            "anyOf": [
              { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
              { "type": "null" }
            ]
          },
          "effects": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "kind": { "type": "string" },
                "description": { "type": "string" },
                "simulated": { "type": "boolean" }
              },
              "required": [ "kind", "description" ],
              "additionalProperties": false
            }
          },
          "llmSkipped": { "type": "boolean" },
          "attempts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "attempt": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "maximum": 9007199254740991
                },
                "at": { "type": "string" },
                "code": { "type": "string" },
                "message": { "type": "string" },
                "kind": { "type": "string", "enum": [ "transient", "permanent" ] },
                "interrupted": { "type": "boolean" },
                "retried": { "type": "boolean" }
              },
              "required": [ "attempt", "at", "code", "message", "kind", "retried" ],
              "additionalProperties": false
            }
          },
          "copiedFrom": { "type": "string" },
          "warnings": { "type": "array", "items": { "type": "string" } },
          "input": {
            "type": "object",
            "propertyNames": { "type": "string" },
            "additionalProperties": {}
          },
          "pinned": { "type": "boolean" },
          "disabled": { "type": "boolean" },
          "loop": {
            "type": "object",
            "properties": {
              "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
              "started": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
              "succeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
              "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
              "concurrency": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "status": {
                "type": "string",
                "enum": [ "running", "done", "failed", "timeout" ]
              },
              "simulatedLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
            },
            "required": [
              "total",
              "started",
              "succeeded",
              "failed",
              "concurrency",
              "status"
            ],
            "additionalProperties": false
          },
          "error": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "code": { "type": "string" },
                  "message": { "type": "string" },
                  "nodeId": { "type": "string" },
                  "kind": { "type": "string", "enum": [ "transient", "permanent" ] },
                  "attempts": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "nodeType": { "type": "string" },
                  "details": {
                    "type": "object",
                    "propertyNames": { "type": "string" },
                    "additionalProperties": {}
                  },
                  "at": { "type": "string" }
                },
                "required": [ "code", "message" ],
                "additionalProperties": false
              },
              { "type": "null" }
            ]
          },
          "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "finishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
        },
        "required": [
          "id",
          "nodeId",
          "status",
          "attempt",
          "output",
          "data",
          "dataTruncated",
          "durationMs",
          "effects",
          "pinned",
          "error",
          "startedAt",
          "finishedAt"
        ],
        "additionalProperties": false
      }
    },
    "attachments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "filename": { "type": "string" },
          "mime": { "type": "string" },
          "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "nodeId": { "type": "string" },
          "integration": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "createdAt": { "type": "string" }
        },
        "required": [
          "position",
          "filename",
          "mime",
          "size",
          "nodeId",
          "integration",
          "createdAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "id",
    "workflowId",
    "workflowVersionId",
    "mailboxId",
    "messageId",
    "status",
    "simulated",
    "error",
    "startedAt",
    "finishedAt",
    "createdAt",
    "workflowName",
    "steps"
  ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — execution.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET `/api/v1/executions/{id}/attachments/{position}`

Download an attachment produced by an execution

The bytes of the attachment at position in the execution, served as attachment with its own content type and an RFC 5987 encoded file name. A purged blob is attachment.unavailable (404).

Access — Member session or API key with scope executions:read.

Parameters

Name	In	Type	Required
`id`	path	`string`	yes
`position`	path	`string`	yes

Responses

200 — The file, as an attachment.

Content type : application/octet-stream

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — execution.not_found, attachment.not_found, attachment.unavailable. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET `/api/v1/executions/{id}/steps/{nodeId}/iterations`

List the iterations of a loop step

The child executions of a flow.loop node, one per item, kept out of the execution list and detail on purpose. The scope is that of the parent execution.

Access — Member session or API key with scope executions:read.

Parameters

Name	In	Type	Required
`id`	path	`string`	yes
`nodeId`	path	`string`	yes

Responses

200 — The iterations.

Field	Type	Required
`nodeId`	`string`	yes
`iterations`	`object[]`	yes

JSON Schema

json

{
  "type": "object",
  "properties": {
    "nodeId": { "type": "string" },
    "iterations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "executionId": { "type": "string" },
          "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "waiting",
              "succeeded",
              "failed",
              "cancelled"
            ]
          },
          "error": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "code": { "type": "string" },
                  "message": { "type": "string" },
                  "nodeId": { "type": "string" },
                  "kind": { "type": "string", "enum": [ "transient", "permanent" ] },
                  "attempts": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "nodeType": { "type": "string" },
                  "details": {
                    "type": "object",
                    "propertyNames": { "type": "string" },
                    "additionalProperties": {}
                  },
                  "at": { "type": "string" }
                },
                "required": [ "code", "message" ],
                "additionalProperties": false
              },
              { "type": "null" }
            ]
          },
          "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "finishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "createdAt": { "type": "string" }
        },
        "required": [
          "executionId",
          "index",
          "status",
          "error",
          "startedAt",
          "finishedAt",
          "createdAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "nodeId", "iterations" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — execution.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

POST `/api/v1/executions/{id}/retry`

Retry a failed execution

Plans a new execution from the trigger data of a failed one. An empty body retries from the start on the published version; from: "failed_step" reuses the successful steps, version: "origin" replays the version that ran. 202: the execution is planned. Recorded in the audit log.

Access — Member session or API key with scope executions:write.

Parameters

Name	In	Type	Required
`id`	path	`string`	yes

Request body (application/json)

Field	Type	Required
`from`	`"start" \| "failed_step"`	no
`version`	`"published" \| "origin"`	no

JSON Schema

json

{
  "type": "object",
  "properties": {
    "from": { "default": "start", "type": "string", "enum": [ "start", "failed_step" ] },
    "version": {
      "default": "published",
      "type": "string",
      "enum": [ "published", "origin" ]
    }
  }
}

Responses

202 — The new execution id.

Field	Type	Required
`executionId`	`string`	yes

JSON Schema

json

{
  "type": "object",
  "properties": { "executionId": { "type": "string" } },
  "required": [ "executionId" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.

Error codes — request.bad_request, execution.not_found, execution.not_retryable, execution.version_unavailable, workflow.invalid_graph. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

Example request

json

{ "from": "failed_step" }

Example response (202)

json

{ "executionId": "0192f1c2-bbbb-7000-8000-000000000008" }

POST `/api/v1/executions/{id}/cancel`

Cancel a running execution

Stops the execution and its children; 200 with the final status. An execution already settled when read is execution.not_cancellable (409).

Access — Member session or API key with scope executions:write.

Parameters

Name	In	Type	Required
`id`	path	`string`	yes

Responses

200 — The final status.

Field	Type	Required
`status`	`"queued" \| "running" \| "waiting" \| "succeeded" \| "failed" \| "cancelled"`	yes

JSON Schema

json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [ "queued", "running", "waiting", "succeeded", "failed", "cancelled" ]
    }
  },
  "required": [ "status" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — execution.not_found, execution.not_cancellable. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

POST `/api/v1/executions/cancel`

Cancel a selection of executions

Cancels up to 200 executions by id, within the scope of the member. The batch never stops on an intruder: an unknown id, or one of another member, is reported as not_found in skipped, an execution already settled as already_settled. 200: the cancellations are done, not planned; hasMore is always false here.

Access — Member session or API key with scope executions:write.

Request body (application/json)

Field	Type	Required
`executionIds`	`string[]`	yes

JSON Schema

json

{
  "type": "object",
  "properties": {
    "executionIds": {
      "minItems": 1,
      "maxItems": 200,
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": [ "executionIds" ]
}

Responses

200 — What was cancelled, and what was skipped.

Field	Type	Required
`executionIds`	`string[]`	yes
`skipped`	`object[]`	yes
`hasMore`	`boolean`	yes

JSON Schema

json

{
  "type": "object",
  "properties": {
    "executionIds": { "type": "array", "items": { "type": "string" } },
    "skipped": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "reason": { "type": "string", "enum": [ "not_found", "already_settled" ] }
        },
        "required": [ "id", "reason" ],
        "additionalProperties": false
      }
    },
    "hasMore": { "type": "boolean" }
  },
  "required": [ "executionIds", "skipped", "hasMore" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.

Error codes — request.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET `/api/v1/executions/waiting`

List the executions currently waiting

Real executions suspended on a wait node, with their wake-up instant and signal key, sorted by deadline and paginated by cursor. signalKey filters by prefix; overdueOnly keeps the late ones.

Access — Member session or API key with scope executions:read.

Parameters

Name	In	Type	Required
`signalKey`	query	`string`	no
`workflowId`	query	`string (uuid)`	no
`overdueOnly`	query	`boolean`	no
`limit`	query	`integer`	no
`cursor`	query	`string`	no

Responses

200 — A page of waiting executions.

Field	Type	Required
`items`	`object[]`	yes
`nextCursor`	`string \| null`	yes

JSON Schema

json

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "executionId": { "type": "string" },
          "stepId": { "type": "string" },
          "nodeId": { "type": "string" },
          "workflowId": { "type": "string" },
          "workflowName": { "type": "string" },
          "wakeAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              { "type": "null" }
            ]
          },
          "signalKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "overdue": { "type": "boolean" },
          "outcomes": { "type": "array", "items": { "type": "string" } },
          "startedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              { "type": "null" }
            ]
          },
          "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
        },
        "required": [
          "executionId",
          "stepId",
          "nodeId",
          "workflowId",
          "workflowName",
          "wakeAt",
          "signalKey",
          "overdue",
          "outcomes",
          "startedAt",
          "subject"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
  },
  "required": [ "items", "nextCursor" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — wait.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

POST `/api/v1/executions/waiting/{stepId}/wake`

Wake a waiting step by hand

Resumes the step through the chosen outcome: done as if the deadline were reached, event as if the awaited event had arrived. The two branches do not do the same thing, so the API never picks one. Recorded in the audit log.

Access — Member session or API key with scope executions:write.

Parameters

Name	In	Type	Required
`stepId`	path	`string`	yes

Request body (application/json)

Field	Type	Required
`outcome`	`"done" \| "event"`	no

JSON Schema

json

{
  "type": "object",
  "properties": {
    "outcome": { "default": "done", "type": "string", "enum": [ "done", "event" ] }
  }
}

Responses

200 — Resumed.

Field	Type	Required
`resumed`	`true`	yes

JSON Schema

json

{
  "type": "object",
  "properties": { "resumed": { "type": "boolean", "const": true } },
  "required": [ "resumed" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — wait.bad_request, wait.step_not_found, wait.step_not_waiting, wait.outcome_not_available, wait.already_settled. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

POST `/api/v1/signals`

Emit a signal

Wakes (resume) or cancels (cancel) every execution waiting on key, instance-wide: a signal is organisational, not scoped to a member. matched counts the waits reached, 0 when nothing listens yet; the signal is kept for a while so a wait installed later still catches it. duplicate says an identical emission was absorbed.

Access — Member session or API key with scope signals:write.

Request body (application/json)

Field	Type	Required
`key`	`string`	yes
`action`	`"resume" \| "cancel"`	no
`payload`	`object`	no

JSON Schema

json

{
  "type": "object",
  "properties": {
    "key": { "type": "string", "minLength": 1, "maxLength": 200 },
    "action": { "default": "resume", "type": "string", "enum": [ "resume", "cancel" ] },
    "payload": {
      "type": "object",
      "propertyNames": { "type": "string" },
      "additionalProperties": {
        "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ]
      }
    }
  },
  "required": [ "key" ]
}

Responses

200 — The signal and what it reached.

Field	Type	Required
`signalId`	`string`	yes
`matched`	`integer`	yes
`duplicate`	`boolean`	yes

JSON Schema

json

{
  "type": "object",
  "properties": {
    "signalId": { "type": "string" },
    "matched": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
    "duplicate": { "type": "boolean" }
  },
  "required": [ "signalId", "matched", "duplicate" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.

Error codes — wait.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

Example request

json

{
  "key": "mandat:PSD-2026-0142",
  "action": "resume",
  "payload": { "signedBy": "client" }
}

Example response (200)

json

{
  "signalId": "0192f1c2-cccc-7000-8000-000000000003",
  "matched": 1,
  "duplicate": false
}

Triggers

AI

Logic

Data

Actions

Account

AI provider

Service

Reference

Executions

GET `/api/v1/executions`

GET `/api/v1/executions/{id}`

GET `/api/v1/executions/{id}/attachments/{position}`

GET `/api/v1/executions/{id}/steps/{nodeId}/iterations`

POST `/api/v1/executions/{id}/retry`

POST `/api/v1/executions/{id}/cancel`

POST `/api/v1/executions/cancel`

GET `/api/v1/executions/waiting`

POST `/api/v1/executions/waiting/{stepId}/wake`

POST `/api/v1/signals`

Executions ​

GET /api/v1/executions ​

GET /api/v1/executions/{id} ​

GET /api/v1/executions/{id}/attachments/{position} ​

GET /api/v1/executions/{id}/steps/{nodeId}/iterations ​

POST /api/v1/executions/{id}/retry ​

POST /api/v1/executions/{id}/cancel ​

POST /api/v1/executions/cancel ​

GET /api/v1/executions/waiting ​

POST /api/v1/executions/waiting/{stepId}/wake ​

POST /api/v1/signals ​

Executions

GET `/api/v1/executions`

GET `/api/v1/executions/{id}`

GET `/api/v1/executions/{id}/attachments/{position}`

GET `/api/v1/executions/{id}/steps/{nodeId}/iterations`

POST `/api/v1/executions/{id}/retry`

POST `/api/v1/executions/{id}/cancel`

POST `/api/v1/executions/cancel`

GET `/api/v1/executions/waiting`

POST `/api/v1/executions/waiting/{stepId}/wake`

POST `/api/v1/signals`