Workflow-API-Endpunkte

Vollständige Referenz für die Workflow-REST-API-Endpunkte - inklusive Workflow-CRUD, Workflow-Detail-Tabs, Versionsverlauf, Analytics, zugehörige Entitäten und Workflow-Run-Helfer.

12 Min. Lesezeit
apiworkflowsversions

Die Workflows-API spiegelt die gesamte /workflows-Erfahrung in der Web-App. Sie können Workflows auflisten, vollständige Workflow-Detail-Daten einsehen, Builder-/Konfigurationszustand aktualisieren, workflow-spezifische Runs, Analytics, zugehörige Entitäten, Versionsverlauf lesen und einen Workflow auf eine frühere Version zurücksetzen.

UI-Parität-Abdeckung

  • Workflows-Listenseite: Namen, Beschreibungen, CLI-Tool-Zusammenfassung, Zeitstempel, Paginierung, Duplizieren, Löschen und Massen-Löschen.
  • Workflow-Detail / Konfiguration: vollständiger Workflow-Datensatz, Default-Sandbox-Konfiguration, Pipeline-Schritte, Persona-Pipeline-Schritte, Workflow-Graph, Zeitstempel.
  • Workflow-Detail / Builder: gespeicherte workflowGraph- und Ausführungs-pipelineSteps-Payloads.
  • Workflow-Detail / Runs: workflow-bezogene Runs mit Paginierung.
  • Workflow-Detail / Analytics: KPIs, Kosten-Aufschlüsselung, Erfolgsraten-Serie, Runs-über-Zeit und zugehörige Entitäten.
  • Workflow-Detail / Related: zugehörige Personas, Issues und Learning-Versionen.
  • Workflow-Detail / Versionen: Versionsverlauf und Revert.
  • Run-Workflow-Dialog: Verwenden Sie POST /api/v1/runs/start, um einen Run aus einem Workflow auszulösen. Wenn Sie zunächst Referenzbilder anhängen möchten, fordern Sie eine Upload-URL über POST /api/v1/files/upload-url an.

Lese-Endpunkte

GET /api/v1/workflows/list

Liefert nicht gelöschte Workflows des aktuellen Projekts, inklusive der Anzeige-Metadaten, die die Tabellen-UI nutzt.

Query-Parameter:

  • limit (optional) - Seitengröße, Default 50, max 100
  • cursor (optional) - Cursor aus der vorherigen Antwort

GET /api/v1/workflows/get

Liefert das vollständige Workflow-Dokument, das die Workflow-Detail-Seite verwendet, inklusive Konfiguration, Pipeline-Schritte, Persona-Pipeline-Schritte und gespeichertem Workflow-Graph.

  • id (erforderlich) - Workflow-ID

GET /api/v1/workflows/runs

Liefert den Runs-Tab für einen Workflow, inklusive Status, Branch-Name, PR-URL, Run-Nummer/Anzeige-ID, Zeitstempel und Paginierungs-Metadaten.

  • id (erforderlich) - Workflow-ID
  • limit (optional) - Default 50, max 100
  • cursor (optional) - Cursor aus der vorherigen Antwort

GET /api/v1/workflows/analytics

Liefert die Analytics-Tab-Payload für einen Workflow.

  • id (erforderlich) - Workflow-ID
  • days (optional) - Rückblick-Fenster, Default 30
  • granularity (optional) - daily, weekly oder monthly

GET /api/v1/workflows/related

Liefert die Related-Tab-Payload für einen Workflow: Personas, Issues und Learning-Versionen, die mit den Runs des Workflows verknüpft sind.

  • id (erforderlich) - Workflow-ID

GET /api/v1/workflows/versions

Liefert die Versionen-Tab-Payload für einen Workflow, inklusive aktueller Versionsnummer und Snapshot-Metadaten für jede gespeicherte Version.

  • id (erforderlich) - Workflow-ID

Schreib-Endpunkte

POST /api/v1/workflows/create

Einen Workflow-Blueprint erstellen.

Unterstützte Schreib-Felder umfassen:

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

Mindestens eines von pipelineSteps oder personaPipelineSteps muss angegeben werden.

POST /api/v1/workflows/update

Eine beliebige Teilmenge von Workflow-Feldern aktualisieren. API-Updates erzeugen außerdem einen Snapshot des vorherigen Workflow-Zustands im Versionsverlauf, damit der Versionen-Tab mit außerhalb der UI vorgenommenen Änderungen synchron bleibt.

{
  "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

Einen Workflow auf eine frühere Version zurücksetzen. Die API snapshottet zuvor den aktuellen Zustand, genau wie die Web-UI.

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

POST /api/v1/workflows/duplicate

Einen Workflow duplizieren, inklusive Persona-Pipeline-Schritten, Ausführungsschritten und gespeichertem Builder-Graph.

POST /api/v1/workflows/delete

Einen Workflow per Soft-Delete löschen.

POST /api/v1/workflows/restore

Einen per Soft-Delete gelöschten Workflow wiederherstellen.

POST /api/v1/workflows/permanent-delete

Einen Workflow dauerhaft löschen.

POST /api/v1/workflows/rename

Einen Workflow umbenennen.

POST /api/v1/workflows/bulk-delete

Workflows per Massen-Soft-Delete löschen.

Einen Workflow per API ausführen

Der Run-Button auf den Workflow-Listen-/Detail-Seiten bildet sich auf POST /api/v1/runs/start ab. Typische Request-Felder umfassen:

  • workflowId (erforderlich)
  • prompt (erforderlich)
  • githubRepoUrl (optional)
  • branchName (optional)
  • config (optionales Sandbox-Konfigurations-Override)
  • referenceImageIds (optional hochgeladene Bilder)

Um wie in der UI Bilder anzuhängen, fordern Sie zuerst eine Upload-URL via POST /api/v1/files/upload-url an, laden Sie das Binary an die zurückgegebene URL hoch und übergeben Sie die resultierenden storageId-Werte beim Start des Runs als referenceImageIds.

Workflow-Datenmodell

Workflow-Antworten können enthalten:

  • name, description, type
  • defaultConfig inklusive Tool-/Modell-/Ressourcenfelder
  • pipelineSteps und personaPipelineSteps
  • workflowGraph für den Builder-Tab
  • defaultCheckerInstructions und defaultOptimizerInstructions
  • createdAt, updatedAt, deletedAt
  • display-Felder wie die in der Listen-UI verwendeten CLI-Tool-Labels