Workflows

Variables, jeux de données et images

API v115 août 2026·9 min de lecture

Variables de workflow, jeux de données de prévisualisation et images de contenu : les trois ressources CRUD les plus petites et les plus uniformes de l'API workflow.

Chaque endpoint ci-dessous est sous /api/v1/workflows. Lisez Workflows d'abord pour le modèle objet ; lisez Modèles, publication et document pour capabilities, la ressource modèle, et la publication, et Sections et thème pour l'arborescence des sections. Cette page couvre les variables, les jeux de données de prévisualisation et les images de contenu.

Les workflows sont en bêta privée, disponible sur demande à [email protected] ; voir Workflows.

Variables

Cette API lit et écrit toujours ce champ comme name, tout comme le dashboard.

Lister les variables

GET/api/v1/workflows/templates/:id/variables

cURL

curl https://app.doclift.io/api/v1/workflows/templates/100050/variables \
  --header "X-Api-Key: <your-api-key>"

200 OK · application/json

[
  { "id": 200100, "name": "investor_name", "description": "Full legal name", "field_type": "text", "allowed_values": [], "seed_value": "Jane Doe", "required": true, "fields": null }
]

Statut	Corps	Quand
200	tableau	succès
404	`{"error": "..."}`	pas un workflow, archivé, ou d'une autre organisation
403	`{"error": "..."}`	voir Comportement commun

Afficher une variable

GET/api/v1/workflows/templates/:id/variables/:id

200 OK · application/json

{ "id": 200100, "name": "investor_name", "description": "Full legal name", "field_type": "text", "allowed_values": [], "seed_value": "Jane Doe", "required": true, "fields": null }

Statut	Corps	Quand
200	variable	succès
404	`{"error": "..."}`	la variable appartient à un autre workflow, ou le workflow lui-même est hors du périmètre
403	`{"error": "..."}`	voir Comportement commun

Créer une variable

POST/api/v1/workflows/templates/:id/variables

cURL

curl https://app.doclift.io/api/v1/workflows/templates/100050/variables \
  --request POST \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "variable": {
      "name": "investments",
      "description": "One row per investment",
      "field_type": "collection",
      "required": false,
      "fields": [
        { "name": "product", "description": "Product name", "required": true },
        { "name": "amount", "description": "Amount invested", "required": true }
      ]
    }
  }'

201 Created · application/json

{
  "id": 200101,
  "name": "investments",
  "description": "One row per investment",
  "field_type": "collection",
  "allowed_values": [],
  "seed_value": null,
  "required": false,
  "fields": [
    { "name": "product", "description": "Product name", "required": true, "seed_value": null },
    { "name": "amount", "description": "Amount invested", "required": true, "seed_value": null }
  ]
}

Champ	Type	Requis	Notes
name	string	oui	`[a-z0-9_]+` uniquement (refusé, pas réécrit, pour tout autre caractère) ; unique par workflow
description	string	oui
field_type	string	non	un parmi `text`, `checkbox`, `radio`, `select`, `collection` ; défaut `text`
seed_value	string	non	doit être l'une des `allowed_values` si les deux sont renseignées ; refusé sur une `collection`
required	boolean	non	n'a de sens que pour les workflows (voir variables requises)
allowed_values	array	non	refusé sur une `collection`
fields	array	`collection` seulement	non vide, chacune `{name, description, required, seed_value}` ; noms uniques et valides

Les noms sont refusés, pas mis en minuscules

Contrairement aux variables d'un modèle personnalisé, un nom de variable de workflow invalide est rejeté purement et simplement : les espaces superflus sont retirés silencieusement, mais une espace, une majuscule, ou un tiret répondent tous 422. Il n'y a pas de passage en minuscules sur lequel compter.

Statut	Corps	Quand
201	variable	succès
422	`{"errors": ["..."]}`	nom invalide/en double, `field_type` inconnu, une `collection` sans `fields` (ou avec `allowed_values`/`seed_value`), une variable non `collection` portant `fields`, `seed_value` hors de `allowed_values`
400	`{"error": "..."}`	corps sans la clé racine `variable`
404	`{"error": "..."}`	pas un workflow, archivé, ou d'une autre organisation
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

Mettre à jour une variable

PATCH/api/v1/workflows/templates/:id/variables/:id

Mêmes champs qu'à la création.

Renommer ne réécrit rien de ce qui cite l'ancien nom

Une condition ou un token citant cette variable garde l'ancien nom, désormais cassé. Renommer ici ne se répercute jamais. Attendez-vous à une anomalie broken_reference au prochain validate, pas à une réécriture automatique.

Statut	Corps	Quand
200	variable	succès
422	`{"errors": ["..."]}`	mêmes validations qu'à la création
404	`{"error": "..."}`	variable ou workflow hors du périmètre
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

Supprimer une variable

DELETE/api/v1/workflows/templates/:id/variables/:id

cURL

curl https://app.doclift.io/api/v1/workflows/templates/100050/variables/200101 \
  --request DELETE \
  --header "X-Api-Key: <your-api-key>"

204 No Content. Réussit même pendant qu'une condition ou un token cite encore la variable supprimée : la citation reste en place ; elle devient une anomalie bloquante broken_reference la prochaine fois que l'arborescence est validée ou publiée, plutôt que d'être balayée en cascade ou refusée.

Statut	Corps	Quand
204	aucun	succès
404	`{"error": "..."}`	variable ou workflow hors du périmètre
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

Jeux de données

Un jeu de données est une carte nom → valeur plate et nommée, que vous enregistrez pour prévisualiser le workflow : un scalaire par variable, ou un tableau d'objets de ligne plats pour une variable collection. La route est délibérément datasets, pas preview_datasets, le nom du modèle lui-même : ce que vous lisez ici est un exemple de payload que vous pouvez rejouer sur POST /api/v1/document_requests, pas un écran de prévisualisation.

Lister les jeux de données

GET/api/v1/workflows/templates/:id/datasets

200 OK · application/json

[
  { "id": 400100, "name": "natural_person", "values": { "investor_type": "natural" } }
]

Par ordre alphabétique de name.

Statut	Corps	Quand
200	tableau	succès
404	`{"error": "..."}`	pas un workflow, archivé, ou d'une autre organisation
403	`{"error": "..."}`	voir Comportement commun

Afficher un jeu de données

GET/api/v1/workflows/templates/:id/datasets/:id

200 OK · application/json

{ "id": 400100, "name": "natural_person", "values": { "investor_type": "natural" } }

Statut	Corps	Quand
200	jeu de données	succès
404	`{"error": "..."}`	jeu de données ou workflow hors du périmètre
403	`{"error": "..."}`	voir Comportement commun

Créer un jeu de données

POST/api/v1/workflows/templates/:id/datasets

cURL

curl https://app.doclift.io/api/v1/workflows/templates/100050/datasets \
  --request POST \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "dataset": {
      "name": "natural_person",
      "values": {
        "investor_type": "natural",
        "investments": [{ "product": "SCPI", "amount": "10 000 €" }]
      }
    }
  }'

201 Created · application/json

{
  "id": 400100,
  "name": "natural_person",
  "values": { "investor_type": "natural", "investments": [{ "product": "SCPI", "amount": "10 000 €" }] }
}

Champ	Type	Requis	Notes
name	string	oui	≤ 60 caractères, unique par workflow (insensible à la casse)
values	object	oui	plat : un scalaire, ou un tableau d'objets de ligne plats, par clé ; rien imbriqué plus profondément

Statut	Corps	Quand
201	jeu de données	succès
422	`{"errors": ["..."]}`	nom vide/trop long/en double, ou une valeur imbriquée plus profondément qu'un niveau
400	`{"error": "..."}`	corps sans la clé racine `dataset`
404	`{"error": "..."}`	pas un workflow, archivé, ou d'une autre organisation
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

Mettre à jour un jeu de données

PATCH/api/v1/workflows/templates/:id/datasets/:id

Mêmes champs qu'à la création ; réécrit name/values en entier.

Statut	Corps	Quand
200	jeu de données	succès
422	`{"errors": ["..."]}`	mêmes validations qu'à la création
404	`{"error": "..."}`	jeu de données ou workflow hors du périmètre
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

Supprimer un jeu de données

DELETE/api/v1/workflows/templates/:id/datasets/:id

204 No Content.

Statut	Corps	Quand
204	aucun	succès
404	`{"error": "..."}`	jeu de données ou workflow hors du périmètre
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

Images

Des images citées depuis le contenu riche, distinctes des arrière-plans de section (voir Définir l'arrière-plan d'une section). Produire un PDF ne récupère rien sur le réseau, donc une image citée par une URL externe s'imprime comme un cadre vide, silencieusement. Cet endpoint existe pour que chaque image que vous citez en soit une dont l'API possède déjà les octets.

Lister les images

GET/api/v1/workflows/templates/:id/images

200 OK · application/json

[
  { "id": 500100, "token": "9f2a1c7e...", "created_at": "2026-01-15 10:00:00 +0100", "url": "/workflows/images/9f2a1c7e...", "content_type": "image/webp", "byte_size": 84213, "width": 1200, "height": 800 }
]

url est un chemin seul (pas d'hôte), de sorte qu'un workflow copié vers un autre environnement continue de résoudre correctement ses images.

Statut	Corps	Quand
200	tableau	succès
404	`{"error": "..."}`	pas un workflow, archivé, ou d'une autre organisation
403	`{"error": "..."}`	voir Comportement commun

Afficher une image

GET/api/v1/workflows/templates/:id/images/:id

:id ici est le token, pas l'id numérique

Cette route recherche l'image par son token, pas par son id numérique ; un id numérique à cette position répond 404 même si l'image existe sous un token différent et valide. Lire les octets bruts est une route séparée, non authentifiée (GET /workflows/images/:token) ; le token de 32 caractères est la seule chose qui se dresse entre les octets et le monde.

200 OK · application/json

{ "id": 500100, "token": "9f2a1c7e...", "created_at": "2026-01-15 10:00:00 +0100", "url": "/workflows/images/9f2a1c7e...", "content_type": "image/webp", "byte_size": 84213, "width": 1200, "height": 800 }

Statut	Corps	Quand
200	image	succès
404	`{"error": "..."}`	mauvais token, id numérique, ou image d'un autre workflow
403	`{"error": "..."}`	voir Comportement commun

Téléverser une image

POST/api/v1/workflows/templates/:id/images

Mêmes deux formes d'import qu'un arrière-plan : multipart image[file], ou JSON {filename, content_type, data}. Aucune largeur minimale, puisqu'une image de contenu est placée à la taille que vous lui donnez.

cURL

curl https://app.doclift.io/api/v1/workflows/templates/100050/images \
  --request POST \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "image": {
      "filename": "logo.png",
      "content_type": "image/png",
      "data": "data:image/png;base64,<...>"
    }
  }'

201 Created · application/json

{ "id": 500101, "token": "b7c3d4e2...", "created_at": "2026-02-03 11:00:00 +0100", "url": "/workflows/images/b7c3d4e2...", "content_type": "image/webp", "byte_size": 12044, "width": 400, "height": 120 }

Placez l'url renvoyée dans un <img src> à l'intérieur du contenu d'une section : puisque les octets de l'image sont déjà stockés sous cette url, elle s'affiche correctement dans le PDF généré.

Statut	Corps	Quand
201	image	succès
422	`{"errors": ["..."]}`	`missing` (aucun fichier/octet), `too_large` (au-dessus du plafond d'octets de l'organisation), `wrong_type` (vérifié contre les octets réencodés)
400	`{"error": "..."}`	corps sans la clé racine `image`
404	`{"error": "..."}`	pas un workflow, archivé, ou d'une autre organisation
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

Supprimer une image

DELETE/api/v1/workflows/templates/:id/images/:id

204 No Content, adressée par token. Réussit même pendant que le contenu d'une section cite encore l'image : la chaîne <img src> reste exactement telle qu'écrite. Au prochain rendu, tout le cadre <img> est abandonné silencieusement plutôt qu'affiché comme une boîte cassée ; stored.unreachable_images de validate est le seul endroit où une citation en suspens est jamais signalée.

Statut	Corps	Quand
204	aucun	succès
404	`{"error": "..."}`	mauvais token, ou image d'un autre workflow
409	`{"error": "..."}`	verrou d'édition détenu
403	`{"error": "..."}`	voir Comportement commun

PrécédentSections et thème

SuivantValider et publier