Workflows

Un workflow enchaîne plusieurs applications en un seul flux : un déclencheur, puis les applications qui s'exécutent l'une après l'autre, avec des conditions qui aiguillent selon la réponse de l'étape précédente. L'API est la surface de création — vous créez le flux, vous dessinez ou décrivez ses étapes, vous relisez s'il peut réellement s'exécuter, vous l'activez et vous le publiez. C'est le même objet que celui que l'espace de travail dessine sur sa zone de travail : un flux écrit ici s'ouvre dans l'éditeur de flux, et un flux dessiné là-bas se lit ici.

Les appels

<workflow_id> est un identifiant de workflow, préfixé wkfl_.

Important — Aucun appel ne lance un workflow. Une exécution est avancée par l'espace de travail, une étape par chargement de page : une exécution créée de l'extérieur resterait en attente et n'avancerait jamais. Lancez un flux depuis sa page dans l'espace de travail. Pour lancer une seule application depuis l'API, utilisez plutôt Exécutions.

L'objet workflow

Le dessin

Le dessin est un ensemble de nœuds (nodes) reliés par des liens (edges).

Un flux est prêt à s'exécuter lorsqu'il porte exactement un déclencheur, au moins une application, que chaque étape applicative nomme une application activée de ce projet dotée d'un modèle utilisable, que chaque champ obligatoire est alimenté, qu'aucune condition n'est en tête de chaîne, qu'aucune flèche ne referme une boucle et que chaque nœud est atteignable depuis le déclencheur. Lorsqu'une règle est enfreinte, issues la nomme — une règle rattachée à un nœud se lit Step 'n2': ….

Un dessin porte au plus 60 nœuds et 7200 liens.

Note — Tout ce que la zone de travail ne saurait pas dessiner est abandonné, non refusé : un type de nœud inconnu, une coordonnée hors grille, une flèche vers un nœud inexistant, une flèche d'un nœud vers lui-même, une flèche en double. Le graph de la réponse est le dessin tel qu'il a été enregistré : relisez-le pour voir exactement ce qui a été conservé.

Fixer les champs d'une étape

Par défaut, une étape applicative est alimentée par l'étape qui la précède. config.fields remplace ce choix, une entrée par champ, indexée par le name du champ ou par son identifiant madi_.

Une valeur seule est un raccourci pour static : "tone": "formal" équivaut à "tone": { "source": "static", "value": "formal" }. Un objet vide prend la valeur par défaut — previous pour un texte, input pour un fichier.

Créer un workflow

POST /v1/workflow/create accepte soit un dessin, soit une liste ordonnée d'étapes.

Envoyez graph lorsque vous disposez déjà d'un dessin, steps lorsque vous voulez simplement que les applications s'exécutent dans l'ordre. Chaque étape s'écrit { "app": "mapp_… ou un nom", "fields": {…} } ou { "condition": { "operator": "contains", "value": "urgent" } }. Les étapes sont reliées entre elles dans l'ordre où vous les envoyez, un déclencheur est créé en tête, et une condition passe à l'étape suivante sur sa branche true. Ajoutez "on_false" à une condition, en nommant une autre étape par son numéro, pour relier l'autre branche.

curl -X POST https://api.think.ultineo.com/v1/workflow/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage then answer",
    "description": "Sort the incoming message, then draft the reply.",
    "steps": [
      { "app": "mapp_0ceacb46e5b3a99e91b6" },
      { "condition": { "operator": "contains", "value": "urgent" } },
      { "app": "mapp_7d3f81b0c25e94a6f01d" }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "wkfl_4a91c7e0d25b83f6a1cd",
    "object": "workflow",
    "name": "Triage then answer",
    "description": "Sort the incoming message, then draft the reply.",
    "type": "private",
    "status": "activated",
    "trigger": "manual",
    "counts": { "app": 2, "condition": 1 },
    "apps": [
      { "id": "mapp_0ceacb46e5b3a99e91b6", "name": "Message triage" },
      { "id": "mapp_7d3f81b0c25e94a6f01d", "name": "Reply drafter" }
    ],
    "graph": {
      "nodes": [
        { "key": "n1", "type": "trigger", "x": 60, "y": 220, "config": {} },
        { "key": "n2", "type": "app", "x": 360, "y": 220, "config": { "app_ident": "mapp_0ceacb46e5b3a99e91b6" } },
        { "key": "n3", "type": "condition", "x": 660, "y": 220, "config": { "operator": "contains", "value": "urgent" } },
        { "key": "n4", "type": "app", "x": 960, "y": 220, "config": { "app_ident": "mapp_7d3f81b0c25e94a6f01d" } }
      ],
      "edges": [
        { "from": "n1", "to": "n2", "branch": "" },
        { "from": "n2", "to": "n3", "branch": "" },
        { "from": "n3", "to": "n4", "branch": "true" }
      ]
    },
    "ready": true,
    "note": null,
    "created_at": 1754209200
  }
}

La création est le seul endroit où un flux invalide est refusé : le dessin n'existe pas encore, il n'y a donc rien à perdre à le redemander.

Envoyer à la fois graph et steps n'est pas une erreur : le dessin l'emporte, et la réponse le dit dans note : Both 'graph' and 'steps' were provided: 'graph' was used and 'steps' ignored.

Note — Une étape ne peut nommer qu'une application de votre propre projet, même publiée par un autre : l'éditeur de flux ne sait pas dessiner une étape sur une application qui ne lui appartient pas, et l'étape serait effacée à la première ouverture du flux. Copiez d'abord l'application dans votre projet.

Lister vos workflows

GET /v1/workflow/list renvoie les flux du projet, du plus récent au plus ancien. Les flux supprimés en sont exclus.

curl "https://api.think.ultineo.com/v1/workflow/list?limit=2" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "wkfl_4a91c7e0d25b83f6a1cd",
        "object": "workflow",
        "name": "Triage then answer",
        "description": "Sort the incoming message, then draft the reply.",
        "type": "private",
        "status": "activated",
        "trigger": "manual",
        "counts": { "app": 2, "condition": 1 },
        "apps": [
          { "id": "mapp_0ceacb46e5b3a99e91b6", "name": "Message triage" },
          { "id": "mapp_7d3f81b0c25e94a6f01d", "name": "Reply drafter" }
        ],
        "runs": { "total": 12, "private": 12, "public": 0 },
        "created_at": 1754209200,
        "updated_at": 1754212800
      }
    ],
    "total": 7
  }
}

Une ligne de liste ne porte ni graph, ni ready, ni issues : une page de dessins fait une réponse volumineuse, et la validité coûte plusieurs requêtes par flux. Consultez un flux pour obtenir les trois.

Consulter un workflow

GET /v1/workflow/detail/<workflow_id> renvoie le flux entier, dessin compris.

curl https://api.think.ultineo.com/v1/workflow/detail/wkfl_4a91c7e0d25b83f6a1cd \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

Le graph que vous relisez est le dessin normalisé — celui que la zone de travail et le moteur lisent réellement, débarrassé de tout ce qui n'a pas été reconnu. Le flux d'un autre projet répond 404 et Workflow not found., qu'il existe ou non.

Modifier un workflow

PATCH /v1/workflow/detail/<workflow_id> ne change que les champs présents dans le corps de la requête.

curl -X PATCH https://api.think.ultineo.com/v1/workflow/detail/wkfl_4a91c7e0d25b83f6a1cd \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Triage, then answer" }'

Important — Un PATCH qui porte un graph enregistre toujours le dessin, même lorsque le flux n'est pas valide. Il n'est pas refusé : le flux repasse en draft dans la même écriture et la réponse reste un 200, avec "ready": false, les règles enfreintes sous issues, et note qui indique The graph was saved but does not validate, so the workflow was set back to draft. C'est ce que fait la zone de travail — un flux à moitié dessiné est conservé pour que vous puissiez y revenir. Après un PATCH, lisez donc ready et issues, jamais le code HTTP, pour savoir si le flux peut s'exécuter.

L'activation et la publication, elles, sont des verrous. "status": "activated" et "type": "public" sont tous deux refusés lorsque le dessin final n'est pas valide, et publier un flux exige en plus qu'il soit activé et que chaque application qu'il enchaîne soit elle-même publiée.

Une association de champ qui ne nomme aucun champ de son application est un 422 lorsque vous l'envoyez par steps, mais à l'intérieur d'un graph dessiné à la main elle est abandonnée et signalée dans note — le dessin est conservé dans les deux cas.

Supprimer un workflow

DELETE /v1/workflow/detail/<workflow_id> retire le flux des listes, du catalogue s'il était publié, et de l'espace de travail.

curl -X DELETE https://api.think.ultineo.com/v1/workflow/detail/wkfl_4a91c7e0d25b83f6a1cd \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": { "deleted": true, "id": "wkfl_4a91c7e0d25b83f6a1cd" }
}

La suppression est douce : les exécutions que le flux a déjà produites sont conservées et restent consultables. Supprimer un flux déjà supprimé répond 404 et Workflow not found.