Exécutions

Les routes sont relatives à <PUBLIC_BASE_URL> ; les corps de requête et de réponse sont en JSON sauf mention contraire. L’authentification, les portées, la pagination et le format des erreurs sont décrits dans les guides de l’API REST.

GET /api/v1/executions

Lister mes exécutions

Les plus récentes d’abord, paginées par curseur (nextCursor, null à la fin). Filtres par workflow, boîte, statut et simulation. Le filtre de boîte est intersecté avec les boîtes du membre : celle d’un autre rend une page vide.

Accès — Session de membre ou clé d’API portant executions:read.

Paramètres

Nom	Où	Type	Requis
workflowId	requête	string	non
mailboxId	requête	string	non
status	requête	"queued" | "running" | "waiting" | "succeeded" | "failed" | "cancelled"	non
simulated	requête	string	non
q	requête	string	non
cursor	requête	string	non
limit	requête	integer	non

Réponses

200 — Une page d’exécutions.

Champ	Type	Requis
executions	object[]	oui
nextCursor	string | null	oui

Schéma 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 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — request.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

GET /api/v1/executions/{id}

Lire une exécution pas à pas

L’exécution, ses étapes avec leurs tentatives et leurs données, les pièces qu’elle a produites, et le nom du workflow (vide s’il a été supprimé depuis). L’exécution d’un autre membre est un 404.

Accès — Session de membre ou clé d’API portant executions:read.

Paramètres

Nom	Où	Type	Requis
id	chemin	string	oui

Réponses

200 — L’exécution.

Champ	Type	Requis
id	string	oui
workflowId	string	oui
workflowVersionId	string	oui
mailboxId	string | null	oui
messageId	string | null	oui
status	"queued" | "running" | "waiting" | "succeeded" | "failed" | "cancelled"	oui
simulated	boolean	oui
parentExecutionId	string | null	non
triggerNodeId	string | null	non
triggerType	string | null	non
retryOfExecutionId	string | null	non
messageHeadline	object | null	non
error	object | null	oui
startedAt	string | null	oui
finishedAt	string | null	oui
createdAt	string	oui
workflowName	string	oui
triggerData	object | null	non
steps	object[]	oui
attachments	object[]	non

Schéma 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 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — execution.not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

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

Télécharger une pièce produite par une exécution

Les octets de la pièce en position position de l’exécution, servis en attachment avec leur propre type et un nom de fichier encodé RFC 5987. Un blob purgé est attachment.unavailable (404).

Accès — Session de membre ou clé d’API portant executions:read.

Paramètres

Nom	Où	Type	Requis
id	chemin	string	oui
position	chemin	string	oui

Réponses

200 — Le fichier, en pièce jointe.

Type de contenu : application/octet-stream

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — execution.not_found, attachment.not_found, attachment.unavailable. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

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

Lister les itérations d’une étape de boucle

Les exécutions filles d’un nœud flow.loop, une par élément, tenues hors de la liste et du détail à dessein. Le périmètre est celui de l’exécution parente.

Accès — Session de membre ou clé d’API portant executions:read.

Paramètres

Nom	Où	Type	Requis
id	chemin	string	oui
nodeId	chemin	string	oui

Réponses

200 — Les itérations.

Champ	Type	Requis
nodeId	string	oui
iterations	object[]	oui

Schéma 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 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — execution.not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

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

Rejouer une exécution échouée

Planifie une nouvelle exécution à partir des données de déclenchement d’une échouée. Un corps vide rejoue depuis le début sur la version publiée ; from: "failed_step" réutilise les étapes réussies, version: "origin" rejoue la version qui a tourné. 202 : l’exécution est planifiée. Tracé au journal d’audit.

Accès — Session de membre ou clé d’API portant executions:write.

Paramètres

Nom	Où	Type	Requis
id	chemin	string	oui

Corps de la requête (application/json)

Champ	Type	Requis
from	"start" | "failed_step"	non
version	"published" | "origin"	non

Schéma JSON

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

Réponses

202 — L’identifiant de la nouvelle exécution.

Champ	Type	Requis
executionId	string	oui

Schéma JSON

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

400 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Cette opération accepte un en-tête Idempotency-Key : rejouer la même requête avec la même clé rend la réponse d’origine au lieu d’agir deux fois. Voir Idempotence.

Codes d’erreur — request.bad_request, execution.not_found, execution.not_retryable, execution.version_unavailable, workflow.invalid_graph. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

Exemple de requête

{ "from": "failed_step" }

Exemple de réponse (202)

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

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

Annuler une exécution en cours

Arrête l’exécution et ses filles ; 200 avec le statut final. Une exécution déjà conclue à la lecture est execution.not_cancellable (409).

Accès — Session de membre ou clé d’API portant executions:write.

Paramètres

Nom	Où	Type	Requis
id	chemin	string	oui

Réponses

200 — Le statut final.

Champ	Type	Requis
status	"queued" | "running" | "waiting" | "succeeded" | "failed" | "cancelled"	oui

Schéma JSON

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

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — execution.not_found, execution.not_cancellable. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

POST /api/v1/executions/cancel

Annuler une sélection d’exécutions

Annule jusqu’à 200 exécutions par identifiant, dans le périmètre du membre. Le lot ne s’arrête jamais sur un intrus : un id inconnu, ou d’un autre membre, est rendu not_found dans skipped, une exécution déjà conclue already_settled. 200 : les annulations sont faites, pas planifiées ; hasMore est toujours faux ici.

Accès — Session de membre ou clé d’API portant executions:write.

Corps de la requête (application/json)

Champ	Type	Requis
executionIds	string[]	oui

Schéma JSON

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

Réponses

200 — Ce qui a été annulé, et ce qui a été ignoré.

Champ	Type	Requis
executionIds	string[]	oui
skipped	object[]	oui
hasMore	boolean	oui

Schéma 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 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Cette opération accepte un en-tête Idempotency-Key : rejouer la même requête avec la même clé rend la réponse d’origine au lieu d’agir deux fois. Voir Idempotence.

Codes d’erreur — request.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

GET /api/v1/executions/waiting

Lister les exécutions en attente

Les exécutions réelles suspendues sur un nœud d’attente, avec leur instant de réveil et leur clé de signal, triées par échéance et paginées par curseur. signalKey filtre par préfixe ; overdueOnly ne garde que les retards.

Accès — Session de membre ou clé d’API portant executions:read.

Paramètres

Nom	Où	Type	Requis
signalKey	requête	string	non
workflowId	requête	string (uuid)	non
overdueOnly	requête	boolean	non
limit	requête	integer	non
cursor	requête	string	non

Réponses

200 — Une page d’exécutions en attente.

Champ	Type	Requis
items	object[]	oui
nextCursor	string | null	oui

Schéma 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 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — wait.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

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

Réveiller une attente à la main

Reprend l’étape par le port choisi : done comme si l’échéance était atteinte, event comme si l’événement attendu était arrivé. Les deux branches ne font pas la même chose : l’API ne choisit jamais. Tracé au journal d’audit.

Accès — Session de membre ou clé d’API portant executions:write.

Paramètres

Nom	Où	Type	Requis
stepId	chemin	string	oui

Corps de la requête (application/json)

Champ	Type	Requis
outcome	"done" | "event"	non

Schéma JSON

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

Réponses

200 — Reprise.

Champ	Type	Requis
resumed	true	oui

Schéma JSON

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

400 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — wait.bad_request, wait.step_not_found, wait.step_not_waiting, wait.outcome_not_available, wait.already_settled. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

POST /api/v1/signals

Émettre un signal

Réveille (resume) ou annule (cancel) toute exécution en attente de key, à l’échelle de l’instance : un signal est organisationnel, pas borné à un membre. matched compte les attentes atteintes, 0 quand rien n’écoute encore ; le signal est conservé un temps pour qu’une attente installée plus tard l’attrape. duplicate dit qu’une émission identique a été absorbée.

Accès — Session de membre ou clé d’API portant signals:write.

Corps de la requête (application/json)

Champ	Type	Requis
key	string	oui
action	"resume" | "cancel"	non
payload	object	non

Schéma 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" ]
}

Réponses

200 — Le signal et ce qu’il a atteint.

Champ	Type	Requis
signalId	string	oui
matched	integer	oui
duplicate	boolean	oui

Schéma JSON

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

400 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Cette opération accepte un en-tête Idempotency-Key : rejouer la même requête avec la même clé rend la réponse d’origine au lieu d’agir deux fois. Voir Idempotence.

Codes d’erreur — wait.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

Exemple de requête

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

Exemple de réponse (200)

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