Endpoint Workflow API

Riferimento completo per gli endpoint REST API dei workflow, inclusi CRUD, tab di dettaglio, cronologia versioni, analytics, entità correlate e helper per l’esecuzione dei run.

12 min letto
apiworkflowsversions

La Workflows API rispecchia l’intera esperienza /workflows della web app. Puoi elencare i workflow, ispezionare tutti i dati di dettaglio di un workflow, aggiornare lo stato del builder/della configurazione, leggere run, analytics, entità correlate e cronologia versioni specifici del workflow, e ripristinare un workflow a una versione precedente.

Copertura di parità con l’UI

  • Pagina lista workflow: nomi, descrizioni, riepilogo dello strumento CLI, timestamp, paginazione, duplica, elimina ed eliminazione in blocco.
  • Dettaglio workflow / Configuration: record completo del workflow, config sandbox predefinita, step della pipeline, step della pipeline di persona, grafo del workflow, timestamp.
  • Dettaglio workflow / Builder: payload persistiti di workflowGraph e pipelineSteps di esecuzione.
  • Dettaglio workflow / Runs: run scoped al workflow con paginazione.
  • Dettaglio workflow / Analytics: KPI, ripartizione dei costi, serie del tasso di successo, run nel tempo ed entità correlate.
  • Dettaglio workflow / Related: persona, issue e versioni di learning correlate.
  • Dettaglio workflow / Versions: cronologia delle versioni e ripristino.
  • Dialogo Run Workflow: usa POST /api/v1/runs/start per avviare un run da un workflow. Per allegare prima immagini di riferimento, richiedi un URL di upload tramite POST /api/v1/files/upload-url.

Endpoint di lettura

GET /api/v1/workflows/list

Restituisce i workflow non eliminati del progetto corrente, inclusi i metadati di visualizzazione usati dall’UI della tabella.

Parametri di query:

  • limit (opzionale) - dimensione pagina, predefinito 50, max 100
  • cursor (opzionale) - cursore dalla risposta precedente

GET /api/v1/workflows/get

Restituisce il documento completo del workflow usato dalla pagina di dettaglio, inclusi config, step della pipeline, step della pipeline di persona e il grafo del workflow salvato.

  • id (obbligatorio) - ID del workflow

GET /api/v1/workflows/runs

Restituisce il tab Runs di un workflow, inclusi stato, nome del branch, URL della PR, numero/ID di visualizzazione del run, timestamp e metadati di paginazione.

  • id (obbligatorio) - ID del workflow
  • limit (opzionale) - predefinito 50, max 100
  • cursor (opzionale) - cursore dalla risposta precedente

GET /api/v1/workflows/analytics

Restituisce il payload del tab Analytics di un workflow.

  • id (obbligatorio) - ID del workflow
  • days (opzionale) - finestra di lookback, predefinito 30
  • granularity (opzionale) - daily, weekly, o monthly

GET /api/v1/workflows/related

Restituisce il payload del tab Related di un workflow: persona, issue e versioni di learning collegate ai run del workflow.

  • id (obbligatorio) - ID del workflow

GET /api/v1/workflows/versions

Restituisce il payload del tab Versions di un workflow, incluso il numero di versione corrente e i metadati dello snapshot per ogni versione salvata.

  • id (obbligatorio) - ID del workflow

Endpoint di scrittura

POST /api/v1/workflows/create

Crea un blueprint di workflow.

I campi di scrittura supportati includono:

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

Deve essere fornito almeno uno tra pipelineSteps e personaPipelineSteps.

POST /api/v1/workflows/update

Aggiorna qualsiasi sottoinsieme dei campi del workflow. Gli aggiornamenti via API creano anche uno snapshot dello stato precedente del workflow nella cronologia versioni, così il tab Versions resta sincronizzato con le modifiche fatte fuori dall’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

Ripristina un workflow a una versione precedente. L’API crea prima uno snapshot dello stato corrente, esattamente come l’UI web.

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

POST /api/v1/workflows/duplicate

Duplica un workflow, inclusi gli step della pipeline di persona, gli step di esecuzione e il grafo del builder salvato.

POST /api/v1/workflows/delete

Elimina (soft-delete) un workflow.

POST /api/v1/workflows/restore

Ripristina un workflow eliminato con soft-delete.

POST /api/v1/workflows/permanent-delete

Elimina definitivamente un workflow.

POST /api/v1/workflows/rename

Rinomina un workflow.

POST /api/v1/workflows/bulk-delete

Eliminazione in blocco (soft-delete) di workflow.

Eseguire un workflow dall’API

Il pulsante Run nelle pagine lista/dettaglio dei workflow corrisponde a POST /api/v1/runs/start. I campi tipici della richiesta includono:

  • workflowId (obbligatorio)
  • prompt (obbligatorio)
  • githubRepoUrl (opzionale)
  • branchName (opzionale)
  • config (override opzionale della config sandbox)
  • referenceImageIds (immagini caricate, opzionale)

Per allegare immagini come fa l’UI, richiedi prima un URL di upload con POST /api/v1/files/upload-url, carica il binario all’URL restituito, poi passa i valori storageIdrisultanti come referenceImageIds all’avvio del run.

Modello dati del workflow

Le risposte del workflow possono includere:

  • name, description, type
  • defaultConfig con i campi strumento/modello/risorse
  • pipelineSteps e personaPipelineSteps
  • workflowGraph per il tab Builder
  • defaultCheckerInstructions e defaultOptimizerInstructions
  • createdAt, updatedAt, deletedAt
  • display con campi come le etichette dello strumento CLI usate dall’UI di lista