Français
Workflows
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/workflows
Lister mes workflows
Les workflows du membre, avec les références de leur brouillon et de leur version publiée. Les archivés sont omis sauf includeArchived=true.
Accès — Session de membre ou clé d’API portant workflows:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
includeArchived | requête | string | non |
Réponses
200 — Les workflows.
| Champ | Type | Requis |
|---|---|---|
workflows | object[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"workflows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"published": { "type": "boolean" },
"draftVersion": {
"anyOf": [
{
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"publishedVersion": {
"anyOf": [
{
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"dispatchPriority": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{ "type": "null" }
]
},
"hasWebhook": { "type": "boolean" },
"pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"errorWorkflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"maxConcurrency": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{ "type": "null" }
]
},
"executionTimeoutMs": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{ "type": "null" }
]
},
"executionLimits": {
"type": "object",
"properties": {
"maxConcurrency": {
"type": "object",
"properties": {
"effective": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"default": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"max": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [ "effective", "default", "max" ],
"additionalProperties": false
},
"executionTimeoutMs": {
"type": "object",
"properties": {
"effective": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"default": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"max": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [ "effective", "default", "max" ],
"additionalProperties": false
}
},
"required": [ "maxConcurrency", "executionTimeoutMs" ],
"additionalProperties": false
},
"lastExecution": {
"anyOf": [
{
"type": "object",
"properties": {
"id": { "type": "string" },
"status": {
"type": "string",
"enum": [
"queued",
"running",
"waiting",
"succeeded",
"failed",
"cancelled"
]
},
"createdAt": { "type": "string" }
},
"required": [ "id", "status", "createdAt" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [
"id",
"name",
"published",
"draftVersion",
"publishedVersion",
"archivedAt",
"dispatchPriority",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}
}
},
"required": [ "workflows" ],
"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.
POST /api/v1/workflows
Créer un workflow
Crée un workflow en brouillon, propriété du membre, vide ou à partir du graphe donné. Rien n’est publié : publier est un geste à part.
Accès — Session de membre ou clé d’API portant workflows:write.
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
name | string | oui |
graph | object | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"graph": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 128 },
"workflowId": { "type": "string", "minLength": 1, "maxLength": 128 },
"nodes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
"type": { "type": "string", "minLength": 1, "maxLength": 128 },
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"params": {
"default": {},
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"onError": {
"default": "fail",
"type": "string",
"enum": [ "fail", "continue", "errorPort" ]
},
"retry": {
"type": "object",
"properties": {
"maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
"delayMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
},
"required": [ "maxAttempts" ]
},
"timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ]
},
"disabled": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 2000 }
},
"required": [ "id", "type", "version", "name" ]
}
},
"connections": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"from": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
"output": { "type": "string" },
"to": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
"input": { "type": "string" },
"kind": { "type": "string", "enum": [ "data", "service" ] }
},
"required": [ "from", "output", "to" ]
}
},
"notes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 64 },
"text": { "default": "", "type": "string", "maxLength": 4000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ]
},
"size": {
"default": { "width": 240, "height": 160 },
"type": "object",
"properties": {
"width": { "type": "number", "minimum": 120, "maximum": 2000 },
"height": { "type": "number", "minimum": 80, "maximum": 2000 }
},
"required": [ "width", "height" ]
},
"color": {
"default": "jaune",
"type": "string",
"enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
}
},
"required": [ "id", "position" ]
}
},
"pins": {
"type": "object",
"propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
"additionalProperties": {
"type": "object",
"properties": {
"output": {},
"port": { "type": "string" },
"pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
},
"required": [ "output", "pinnedAt" ]
}
}
},
"required": [ "id", "workflowId", "nodes", "connections" ],
"additionalProperties": false
}
},
"required": [ "name" ]
}Réponses
201 — Le workflow, avec son graphe de brouillon et son diagnostic.
| Champ | Type | Requis |
|---|---|---|
id | string | oui |
name | string | oui |
published | boolean | oui |
draftVersion | object | null | oui |
publishedVersion | object | null | oui |
archivedAt | string | null | oui |
dispatchPriority | integer | null | oui |
hasWebhook | boolean | non |
pausedAt | string | null | non |
errorWorkflowId | string | null | non |
maxConcurrency | integer | null | non |
executionTimeoutMs | integer | null | non |
executionLimits | object | non |
lastExecution | object | null | non |
createdAt | string | oui |
updatedAt | string | oui |
graph | object | oui |
validation | object | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"published": { "type": "boolean" },
"draftVersion": {
"anyOf": [
{
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"publishedVersion": {
"anyOf": [
{
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"dispatchPriority": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{ "type": "null" }
]
},
"hasWebhook": { "type": "boolean" },
"pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"errorWorkflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"maxConcurrency": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{ "type": "null" }
]
},
"executionTimeoutMs": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{ "type": "null" }
]
},
"executionLimits": {
"type": "object",
"properties": {
"maxConcurrency": {
"type": "object",
"properties": {
"effective": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"default": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"max": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [ "effective", "default", "max" ],
"additionalProperties": false
},
"executionTimeoutMs": {
"type": "object",
"properties": {
"effective": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"default": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"max": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [ "effective", "default", "max" ],
"additionalProperties": false
}
},
"required": [ "maxConcurrency", "executionTimeoutMs" ],
"additionalProperties": false
},
"lastExecution": {
"anyOf": [
{
"type": "object",
"properties": {
"id": { "type": "string" },
"status": {
"type": "string",
"enum": [
"queued",
"running",
"waiting",
"succeeded",
"failed",
"cancelled"
]
},
"createdAt": { "type": "string" }
},
"required": [ "id", "status", "createdAt" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" },
"graph": {
"type": "object",
"properties": {
"id": {},
"workflowId": {},
"nodes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {},
"type": { "type": "string", "minLength": 1, "maxLength": 128 },
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"params": {
"default": {},
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"onError": {
"default": "fail",
"type": "string",
"enum": [ "fail", "continue", "errorPort" ]
},
"retry": {
"type": "object",
"properties": {
"maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
"delayMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
},
"required": [ "maxAttempts" ],
"additionalProperties": false
},
"timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"disabled": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 2000 }
},
"required": [ "id", "type", "version", "name", "params", "onError" ],
"additionalProperties": false
}
},
"connections": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"from": {},
"output": { "type": "string" },
"to": {},
"input": { "type": "string" },
"kind": { "type": "string", "enum": [ "data", "service" ] }
},
"required": [ "from", "output", "to" ],
"additionalProperties": false
}
},
"notes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 64 },
"text": { "default": "", "type": "string", "maxLength": 4000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"size": {
"default": { "width": 240, "height": 160 },
"type": "object",
"properties": {
"width": { "type": "number", "minimum": 120, "maximum": 2000 },
"height": { "type": "number", "minimum": 80, "maximum": 2000 }
},
"required": [ "width", "height" ],
"additionalProperties": false
},
"color": {
"default": "jaune",
"type": "string",
"enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
}
},
"required": [ "id", "text", "position", "size", "color" ],
"additionalProperties": false
}
},
"pins": {
"type": "object",
"propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
"additionalProperties": {
"type": "object",
"properties": {
"output": {},
"port": { "type": "string" },
"pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
},
"required": [ "output", "pinnedAt" ],
"additionalProperties": false
}
}
},
"required": [ "id", "workflowId", "nodes", "connections" ],
"additionalProperties": false
},
"validation": {
"type": "object",
"properties": {
"ok": { "type": "boolean" },
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
}
},
"required": [ "ok", "errors", "warnings" ],
"additionalProperties": false
}
},
"required": [
"id",
"name",
"published",
"draftVersion",
"publishedVersion",
"archivedAt",
"dispatchPriority",
"createdAt",
"updatedAt",
"graph",
"validation"
],
"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, workflow.invalid_graph, workflow.graph_outdated. 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
json
{ "name": "Triage des factures" }GET /api/v1/workflows/{id}
Lire un workflow
Le résumé, le graphe du brouillon et son diagnostic de validation. Un workflow qui n’appartient pas à l’appelant est un 404, jamais un 403.
Accès — Session de membre ou clé d’API portant workflows:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — Le workflow.
| Champ | Type | Requis |
|---|---|---|
id | string | oui |
name | string | oui |
published | boolean | oui |
draftVersion | object | null | oui |
publishedVersion | object | null | oui |
archivedAt | string | null | oui |
dispatchPriority | integer | null | oui |
hasWebhook | boolean | non |
pausedAt | string | null | non |
errorWorkflowId | string | null | non |
maxConcurrency | integer | null | non |
executionTimeoutMs | integer | null | non |
executionLimits | object | non |
lastExecution | object | null | non |
createdAt | string | oui |
updatedAt | string | oui |
graph | object | oui |
validation | object | oui |
Même schéma que POST /api/v1/workflows.
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 — workflow.not_found, workflow.invalid_graph, workflow.graph_outdated. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
PATCH /api/v1/workflows/{id}
Renommer, archiver ou régler un workflow
Mise à jour partielle : nom, archivage, priorité d’envoi et workflow d’erreur. Pour les champs nullables, une clé absente laisse la valeur, null l’efface. Archiver désarme les déclencheurs sans rien effacer.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
name | string | non |
archived | boolean | non |
dispatchPriority | integer | null | non |
errorWorkflowId | string | null | non |
maxConcurrency | integer | null | non |
executionTimeoutMs | integer | null | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"archived": { "type": "boolean" },
"dispatchPriority": {
"anyOf": [
{ "type": "integer", "minimum": 0, "maximum": 9999 },
{ "type": "null" }
]
},
"errorWorkflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"maxConcurrency": {
"anyOf": [
{ "type": "integer", "minimum": 1, "maximum": 1000 },
{ "type": "null" }
]
},
"executionTimeoutMs": {
"anyOf": [
{ "type": "integer", "minimum": 60000, "maximum": 9007199254740991 },
{ "type": "null" }
]
}
}
}Réponses
200 — Le workflow, mis à jour.
| Champ | Type | Requis |
|---|---|---|
id | string | oui |
name | string | oui |
published | boolean | oui |
draftVersion | object | null | oui |
publishedVersion | object | null | oui |
archivedAt | string | null | oui |
dispatchPriority | integer | null | oui |
hasWebhook | boolean | non |
pausedAt | string | null | non |
errorWorkflowId | string | null | non |
maxConcurrency | integer | null | non |
executionTimeoutMs | integer | null | non |
executionLimits | object | non |
lastExecution | object | null | non |
createdAt | string | oui |
updatedAt | string | oui |
graph | object | oui |
validation | object | oui |
Même schéma que POST /api/v1/workflows.
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, workflow.not_found, workflow.error_workflow_invalid. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
DELETE /api/v1/workflows/{id}
Supprimer un brouillon vierge
Seul un workflow jamais publié et jamais exécuté peut être supprimé. Tout autre est refusé avec workflow.delete_forbidden : archivez-le plutôt.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
204 — Supprimé.
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 — workflow.not_found, workflow.delete_forbidden. 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/workflows/{id}/duplicate
Dupliquer un workflow
Crée un nouveau brouillon à partir du graphe de brouillon de la source. La copie n’emporte ni publication, ni exécutions, ni mails d’essai, ni jeton de webhook.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
name | string | oui |
Schéma JSON
json
{
"type": "object",
"properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } },
"required": [ "name" ]
}Réponses
201 — La copie.
| Champ | Type | Requis |
|---|---|---|
id | string | oui |
name | string | oui |
published | boolean | oui |
draftVersion | object | null | oui |
publishedVersion | object | null | oui |
archivedAt | string | null | oui |
dispatchPriority | integer | null | oui |
hasWebhook | boolean | non |
pausedAt | string | null | non |
errorWorkflowId | string | null | non |
maxConcurrency | integer | null | non |
executionTimeoutMs | integer | null | non |
executionLimits | object | non |
lastExecution | object | null | non |
createdAt | string | oui |
updatedAt | string | oui |
graph | object | oui |
validation | object | oui |
Même schéma que POST /api/v1/workflows.
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, workflow.not_found, workflow.invalid_graph, workflow.graph_outdated. 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/workflows/{id}/draft
Lire le brouillon
La même forme que GET /workflows/{id} : le résumé avec le graphe du brouillon et son diagnostic.
Accès — Session de membre ou clé d’API portant workflows:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — Le brouillon.
| Champ | Type | Requis |
|---|---|---|
id | string | oui |
name | string | oui |
published | boolean | oui |
draftVersion | object | null | oui |
publishedVersion | object | null | oui |
archivedAt | string | null | oui |
dispatchPriority | integer | null | oui |
hasWebhook | boolean | non |
pausedAt | string | null | non |
errorWorkflowId | string | null | non |
maxConcurrency | integer | null | non |
executionTimeoutMs | integer | null | non |
executionLimits | object | non |
lastExecution | object | null | non |
createdAt | string | oui |
updatedAt | string | oui |
graph | object | oui |
validation | object | oui |
Même schéma que POST /api/v1/workflows.
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 — workflow.not_found, workflow.invalid_graph, workflow.graph_outdated. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
PUT /api/v1/workflows/{id}/draft
Enregistrer le brouillon
Avertissements seulement : un graphe incohérent est enregistré et ses problèmes rendus, seul un document mal formé est refusé (400). Avec expectedDraft, l’écriture est refusée (409 workflow.draft_conflict) si le brouillon a été écrit ailleurs depuis sa lecture.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
graph | object | oui |
expectedDraft | object | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"graph": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 128 },
"workflowId": { "type": "string", "minLength": 1, "maxLength": 128 },
"nodes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
"type": { "type": "string", "minLength": 1, "maxLength": 128 },
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"params": {
"default": {},
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"onError": {
"default": "fail",
"type": "string",
"enum": [ "fail", "continue", "errorPort" ]
},
"retry": {
"type": "object",
"properties": {
"maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
"delayMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
},
"required": [ "maxAttempts" ]
},
"timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ]
},
"disabled": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 2000 }
},
"required": [ "id", "type", "version", "name" ]
}
},
"connections": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"from": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
"output": { "type": "string" },
"to": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
"input": { "type": "string" },
"kind": { "type": "string", "enum": [ "data", "service" ] }
},
"required": [ "from", "output", "to" ]
}
},
"notes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 64 },
"text": { "default": "", "type": "string", "maxLength": 4000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ]
},
"size": {
"default": { "width": 240, "height": 160 },
"type": "object",
"properties": {
"width": { "type": "number", "minimum": 120, "maximum": 2000 },
"height": { "type": "number", "minimum": 80, "maximum": 2000 }
},
"required": [ "width", "height" ]
},
"color": {
"default": "jaune",
"type": "string",
"enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
}
},
"required": [ "id", "position" ]
}
},
"pins": {
"type": "object",
"propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
"additionalProperties": {
"type": "object",
"properties": {
"output": {},
"port": { "type": "string" },
"pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
},
"required": [ "output", "pinnedAt" ]
}
}
},
"required": [ "id", "workflowId", "nodes", "connections" ],
"additionalProperties": false
},
"expectedDraft": {
"type": "object",
"properties": { "id": { "type": "string" }, "updatedAt": { "type": "string" } },
"required": [ "id", "updatedAt" ]
}
},
"required": [ "graph" ]
}Réponses
200 — La nouvelle version de brouillon et son diagnostic.
| Champ | Type | Requis |
|---|---|---|
version | object | oui |
validation | object | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"version": {
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
},
"validation": {
"type": "object",
"properties": {
"ok": { "type": "boolean" },
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
}
},
"required": [ "ok", "errors", "warnings" ],
"additionalProperties": false
}
},
"required": [ "version", "validation" ],
"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 — workflow.not_found, workflow.invalid_graph, workflow.graph_outdated, workflow.draft_conflict. 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/workflows/{id}/publish
Publier le brouillon
Fige le brouillon en version publiée et arme ses déclencheurs. Bloquant sur les erreurs de validation (409 workflow.not_publishable, diagnostic dans details.validation). Pour un déclencheur webhook, le jeton est rendu ici en clair, une fois, et plus jamais.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — La version publiée, les boîtes armées et l’URL de webhook s’il y en a une.
| Champ | Type | Requis |
|---|---|---|
ok | boolean | oui |
validation | object | oui |
publishedVersion | object | null | oui |
armedMailboxes | integer | oui |
webhook | object | null | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"ok": { "type": "boolean" },
"validation": {
"type": "object",
"properties": {
"ok": { "type": "boolean" },
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
}
},
"required": [ "ok", "errors", "warnings" ],
"additionalProperties": false
},
"publishedVersion": {
"anyOf": [
{
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"armedMailboxes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"webhook": {
"anyOf": [
{
"type": "object",
"properties": {
"configured": { "type": "boolean" },
"url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [ "configured", "url", "token" ],
"additionalProperties": false
},
{ "type": "null" }
]
}
},
"required": [ "ok", "validation", "publishedVersion", "armedMailboxes" ],
"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.
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 — workflow.not_found, workflow.archived, workflow.not_publishable, workflow.call_cycle, workflow.invalid_graph, workflow.graph_outdated. 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/workflows/{id}/unpublish
Dépublier un workflow
Désarme les déclencheurs et retire la version publiée. Le brouillon est intact.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — Dépublié.
| Champ | Type | Requis |
|---|---|---|
published | false | oui |
Schéma JSON
json
{
"type": "object",
"properties": { "published": { "type": "boolean", "const": false } },
"required": [ "published" ],
"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 — workflow.not_found, workflow.not_published. 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/workflows/{id}/pause
Suspendre un workflow publié
Arrête les déclenchements sans dépublier : la version publiée reste, rien ne part jusqu’à resume. Exige un workflow publié (409 workflow.not_published sinon). Tracé au journal d’audit.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — L’instant de la pause.
| Champ | Type | Requis |
|---|---|---|
pausedAt | string | oui |
Schéma JSON
json
{
"type": "object",
"properties": { "pausedAt": { "type": "string" } },
"required": [ "pausedAt" ],
"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 — workflow.not_found, workflow.not_published. 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/workflows/{id}/resume
Reprendre un workflow suspendu
Les déclencheurs repartent. Idempotent : reprendre un workflow qui n’est pas en pause rend 200.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — Repris.
| Champ | Type | Requis |
|---|---|---|
pausedAt | null | oui |
Schéma JSON
json
{
"type": "object",
"properties": { "pausedAt": { "type": "null" } },
"required": [ "pausedAt" ],
"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 — workflow.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/workflows/{id}/webhook
Générer ou régénérer l’URL de webhook
Émet un nouveau jeton pour le déclencheur webhook ; l’ancienne URL cesse de répondre aussitôt. Le jeton n’est stocké que haché : c’est le seul moyen de revoir une URL. Autorisé avant publication : l’URL ne déclenche rien tant que le workflow n’est pas publié.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — L’URL de webhook et son jeton, en clair, une fois.
| Champ | Type | Requis |
|---|---|---|
webhook | object | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"webhook": {
"type": "object",
"properties": {
"configured": { "type": "boolean" },
"url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [ "configured", "url", "token" ],
"additionalProperties": false
}
},
"required": [ "webhook" ],
"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 — workflow.not_found, workflow.not_a_webhook. 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/workflows/{id}/versions
Lister les versions d’un workflow
L’historique, en références de version (sans graphe). Le graphe figé se lit par GET .../versions/{versionId}/graph.
Accès — Session de membre ou clé d’API portant workflows:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — Les versions.
| Champ | Type | Requis |
|---|---|---|
versions | object[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"versions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
}
}
},
"required": [ "versions" ],
"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 — workflow.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/workflows/{id}/versions/{versionId}/graph
Lire le graphe figé d’une version
Une version d’un autre workflow, ou d’un autre membre, est le même 404 qu’un identifiant inconnu.
Accès — Session de membre ou clé d’API portant workflows:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
versionId | chemin | string | oui |
Réponses
200 — Le graphe.
| Champ | Type | Requis |
|---|---|---|
graph | object | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"graph": {
"type": "object",
"properties": {
"id": {},
"workflowId": {},
"nodes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {},
"type": { "type": "string", "minLength": 1, "maxLength": 128 },
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"params": {
"default": {},
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"onError": {
"default": "fail",
"type": "string",
"enum": [ "fail", "continue", "errorPort" ]
},
"retry": {
"type": "object",
"properties": {
"maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
"delayMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
},
"required": [ "maxAttempts" ],
"additionalProperties": false
},
"timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"disabled": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 2000 }
},
"required": [ "id", "type", "version", "name", "params", "onError" ],
"additionalProperties": false
}
},
"connections": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"from": {},
"output": { "type": "string" },
"to": {},
"input": { "type": "string" },
"kind": { "type": "string", "enum": [ "data", "service" ] }
},
"required": [ "from", "output", "to" ],
"additionalProperties": false
}
},
"notes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 64 },
"text": { "default": "", "type": "string", "maxLength": 4000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"size": {
"default": { "width": 240, "height": 160 },
"type": "object",
"properties": {
"width": { "type": "number", "minimum": 120, "maximum": 2000 },
"height": { "type": "number", "minimum": 80, "maximum": 2000 }
},
"required": [ "width", "height" ],
"additionalProperties": false
},
"color": {
"default": "jaune",
"type": "string",
"enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
}
},
"required": [ "id", "text", "position", "size", "color" ],
"additionalProperties": false
}
},
"pins": {
"type": "object",
"propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
"additionalProperties": {
"type": "object",
"properties": {
"output": {},
"port": { "type": "string" },
"pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
},
"required": [ "output", "pinnedAt" ],
"additionalProperties": false
}
}
},
"required": [ "id", "workflowId", "nodes", "connections" ],
"additionalProperties": false
}
},
"required": [ "graph" ],
"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 — workflow.not_found, workflow.invalid_graph, workflow.graph_outdated. 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/workflows/{id}/versions/{versionId}/restore
Reprendre une version comme brouillon
Recopie le graphe figé de la version dans le brouillon, par le même chemin qu’un enregistrement. Rien n’est publié ni effacé. Pas de contrôle de concurrence : le geste remplace délibérément le brouillon. Refusé sur un workflow archivé.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
versionId | chemin | string | oui |
Réponses
200 — La nouvelle version de brouillon, son graphe et son diagnostic.
| Champ | Type | Requis |
|---|---|---|
version | object | oui |
graph | object | oui |
validation | object | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"version": {
"type": "object",
"properties": {
"id": { "type": "string" },
"number": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [ "id", "number", "publishedAt", "createdAt" ],
"additionalProperties": false
},
"graph": {
"type": "object",
"properties": {
"id": {},
"workflowId": {},
"nodes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {},
"type": { "type": "string", "minLength": 1, "maxLength": 128 },
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"params": {
"default": {},
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"onError": {
"default": "fail",
"type": "string",
"enum": [ "fail", "continue", "errorPort" ]
},
"retry": {
"type": "object",
"properties": {
"maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
"delayMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
},
"required": [ "maxAttempts" ],
"additionalProperties": false
},
"timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"disabled": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 2000 }
},
"required": [ "id", "type", "version", "name", "params", "onError" ],
"additionalProperties": false
}
},
"connections": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"from": {},
"output": { "type": "string" },
"to": {},
"input": { "type": "string" },
"kind": { "type": "string", "enum": [ "data", "service" ] }
},
"required": [ "from", "output", "to" ],
"additionalProperties": false
}
},
"notes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 64 },
"text": { "default": "", "type": "string", "maxLength": 4000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"size": {
"default": { "width": 240, "height": 160 },
"type": "object",
"properties": {
"width": { "type": "number", "minimum": 120, "maximum": 2000 },
"height": { "type": "number", "minimum": 80, "maximum": 2000 }
},
"required": [ "width", "height" ],
"additionalProperties": false
},
"color": {
"default": "jaune",
"type": "string",
"enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
}
},
"required": [ "id", "text", "position", "size", "color" ],
"additionalProperties": false
}
},
"pins": {
"type": "object",
"propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
"additionalProperties": {
"type": "object",
"properties": {
"output": {},
"port": { "type": "string" },
"pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
},
"required": [ "output", "pinnedAt" ],
"additionalProperties": false
}
}
},
"required": [ "id", "workflowId", "nodes", "connections" ],
"additionalProperties": false
},
"validation": {
"type": "object",
"properties": {
"ok": { "type": "boolean" },
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "type": "string" },
"nodeName": { "type": "string" },
"nodeType": { "type": "string" },
"connectionIndex": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"port": { "type": "string" },
"availablePorts": { "type": "array", "items": { "type": "string" } },
"cycle": { "type": "array", "items": { "type": "string" } },
"param": { "type": "string" },
"value": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] },
"triggerTypes": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"path": { "type": "string" }
},
"required": [ "code", "message", "path" ],
"additionalProperties": false
}
}
},
"required": [ "code", "message" ],
"additionalProperties": false
}
}
},
"required": [ "ok", "errors", "warnings" ],
"additionalProperties": false
}
},
"required": [ "version", "graph", "validation" ],
"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 — workflow.not_found, workflow.archived, workflow.invalid_graph, workflow.graph_outdated. 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/workflows/{id}/test
Exécuter le brouillon en simulé
Planifie une exécution simulée du BROUILLON sur un mail réel du miroir ou sur des données de déclenchement : aucun mail ne part, aucun effet. triggerNodeId est requis quand le brouillon a des déclencheurs de natures différentes ; targetNodeId s’arrête après ce nœud. 202 : l’exécution est planifiée, ses étapes arrivent par le WebSocket et GET /executions/{id}.
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 |
|---|---|---|
messageId | string | non |
triggerData | object | non |
triggerNodeId | string | non |
targetNodeId | string | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"messageId": { "type": "string", "minLength": 1 },
"triggerData": {
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"triggerNodeId": { "type": "string", "minLength": 1 },
"targetNodeId": { "type": "string", "minLength": 1 }
}
}Réponses
202 — L’exécution planifiée et les nœuds qu’elle fera tourner.
| Champ | Type | Requis |
|---|---|---|
execution | object | oui |
plannedNodes | string[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"execution": {
"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
},
"plannedNodes": { "type": "array", "items": { "type": "string" } }
},
"required": [ "execution", "plannedNodes" ],
"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, workflow.not_found, workflow.not_publishable, workflow.trigger_required, workflow.unknown_trigger, workflow.unknown_node, workflow.node_not_executable, workflow.test_message_not_found, workflow.trigger_poll_failed, workflow.invalid_graph, workflow.graph_outdated. 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/workflows/{id}/run
Lancer la version publiée sur un mail
Une exécution RÉELLE de la version PUBLIÉE sur un mail du miroir du membre : les mails partent. À ne pas confondre avec test. Un workflow non publié est refusé (workflow.not_published). Rejouable à volonté sur le même mail. 202 : l’exécution est planifiée.
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 |
|---|---|---|
messageId | string | oui |
clientToken | string | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"messageId": { "type": "string", "minLength": 1 },
"clientToken": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
},
"required": [ "messageId" ]
}Réponses
202 — L’identifiant de l’exécution planifiée et les nœuds qu’elle fera tourner.
| Champ | Type | Requis |
|---|---|---|
executionId | string | oui |
plannedNodes | string[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"executionId": { "type": "string" },
"plannedNodes": { "type": "array", "items": { "type": "string" } }
},
"required": [ "executionId", "plannedNodes" ],
"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, workflow.not_found, workflow.not_published, workflow.archived, workflow.test_message_not_found, 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
json
{ "messageId": "0192f1c2-aaaa-7000-8000-000000000042" }Exemple de réponse (202)
json
{
"executionId": "0192f1c2-bbbb-7000-8000-000000000007",
"plannedNodes": [ "trigger", "categorize", "reply" ]
}POST /api/v1/workflows/{id}/executions/retry-failed
Rejouer les exécutions échouées d’un workflow
Planifie le rejeu des exécutions réelles échouées depuis since (24 h par défaut, 30 jours au plus) et pas encore rejouées, jusqu’à limit. hasMore dit s’il faut rappeler. 202 : les exécutions sont planifiées.
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 |
|---|---|---|
since | string (date-time) | non |
from | "start" | "failed_step" | non |
version | "published" | "origin" | non |
limit | integer | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"since": {
"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"from": { "default": "start", "type": "string", "enum": [ "start", "failed_step" ] },
"version": {
"default": "published",
"type": "string",
"enum": [ "published", "origin" ]
},
"limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }
}
}Réponses
202 — Les nouvelles exécutions, le nombre d’ignorées et s’il en reste.
| Champ | Type | Requis |
|---|---|---|
executionIds | string[] | oui |
skipped | integer | oui |
hasMore | boolean | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"executionIds": { "type": "array", "items": { "type": "string" } },
"skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"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, workflow.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/workflows/{id}/executions/cancel
Annuler les exécutions en vol d’un workflow
Annule les exécutions de premier niveau du workflow en file, en cours ou en attente, jusqu’à limit ; leurs enfants (sous-workflows, itérations) suivent par la cascade. 200 : les annulations sont faites, pas planifiées. hasMore dit s’il faut rappeler.
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 |
|---|---|---|
limit | integer | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }
}
}Réponses
200 — Ce qui a été annulé, ce qui a été ignoré, et s’il en reste.
| Champ | Type | Requis |
|---|---|---|
executionIds | string[] | oui |
skipped | object[] | oui |
hasMore | boolean | oui |
Schéma JSON
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, workflow.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/workflows/schedule/preview
Prévisualiser les prochains passages d’une planification
Une fonction pure du rythme et de l’horloge : les prochaines occurrences d’une planification en cours de saisie, sans rien enregistrer. Un rythme invalide n’est pas une erreur : 200 avec des issues et aucun passage, les mêmes codes que la publication refuserait.
Accès — Session de membre ou clé d’API portant workflows:read.
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
mode | "interval" | "cron" | oui |
everyMinutes | integer | non |
cron | string | non |
timezone | string | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"mode": { "type": "string", "enum": [ "interval", "cron" ] },
"everyMinutes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"cron": { "type": "string", "maxLength": 120 },
"timezone": { "type": "string", "maxLength": 64 }
},
"required": [ "mode" ]
}Réponses
200 — Les prochains passages, ou les problèmes.
| Champ | Type | Requis |
|---|---|---|
runs | string[] | oui |
issues | object[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"runs": { "type": "array", "items": { "type": "string" } },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": { "code": { "type": "string" }, "field": { "type": "string" } },
"required": [ "code", "field" ],
"additionalProperties": false
}
}
},
"required": [ "runs", "issues" ],
"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.
POST /api/v1/workflows/wait/preview
Prévisualiser le réveil d’une attente
Résout une échéance contre le calendrier ouvré et l’attente maximale de l’instance, depuis from ou maintenant. capped dit que le plafond l’a raccourcie. Une échéance incalculable est un 400 portant le code d’erreur d’échéance.
Accès — Session de membre ou clé d’API portant workflows:read.
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
mode | "duration" | "until" | "business" | oui |
amount | number | non |
unit | "minutes" | "hours" | "days" | "weeks" | "months" | "years" | non |
date | string | non |
offsetAmount | number | non |
offsetUnit | "days" | "weeks" | "months" | "years" | non |
businessAmount | number | non |
businessUnit | "businessDays" | "businessHours" | non |
atClock | string | non |
timezone | string | non |
onlyBusinessHours | boolean | non |
from | string (date-time) | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"mode": { "type": "string", "enum": [ "duration", "until", "business" ] },
"amount": { "type": "number" },
"unit": {
"type": "string",
"enum": [ "minutes", "hours", "days", "weeks", "months", "years" ]
},
"date": { "type": "string", "maxLength": 200 },
"offsetAmount": { "type": "number" },
"offsetUnit": { "type": "string", "enum": [ "days", "weeks", "months", "years" ] },
"businessAmount": { "type": "number" },
"businessUnit": { "type": "string", "enum": [ "businessDays", "businessHours" ] },
"atClock": { "type": "string", "maxLength": 80 },
"timezone": { "type": "string", "maxLength": 100 },
"onlyBusinessHours": { "type": "boolean" },
"from": {
"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))$"
}
},
"required": [ "mode" ]
}Réponses
200 — L’instant du réveil.
| Champ | Type | Requis |
|---|---|---|
at | string (date-time) | oui |
waitMs | integer | oui |
past | boolean | oui |
capped | boolean | oui |
shiftedToBusinessHours | boolean | oui |
timezone | string | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"at": {
"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))$"
},
"waitMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"past": { "type": "boolean" },
"capped": { "type": "boolean" },
"shiftedToBusinessHours": { "type": "boolean" },
"timezone": { "type": "string" }
},
"required": [ "at", "waitMs", "past", "capped", "shiftedToBusinessHours", "timezone" ],
"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.deadline_invalid. 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/workflows/{id}/test-messages
Lister les mails d’essai épinglés
Les mails épinglés à ce workflow pour l’essayer. Les messages purgés du miroir n’y sont plus.
Accès — Session de membre ou clé d’API portant workflows:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — Les messages.
| Champ | Type | Requis |
|---|---|---|
messages | object[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"mailboxId": { "type": "string" },
"from": {
"anyOf": [
{
"type": "object",
"properties": { "name": { "type": "string" }, "email": { "type": "string" } },
"required": [ "email" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"receivedAt": { "type": "string" },
"folderLabels": { "type": "array", "items": { "type": "string" } },
"flags": {
"type": "object",
"properties": {
"seen": { "type": "boolean" },
"flagged": { "type": "boolean" },
"draft": { "type": "boolean" },
"sent": { "type": "boolean" }
},
"required": [ "seen", "flagged", "draft", "sent" ],
"additionalProperties": false
},
"signals": {
"type": "object",
"properties": {
"isAutoReply": { "type": "boolean" },
"isNoReply": { "type": "boolean" },
"isMailingList": { "type": "boolean" },
"isFromSelf": { "type": "boolean" }
},
"required": [ "isAutoReply", "isNoReply", "isMailingList", "isFromSelf" ],
"additionalProperties": false
},
"hasAttachments": { "type": "boolean" },
"position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"addedAt": { "type": "string" }
},
"required": [
"id",
"mailboxId",
"from",
"subject",
"snippet",
"receivedAt",
"folderLabels",
"flags",
"signals",
"hasAttachments",
"position",
"addedAt"
],
"additionalProperties": false
}
}
},
"required": [ "messages" ],
"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 — workflow.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.
PUT /api/v1/workflows/{id}/test-messages
Remplacer les mails d’essai épinglés
Un remplacement, pas un ajout : le jeu entier, vingt messages au plus, une liste vide le vide. Un message hors des boîtes du membre est un 404.
Accès — Session de membre ou clé d’API portant workflows:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
messageIds | string[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"messageIds": {
"maxItems": 20,
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
},
"required": [ "messageIds" ]
}Réponses
200 — Le nouveau jeu.
| Champ | Type | Requis |
|---|---|---|
messages | object[] | oui |
Même schéma que GET /api/v1/workflows/{id}/test-messages.
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, workflow.not_found, workflow.test_message_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.