Templates

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/templates

Lister les templates de l’instance

Ce que le membre peut installer. Un administrateur reçoit la même forme, templates désactivés compris.

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

Réponses

200 — Les templates.

Champ	Type	Requis
templates	object[]	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "templates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "enabled": { "type": "boolean" },
          "nodeTypes": { "type": "array", "items": { "type": "string" } },
          "requiresProviders": { "type": "array", "items": { "type": "string" } },
          "createdBy": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              { "type": "null" }
            ]
          },
          "createdAt": {
            "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))$"
          },
          "updatedAt": {
            "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))$"
          },
          "installCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
        },
        "required": [
          "id",
          "name",
          "description",
          "category",
          "enabled",
          "nodeTypes",
          "requiresProviders",
          "createdBy",
          "createdAt",
          "updatedAt",
          "installCount"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "templates" ],
  "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.

GET /api/v1/templates/{id}

Lire un template et son graphe

Le graphe voyage pour que l’installation soit un choix éclairé. Pour un membre, un template désactivé est le même 404 qu’un identifiant inconnu.

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

Paramètres

Nom	Où	Type	Requis
id	chemin	string	oui

Réponses

200 — Le template.

Champ	Type	Requis
template	object	oui
graph	object	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "name": { "type": "string" },
        "description": { "type": "string" },
        "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
        "enabled": { "type": "boolean" },
        "nodeTypes": { "type": "array", "items": { "type": "string" } },
        "requiresProviders": { "type": "array", "items": { "type": "string" } },
        "createdBy": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            { "type": "null" }
          ]
        },
        "createdAt": {
          "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))$"
        },
        "updatedAt": {
          "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))$"
        },
        "installCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
      },
      "required": [
        "id",
        "name",
        "description",
        "category",
        "enabled",
        "nodeTypes",
        "requiresProviders",
        "createdBy",
        "createdAt",
        "updatedAt",
        "installCount"
      ],
      "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
    }
  },
  "required": [ "template", "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 — templates.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/templates/{id}/install

Installer un template en nouveau brouillon

Crée un workflow en brouillon, propriété du membre, à partir d’une copie du graphe du template ; publier reste un geste explicite. Un template qui utilise un type de nœud interdit à ce membre est refusé (409 templates.forbidden_node, les types dans details.nodeTypes).

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

Schéma JSON

{
  "type": "object",
  "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }
}

Réponses

201 — L’identifiant du nouveau workflow.

Champ	Type	Requis
workflowId	string (uuid)	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "workflowId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [ "workflowId" ],
  "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, templates.not_found, templates.forbidden_node. 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

{}

Exemple de réponse (201)

{ "workflowId": "0192f1c2-dddd-7000-8000-000000000011" }

POST /api/v1/admin/templates/promote

Promouvoir un workflow en template

Fige le graphe du workflow de n’importe quel membre (sa version publiée, ou son brouillon) en template de l’instance. Un graphe qui échoue à la validation est refusé avec 422 templates.invalid_graph et le diagnostic dans details.validation.

Accès — Session de membre ou clé d’API portant admin:write (rôle administrateur requis).

Corps de la requête (application/json)

Champ	Type	Requis
workflowId	string (uuid)	oui
name	string	oui
description	string	oui
category	string | null	non

Schéma JSON

{
  "type": "object",
  "properties": {
    "workflowId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
    "description": { "type": "string", "maxLength": 2000 },
    "category": {
      "anyOf": [
        { "type": "string", "minLength": 1, "maxLength": 60 },
        { "type": "null" }
      ]
    }
  },
  "required": [ "workflowId", "name", "description" ]
}

Réponses

201 — Le template.

Champ	Type	Requis
template	object	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "name": { "type": "string" },
        "description": { "type": "string" },
        "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
        "enabled": { "type": "boolean" },
        "nodeTypes": { "type": "array", "items": { "type": "string" } },
        "requiresProviders": { "type": "array", "items": { "type": "string" } },
        "createdBy": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            { "type": "null" }
          ]
        },
        "createdAt": {
          "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))$"
        },
        "updatedAt": {
          "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))$"
        },
        "installCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
      },
      "required": [
        "id",
        "name",
        "description",
        "category",
        "enabled",
        "nodeTypes",
        "requiresProviders",
        "createdBy",
        "createdAt",
        "updatedAt",
        "installCount"
      ],
      "additionalProperties": false
    }
  },
  "required": [ "template" ],
  "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, templates.workflow_not_found, templates.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.

PUT /api/v1/admin/templates/{id}

Modifier les métadonnées d’un template

Partiel, et métadonnées seulement (nom, description, catégorie, actif). category: null l’efface, une clé absente la laisse. Le graphe ne change jamais : promouvoir à nouveau pour un autre.

Accès — Session de membre ou clé d’API portant admin:write (rôle administrateur requis).

Paramètres

Nom	Où	Type	Requis
id	chemin	string	oui

Corps de la requête (application/json)

Champ	Type	Requis
name	string	non
description	string	non
category	string | null	non
enabled	boolean	non

Schéma JSON

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
    "description": { "type": "string", "maxLength": 2000 },
    "category": {
      "anyOf": [
        { "type": "string", "minLength": 1, "maxLength": 60 },
        { "type": "null" }
      ]
    },
    "enabled": { "type": "boolean" }
  }
}

Réponses

200 — Le template, mis à jour.

Champ	Type	Requis
template	object	oui

Même schéma que POST /api/v1/admin/templates/promote.

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, templates.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.

DELETE /api/v1/admin/templates/{id}

Supprimer un template

Les workflows déjà installés depuis lui sont intacts : chacun a reçu sa copie du graphe.

Accès — Session de membre ou clé d’API portant admin:write (rôle administrateur requis).

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 — templates.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/gallery

La galerie publique, vue du membre

Si une galerie est configurée (GALLERY_URL), le profil créateur lié à l’appelant, et si l’instance peut soumettre par son lien control plane.

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

Réponses

200 — L’état de la galerie.

Champ	Type	Requis
enabled	boolean	oui
galleryUrl	string (uri) | null	oui
creator	object | null	oui
instanceLink	boolean	oui
productVersion	string	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "enabled": { "type": "boolean" },
    "galleryUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] },
    "creator": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "slug": { "type": "string" },
            "name": { "type": "string" },
            "profileUrl": {
              "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ]
            }
          },
          "required": [ "slug", "name", "profileUrl" ],
          "additionalProperties": false
        },
        { "type": "null" }
      ]
    },
    "instanceLink": { "type": "boolean" },
    "productVersion": { "type": "string" }
  },
  "required": [ "enabled", "galleryUrl", "creator", "instanceLink", "productVersion" ],
  "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.

PUT /api/v1/gallery/creator-token

Lier un profil créateur

Vérifie le jeton de créateur auprès de la galerie et le garde scellé sur l’instance. Session seulement : un jeton est un identifiant personnel.

Accès — Session de membre seulement : les clés d’API sont refusées (api_key.session_required).

Corps de la requête (application/json)

Champ	Type	Requis
token	string	oui

Schéma JSON

{
  "type": "object",
  "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 200 } },
  "required": [ "token" ]
}

Réponses

200 — L’état mis à jour.

Champ	Type	Requis
enabled	boolean	oui
galleryUrl	string (uri) | null	oui
creator	object | null	oui
instanceLink	boolean	oui
productVersion	string	oui

Même schéma que GET /api/v1/gallery.

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, gallery.disabled, gallery.invalid_token, gallery.encryption_disabled, gallery.unreachable. 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/gallery/creator-token

Délier le profil créateur

Accès — Session de membre seulement : les clés d’API sont refusées (api_key.session_required).

Réponses

204 — Délié.

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/gallery/export

Aperçu d’un workflow en template public

Exporte un workflow (sa version publiée, ou son brouillon) ou un template d’organisation au format public : connexions, boîtes, tables et ressources distantes deviennent des emplacements, adresses et secrets sont réécrits. Rien n’est envoyé ; le rapport liste ce qui a été retiré.

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

Corps de la requête (application/json)

Champ	Type	Requis
source	object	oui
metadata	object	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "source": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": { "type": "string", "const": "workflow" },
            "id": { "type": "string", "minLength": 1 },
            "version": { "type": "string", "enum": [ "published", "draft" ] }
          },
          "required": [ "kind", "id" ]
        },
        {
          "type": "object",
          "properties": {
            "kind": { "type": "string", "const": "orgTemplate" },
            "id": { "type": "string", "minLength": 1 }
          },
          "required": [ "kind", "id" ]
        }
      ]
    },
    "metadata": {
      "type": "object",
      "properties": {
        "title": {
          "type": "object",
          "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
          "required": [ "en", "fr" ]
        },
        "description": {
          "type": "object",
          "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
          "required": [ "en", "fr" ]
        },
        "category": {
          "type": "string",
          "enum": [
            "triage",
            "replies",
            "extraction",
            "follow-ups",
            "approvals",
            "sync",
            "notifications",
            "other"
          ]
        },
        "useCases": {
          "default": [],
          "maxItems": 6,
          "type": "array",
          "items": { "type": "string", "minLength": 1, "maxLength": 60 }
        }
      },
      "required": [ "title", "description", "category" ]
    }
  },
  "required": [ "source", "metadata" ]
}

Réponses

200 — Le template assaini et son rapport.

Champ	Type	Requis
template	object	oui
report	object[]	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "formatVersion": { "type": "number", "const": 1 },
        "title": {
          "type": "object",
          "properties": {
            "en": { "type": "string", "maxLength": 60 },
            "fr": { "type": "string", "maxLength": 60 }
          },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "description": {
          "type": "object",
          "properties": {
            "en": { "type": "string", "maxLength": 4000 },
            "fr": { "type": "string", "maxLength": 4000 }
          },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "category": {
          "type": "string",
          "enum": [
            "triage",
            "replies",
            "extraction",
            "follow-ups",
            "approvals",
            "sync",
            "notifications",
            "other"
          ]
        },
        "useCases": {
          "default": [],
          "maxItems": 6,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 60,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          }
        },
        "integrations": {
          "default": [],
          "maxItems": 30,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 80,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          }
        },
        "nodeTypes": {
          "default": [],
          "maxItems": 200,
          "type": "array",
          "items": { "type": "string", "minLength": 1, "maxLength": 128 }
        },
        "minProductVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
        "placeholders": {
          "default": [],
          "maxItems": 500,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "nodeId": { "type": "string", "minLength": 1, "maxLength": 64 },
              "nodeType": { "type": "string", "minLength": 1, "maxLength": 128 },
              "param": { "type": "string", "minLength": 1, "maxLength": 200 },
              "kind": {
                "type": "string",
                "enum": [
                  "connection",
                  "mailbox",
                  "table",
                  "resource",
                  "address",
                  "secret"
                ]
              },
              "credentialType": { "type": "string", "maxLength": 80 },
              "capability": { "type": "string", "maxLength": 80 },
              "provider": { "type": "string", "maxLength": 80 },
              "resource": { "type": "string", "maxLength": 80 }
            },
            "required": [ "nodeId", "nodeType", "param", "kind" ],
            "additionalProperties": false
          }
        },
        "graph": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "const": "template" },
            "workflowId": { "type": "string", "const": "template" },
            "nodes": {
              "minItems": 1,
              "maxItems": 200,
              "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": {
              "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": {
              "maxItems": 50,
              "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
              }
            }
          },
          "required": [ "id", "workflowId", "nodes", "connections" ],
          "additionalProperties": false
        }
      },
      "required": [
        "formatVersion",
        "title",
        "description",
        "category",
        "useCases",
        "integrations",
        "nodeTypes",
        "minProductVersion",
        "placeholders",
        "graph"
      ],
      "additionalProperties": false
    },
    "report": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nodeId": { "type": "string" },
          "nodeType": { "type": "string" },
          "param": { "type": "string" },
          "action": { "type": "string", "enum": [ "placeholder", "scrubbed" ] },
          "kind": {
            "type": "string",
            "enum": [
              "connection",
              "mailbox",
              "table",
              "resource",
              "address",
              "secret"
            ]
          }
        },
        "required": [ "nodeId", "nodeType", "param", "action", "kind" ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "template", "report" ],
  "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, gallery.source_not_found, gallery.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.

POST /api/v1/gallery/submissions

Soumettre un template à la galerie

Exporte (exactement comme l’aperçu) et soumet à la galerie, au nom du créateur lié à l’appelant ou, sur une instance cloud, par le lien control plane. La galerie modère : rien n’est public à la soumission.

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

Corps de la requête (application/json)

Champ	Type	Requis
source	object	oui
metadata	object	oui
via	"creator" | "instance"	non
licenseAccepted	true	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "source": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": { "type": "string", "const": "workflow" },
            "id": { "type": "string", "minLength": 1 },
            "version": { "type": "string", "enum": [ "published", "draft" ] }
          },
          "required": [ "kind", "id" ]
        },
        {
          "type": "object",
          "properties": {
            "kind": { "type": "string", "const": "orgTemplate" },
            "id": { "type": "string", "minLength": 1 }
          },
          "required": [ "kind", "id" ]
        }
      ]
    },
    "metadata": {
      "type": "object",
      "properties": {
        "title": {
          "type": "object",
          "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
          "required": [ "en", "fr" ]
        },
        "description": {
          "type": "object",
          "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
          "required": [ "en", "fr" ]
        },
        "category": {
          "type": "string",
          "enum": [
            "triage",
            "replies",
            "extraction",
            "follow-ups",
            "approvals",
            "sync",
            "notifications",
            "other"
          ]
        },
        "useCases": {
          "default": [],
          "maxItems": 6,
          "type": "array",
          "items": { "type": "string", "minLength": 1, "maxLength": 60 }
        }
      },
      "required": [ "title", "description", "category" ]
    },
    "via": {
      "default": "creator",
      "type": "string",
      "enum": [ "creator", "instance" ]
    },
    "licenseAccepted": { "type": "boolean", "const": true }
  },
  "required": [ "source", "metadata", "licenseAccepted" ]
}

Réponses

201 — La soumission.

Champ	Type	Requis
submissionId	string	oui
status	string	oui
templateSlug	string | null	oui
url	string (uri) | null	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "submissionId": { "type": "string" },
    "status": { "type": "string" },
    "templateSlug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }
  },
  "required": [ "submissionId", "status", "templateSlug", "url" ],
  "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, gallery.disabled, gallery.not_linked, gallery.source_not_found, gallery.invalid_graph, gallery.invalid_token, gallery.rejected, gallery.unreachable. 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/gallery/templates

Parcourir la galerie publique

Les templates publiés dans la galerie publique, lus par l’instance (le navigateur n’appelle jamais la galerie) : recherche plein texte, filtres par catégorie, intégration et cas d’usage, tri par popularité ou par date, pagination. Les réponses sont gardées une minute. Sans GALLERY_URL, 404 gallery.disabled.

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

Paramètres

Nom	Où	Type	Requis
q	requête	string	non
category	requête	"triage" | "replies" | "extraction" | "follow-ups" | "approvals" | "sync" | "notifications" | "other"	non
integration	requête	string	non
useCase	requête	string	non
sort	requête	"popular" | "recent"	non
page	requête	integer	non

Réponses

200 — Une page de templates.

Champ	Type	Requis
templates	object[]	oui
page	integer	oui
total	integer	oui
pageCount	integer	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "templates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": {
            "type": "object",
            "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
            "required": [ "en", "fr" ],
            "additionalProperties": false
          },
          "description": {
            "type": "object",
            "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
            "required": [ "en", "fr" ],
            "additionalProperties": false
          },
          "category": {
            "type": "string",
            "enum": [
              "triage",
              "replies",
              "extraction",
              "follow-ups",
              "approvals",
              "sync",
              "notifications",
              "other"
            ]
          },
          "useCases": { "type": "array", "items": { "type": "string" } },
          "integrations": { "type": "array", "items": { "type": "string" } },
          "nodeTypes": { "type": "array", "items": { "type": "string" } },
          "importCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "author": {
            "type": "object",
            "properties": {
              "slug": { "type": "string" },
              "name": { "type": "string" },
              "official": { "type": "boolean" }
            },
            "required": [ "slug", "name", "official" ],
            "additionalProperties": false
          },
          "pageUrl": {
            "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ]
          },
          "documentUrl": { "type": "string", "format": "uri" }
        },
        "required": [
          "slug",
          "title",
          "description",
          "category",
          "useCases",
          "integrations",
          "nodeTypes",
          "importCount",
          "publishedAt",
          "author",
          "pageUrl",
          "documentUrl"
        ],
        "additionalProperties": false
      }
    },
    "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
    "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
    "pageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
  },
  "required": [ "templates", "page", "total", "pageCount" ],
  "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, gallery.disabled, gallery.unreachable. 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/gallery/templates/{slug}

Un template de la galerie publique

Sa carte, son document (le graphe à prévisualiser) et ce que cette instance demanderait pour l’importer : prérequis à compléter, nœuds inconnus, compatibilité de version. Rien n’est créé ; POST /api/v1/gallery/import avec documentUrl crée le brouillon.

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

Paramètres

Nom	Où	Type	Requis
slug	chemin	string	oui

Réponses

200 — Le template et son inspection.

Champ	Type	Requis
summary	object	oui
template	object	oui
inspection	object	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "object",
      "properties": {
        "slug": { "type": "string" },
        "title": {
          "type": "object",
          "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "description": {
          "type": "object",
          "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "category": {
          "type": "string",
          "enum": [
            "triage",
            "replies",
            "extraction",
            "follow-ups",
            "approvals",
            "sync",
            "notifications",
            "other"
          ]
        },
        "useCases": { "type": "array", "items": { "type": "string" } },
        "integrations": { "type": "array", "items": { "type": "string" } },
        "nodeTypes": { "type": "array", "items": { "type": "string" } },
        "importCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
        "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
        "author": {
          "type": "object",
          "properties": {
            "slug": { "type": "string" },
            "name": { "type": "string" },
            "official": { "type": "boolean" }
          },
          "required": [ "slug", "name", "official" ],
          "additionalProperties": false
        },
        "pageUrl": {
          "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ]
        },
        "documentUrl": { "type": "string", "format": "uri" }
      },
      "required": [
        "slug",
        "title",
        "description",
        "category",
        "useCases",
        "integrations",
        "nodeTypes",
        "importCount",
        "publishedAt",
        "author",
        "pageUrl",
        "documentUrl"
      ],
      "additionalProperties": false
    },
    "template": {
      "type": "object",
      "properties": {
        "formatVersion": { "type": "number", "const": 1 },
        "title": {
          "type": "object",
          "properties": {
            "en": { "type": "string", "maxLength": 60 },
            "fr": { "type": "string", "maxLength": 60 }
          },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "description": {
          "type": "object",
          "properties": {
            "en": { "type": "string", "maxLength": 4000 },
            "fr": { "type": "string", "maxLength": 4000 }
          },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "category": {
          "type": "string",
          "enum": [
            "triage",
            "replies",
            "extraction",
            "follow-ups",
            "approvals",
            "sync",
            "notifications",
            "other"
          ]
        },
        "useCases": {
          "default": [],
          "maxItems": 6,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 60,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          }
        },
        "integrations": {
          "default": [],
          "maxItems": 30,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 80,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          }
        },
        "nodeTypes": {
          "default": [],
          "maxItems": 200,
          "type": "array",
          "items": { "type": "string", "minLength": 1, "maxLength": 128 }
        },
        "minProductVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
        "placeholders": {
          "default": [],
          "maxItems": 500,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "nodeId": { "type": "string", "minLength": 1, "maxLength": 64 },
              "nodeType": { "type": "string", "minLength": 1, "maxLength": 128 },
              "param": { "type": "string", "minLength": 1, "maxLength": 200 },
              "kind": {
                "type": "string",
                "enum": [
                  "connection",
                  "mailbox",
                  "table",
                  "resource",
                  "address",
                  "secret"
                ]
              },
              "credentialType": { "type": "string", "maxLength": 80 },
              "capability": { "type": "string", "maxLength": 80 },
              "provider": { "type": "string", "maxLength": 80 },
              "resource": { "type": "string", "maxLength": 80 }
            },
            "required": [ "nodeId", "nodeType", "param", "kind" ],
            "additionalProperties": false
          }
        },
        "graph": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "const": "template" },
            "workflowId": { "type": "string", "const": "template" },
            "nodes": {
              "minItems": 1,
              "maxItems": 200,
              "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": {
              "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": {
              "maxItems": 50,
              "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
              }
            }
          },
          "required": [ "id", "workflowId", "nodes", "connections" ],
          "additionalProperties": false
        }
      },
      "required": [
        "formatVersion",
        "title",
        "description",
        "category",
        "useCases",
        "integrations",
        "nodeTypes",
        "minProductVersion",
        "placeholders",
        "graph"
      ],
      "additionalProperties": false
    },
    "inspection": {
      "type": "object",
      "properties": {
        "prerequisites": {
          "type": "object",
          "properties": {
            "connections": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "mailboxes": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "tables": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "resources": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "addresses": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "secrets": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "connections",
            "mailboxes",
            "tables",
            "resources",
            "addresses",
            "secrets"
          ],
          "additionalProperties": false
        },
        "unknownNodes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "nodeId": { "type": "string" },
              "nodeType": { "type": "string" },
              "version": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "reason": { "type": "string", "enum": [ "type", "version" ] }
            },
            "required": [ "nodeId", "nodeType", "version", "reason" ],
            "additionalProperties": false
          }
        },
        "versionCompatible": { "type": "boolean" },
        "minProductVersion": { "type": "string" },
        "productVersion": { "type": "string" },
        "ready": { "type": "boolean" }
      },
      "required": [
        "prerequisites",
        "unknownNodes",
        "versionCompatible",
        "minProductVersion",
        "productVersion",
        "ready"
      ],
      "additionalProperties": false
    }
  },
  "required": [ "summary", "template", "inspection" ],
  "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 — request.bad_request, gallery.disabled, gallery.template_not_found, gallery.invalid_template, gallery.unreachable. 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/gallery/import/preview

Inspecter un template avant de l’importer

Depuis une URL de la galerie (template= de l’écran d’import) ou un document collé : les prérequis à compléter (connexions, boîtes, tables…), les nœuds que cette instance ne connaît pas, la compatibilité de version. Rien n’est créé.

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

Corps de la requête (application/json)

Type : object

{
  "anyOf": [
    {
      "type": "object",
      "properties": { "url": { "type": "string", "format": "uri" } },
      "required": [ "url" ]
    },
    {
      "type": "object",
      "properties": { "template": {} },
      "required": [ "template" ]
    }
  ]
}

Réponses

200 — L’inspection.

Champ	Type	Requis
template	object	oui
inspection	object	oui
sourceUrl	string (uri) | null	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "formatVersion": { "type": "number", "const": 1 },
        "title": {
          "type": "object",
          "properties": {
            "en": { "type": "string", "maxLength": 60 },
            "fr": { "type": "string", "maxLength": 60 }
          },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "description": {
          "type": "object",
          "properties": {
            "en": { "type": "string", "maxLength": 4000 },
            "fr": { "type": "string", "maxLength": 4000 }
          },
          "required": [ "en", "fr" ],
          "additionalProperties": false
        },
        "category": {
          "type": "string",
          "enum": [
            "triage",
            "replies",
            "extraction",
            "follow-ups",
            "approvals",
            "sync",
            "notifications",
            "other"
          ]
        },
        "useCases": {
          "default": [],
          "maxItems": 6,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 60,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          }
        },
        "integrations": {
          "default": [],
          "maxItems": 30,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 80,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          }
        },
        "nodeTypes": {
          "default": [],
          "maxItems": 200,
          "type": "array",
          "items": { "type": "string", "minLength": 1, "maxLength": 128 }
        },
        "minProductVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
        "placeholders": {
          "default": [],
          "maxItems": 500,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "nodeId": { "type": "string", "minLength": 1, "maxLength": 64 },
              "nodeType": { "type": "string", "minLength": 1, "maxLength": 128 },
              "param": { "type": "string", "minLength": 1, "maxLength": 200 },
              "kind": {
                "type": "string",
                "enum": [
                  "connection",
                  "mailbox",
                  "table",
                  "resource",
                  "address",
                  "secret"
                ]
              },
              "credentialType": { "type": "string", "maxLength": 80 },
              "capability": { "type": "string", "maxLength": 80 },
              "provider": { "type": "string", "maxLength": 80 },
              "resource": { "type": "string", "maxLength": 80 }
            },
            "required": [ "nodeId", "nodeType", "param", "kind" ],
            "additionalProperties": false
          }
        },
        "graph": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "const": "template" },
            "workflowId": { "type": "string", "const": "template" },
            "nodes": {
              "minItems": 1,
              "maxItems": 200,
              "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": {
              "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": {
              "maxItems": 50,
              "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
              }
            }
          },
          "required": [ "id", "workflowId", "nodes", "connections" ],
          "additionalProperties": false
        }
      },
      "required": [
        "formatVersion",
        "title",
        "description",
        "category",
        "useCases",
        "integrations",
        "nodeTypes",
        "minProductVersion",
        "placeholders",
        "graph"
      ],
      "additionalProperties": false
    },
    "inspection": {
      "type": "object",
      "properties": {
        "prerequisites": {
          "type": "object",
          "properties": {
            "connections": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "mailboxes": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "tables": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "resources": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "addresses": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            },
            "secrets": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "nodeId": { "type": "string" },
                  "nodeType": { "type": "string" },
                  "param": { "type": "string" },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "connection",
                      "mailbox",
                      "table",
                      "resource",
                      "address",
                      "secret"
                    ]
                  },
                  "credentialType": { "type": "string" },
                  "capability": { "type": "string" },
                  "provider": { "type": "string" },
                  "resource": { "type": "string" }
                },
                "required": [ "nodeId", "nodeType", "param", "kind" ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "connections",
            "mailboxes",
            "tables",
            "resources",
            "addresses",
            "secrets"
          ],
          "additionalProperties": false
        },
        "unknownNodes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "nodeId": { "type": "string" },
              "nodeType": { "type": "string" },
              "version": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "reason": { "type": "string", "enum": [ "type", "version" ] }
            },
            "required": [ "nodeId", "nodeType", "version", "reason" ],
            "additionalProperties": false
          }
        },
        "versionCompatible": { "type": "boolean" },
        "minProductVersion": { "type": "string" },
        "productVersion": { "type": "string" },
        "ready": { "type": "boolean" }
      },
      "required": [
        "prerequisites",
        "unknownNodes",
        "versionCompatible",
        "minProductVersion",
        "productVersion",
        "ready"
      ],
      "additionalProperties": false
    },
    "sourceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }
  },
  "required": [ "template", "inspection", "sourceUrl" ],
  "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, gallery.disabled, gallery.untrusted_url, gallery.template_not_found, gallery.invalid_template, gallery.unreachable. 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/gallery/import

Importer un template en nouveau brouillon

Crée un workflow en brouillon, propriété du membre, à partir du template ; les emplacements restent vides, l’éditeur les signale. Un template qui utilise des nœuds inconnus de cette instance est refusé (409 gallery.not_importable). Chaque import depuis une URL de la galerie est compté une fois par instance.

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

Corps de la requête (application/json)

Type : object

{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "url": { "type": "string", "format": "uri" },
        "name": { "type": "string", "minLength": 1, "maxLength": 200 }
      },
      "required": [ "url" ]
    },
    {
      "type": "object",
      "properties": {
        "template": {},
        "name": { "type": "string", "minLength": 1, "maxLength": 200 }
      },
      "required": [ "template" ]
    }
  ]
}

Réponses

201 — L’identifiant du nouveau workflow.

Champ	Type	Requis
workflowId	string	oui

Schéma JSON

{
  "type": "object",
  "properties": { "workflowId": { "type": "string" } },
  "required": [ "workflowId" ],
  "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, gallery.disabled, gallery.untrusted_url, gallery.template_not_found, gallery.invalid_template, gallery.not_importable, gallery.unreachable. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.