Points de terminaison Workflow API

La Workflows API reflète l’intégralité de l’expérience /workflows de l’application web. Vous pouvez lister les workflows, inspecter toutes les données de détail d’un workflow, mettre à jour l’état du builder/de la configuration, lire les runs, les analytics, les entités liées et l’historique de versions spécifiques à un workflow, et revenir à une version précédente.

Couverture de parité avec l’UI

• Page liste des workflows : noms, descriptions, résumé de l’outil CLI, horodatages, pagination, duplication, suppression et suppression en masse.
• Détail du workflow / Configuration : enregistrement complet du workflow, config sandbox par défaut, étapes de pipeline, étapes de pipeline de personas, graphe de workflow, horodatages.
• Détail du workflow / Builder : payloads persistésworkflowGraph et pipelineStepsd’exécution.
• Détail du workflow / Runs : runs scopés au workflow avec pagination.
• Détail du workflow / Analytics : KPI, répartition des coûts, série de taux de succès, runs dans le temps, et entités liées.
• Détail du workflow / Related : personas, issues et versions de learnings liées.
• Détail du workflow / Versions : historique de versions et retour en arrière.
• Dialogue Run Workflow : utilisez POST /api/v1/runs/start pour déclencher un run à partir d’un workflow. Pour joindre des images de référence d’abord, demandez une URL d’upload via POST /api/v1/files/upload-url.

Points de terminaison de lecture

GET /api/v1/workflows/list

Renvoie les workflows non supprimés du projet actuel, y compris les métadonnées d’affichage utilisées par l’UI de tableau.

Paramètres de query :

• limit (optionnel) - taille de page, par défaut 50, max 100
• cursor (optionnel) - curseur de la réponse précédente

GET /api/v1/workflows/get

Renvoie le document complet du workflow utilisé par la page de détail, y compris la config, les étapes de pipeline, les étapes de pipeline de personas et le graphe de workflow enregistré.

• id (requis) - ID du workflow

GET /api/v1/workflows/runs

Renvoie l’onglet Runs d’un workflow, y compris le statut, le nom de branche, l’URL de PR, le numéro/l’ID d’affichage du run, les horodatages et les métadonnées de pagination.

• id (requis) - ID du workflow
• limit (optionnel) - par défaut 50, max 100
• cursor (optionnel) - curseur de la réponse précédente

GET /api/v1/workflows/analytics

Renvoie le payload de l’onglet Analytics d’un workflow.

• id (requis) - ID du workflow
• days (optionnel) - fenêtre de lookback, par défaut 30
• granularity (optionnel) - daily, weekly, ou monthly

GET /api/v1/workflows/related

Renvoie le payload de l’onglet Related d’un workflow : personas, issues et versions de learnings liées aux runs du workflow.

• id (requis) - ID du workflow

GET /api/v1/workflows/versions

Renvoie le payload de l’onglet Versions d’un workflow, y compris le numéro de version actuel et les métadonnées de snapshot pour chaque version enregistrée.

• id (requis) - ID du workflow

Points de terminaison d’écriture

POST /api/v1/workflows/create

Crée un blueprint de workflow.

Les champs d’écriture pris en charge incluent :

• name (requis)
• description
• type
• defaultConfig
• maxIterations
• pipelineSteps
• personaPipelineSteps
• workflowGraph

Au moins l’un de pipelineSteps ou personaPipelineSteps doit être fourni.

POST /api/v1/workflows/update

Met à jour n’importe quel sous-ensemble de champs du workflow. Les mises à jour via l’API snapshotent aussi l’état précédent du workflow dans l’historique de versions, afin que l’onglet Versions reste synchronisé avec les changements faits hors de l’UI.

{
  "workflowId": "...",
  "name": "Release hardening",
  "defaultConfig": {
    "templateId": "claude",
    "timeoutMs": 3600000,
    "memoryMb": 4096,
    "cpuCount": 4
  },
  "pipelineSteps": [
    { "type": "designer", "cliId": "claude", "model": "claude-opus-4-7" },
    { "type": "checker", "cliId": "claude", "model": "claude-sonnet-4-6" }
  ],
  "workflowGraph": { "nodes": [], "edges": [] }
}

POST /api/v1/workflows/versions/revert

Revient à une version précédente d’un workflow. L’API snapshote d’abord l’état actuel, exactement comme l’UI web.

{ "workflowId": "...", "versionId": "..." }

POST /api/v1/workflows/duplicate

Duplique un workflow, y compris les étapes de pipeline de personas, les étapes d’exécution et le graphe du builder enregistré.

POST /api/v1/workflows/delete

Supprime un workflow (soft-delete).

POST /api/v1/workflows/restore

Restaure un workflow supprimé en soft-delete.

POST /api/v1/workflows/permanent-delete

Supprime définitivement un workflow.

POST /api/v1/workflows/rename

Renomme un workflow.

POST /api/v1/workflows/bulk-delete

Suppression en masse (soft-delete) de workflows.

Exécuter un workflow depuis l’API

Le bouton Run des pages liste/détail des workflows correspond à POST /api/v1/runs/start. Les champs de requête typiques incluent :

• workflowId (requis)
• prompt (requis)
• githubRepoUrl (optionnel)
• branchName (optionnel)
• config (override optionnel de la config sandbox)
• referenceImageIds (images uploadées, optionnel)

Pour joindre des images comme le fait l’UI, demandez d’abord une URL d’upload avec POST /api/v1/files/upload-url, uploadez le binaire vers l’URL renvoyée, puis passez les valeurs storageId résultantes en tant que referenceImageIds lors du démarrage du run.

Modèle de données du workflow

Les réponses de workflow peuvent inclure :

• name, description, type
• defaultConfig incluant les champs outil/modèle/ressources
• pipelineSteps et personaPipelineSteps
• workflowGraph pour l’onglet Builder
• defaultCheckerInstructions et defaultOptimizerInstructions
• createdAt, updatedAt, deletedAt
• display avec des champs comme les libellés d’outil CLI utilisés par l’UI de liste