DokumentOffene API-PlattformV1-endpunktreferenz

Vollständige Referenz für v1-Endpunkte

Request- / Response- / cURL-Beispiele für die 14 v1-Endpunkte sowie ein End-to-End-Aufrufablauf.

Die offene Plattform v1 umfasst insgesamt 14 Endpunkte (3 für Workflows, 4 für Ausführungen, 5 für Genehmigungen, 2 für Artefakte), alle unter dem Präfix /api/v1/*. Für jeden Endpunkt sind der erforderliche Scope, das Request-Format, das Response-Format und ein curl-Beispiel aufgeführt.

Allgemeine Konvention

Empfohlen wird Authorization: Bearer dyk_<id>_<secret>; der X-API-Key Header wird ebenfalls akzeptiert (zur Schreibweise siehe die Seite „Authentifizierung und Ratenbegrenzung“)
Alle Antworten sind application/json
Die Fehlerantwort ist einheitlich als {"error": "..."}. Informationen zur Semantik von HTTP-Statuscodes finden Sie auf der Seite „Authentifizierung und Ratenbegrenzung“.
triggerSource = „open_api“: Die von v1 gestartete Ausführung nimmt nicht an der automatischen Wiederaufnahme teil und der Aufrufer ist für die Wiederholung/idempotent verantwortlich

Workflow-klasse

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

Listet die Workflows auf, die für den aktuellen Token-Besitzer sichtbar sind. Unterstützt Paging:?page=1&size=50 (Standard 50, maximal 200).

bash

curl https://braidrun.com/api/v1/workflows?page=1&size=20 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

Antwort:

json

{
  "items": [
    {
      "id": "wf-001",
      "name": "Daily ASA report",
      "ownerId": "u-alice",
      "workflow": [...]
    }
  ],
  "total": 17,
  "page": 1,
  "size": 20
}

GET `/api/v1/workflows/{id}`

Scope: WORKFLOW_READ

Lesen Sie eine einzelne Workflow-Definition (mit Freigabe-/Berechtigungsprüfungen).

bash

curl https://braidrun.com/api/v1/workflows/wf-001 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

POST `/api/v1/workflows/{id}/executions`

Scope: WORKFLOW_EXECUTE

Starten Sie eine neue Ausführung. Der Anforderungstext unterstützt Eingaben und enableMonitoring-Felder. Antwort 202 Akzeptiert (Ausführung erfolgt asynchron).

bash

curl -X POST https://braidrun.com/api/v1/workflows/wf-001/executions \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "customer_id": "12345",
      "report_date": "2026-04-30"
    },
    "enableMonitoring": true
  }'

Antwort (202 akzeptiert):

json

{
  "executionId": "exec_a3b9c8...",
  "status": "PENDING",
  "workflowId": "wf-001",
  "startedAt": 1735632891234
}

Verwenden Sie nach Erhalt der Ausführungs-ID GET /api/v1/executions/{id} Umfragestatus.

Ausführungsklasse

GET `/api/v1/executions`

Scope: EXECUTION_READ

Paginierte Liste der Hinrichtungen des aktuellen Besitzers. Kann nach ?workflowId= ?status= gefiltert werden.

bash

curl 'https://braidrun.com/api/v1/executions?status=RUNNING&size=10' \
  -H "Authorization: Bearer dyk_<id>_<secret>"

GET `/api/v1/executions/{id}`

Scope: EXECUTION_READ

Gibt den Echtzeitstatus der Ausführung zurück: status/currentStep/completeSteps/totalSteps/startAt/completeAt/error/stepResults.

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

Bedeutung des Antwortfeldes:

Feld	Typ	Beschreibung
`status`	string	PENDING / RUNNING / COMPLETED / FAILED / CANCELLED / INTERRUPTED
`currentStep`	string?	Der Name des Schritts, der gerade ausgeführt wird (null, wenn abgeschlossen)
`completedSteps / totalSteps`	int	für Fortschrittsbalken
`error`	string?	Fehlermeldung im Status FAILED
`stepResults`	map	Schrittname → StepResult, einschließlich Status/Ausgabe/Dauer jedes Schritts

GET `/api/v1/executions/{id}/result`

Scope: EXECUTION_READ

Gibt das vollständige ExecutionResult zurück, einschließlich stepResults + Dauer + Gesamtausgabe. Der Wert ist erst nach dem Beendigungsstatus (COMPLETED/FAILED/CANCELLED) verfügbar.

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8/result \
  -H "Authorization: Bearer dyk_<id>_<secret>"

POST `/api/v1/executions/{id}/cancel`

Scope: EXECUTION_CANCEL

Brechen Sie eine laufende Ausführung ab. Gibt 404 zurück, wenn die Ausführung abgeschlossen wurde oder nicht vorhanden ist.

bash

curl -X POST https://braidrun.com/api/v1/executions/exec_a3b9c8/cancel \
  -H "Authorization: Bearer dyk_<id>_<secret>"

Genehmigungen

Erreicht eine Ausführung einen manual_approval-Schritt, pausiert sie und erzeugt einen Genehmigungsdatensatz. Die folgenden 5 Endpunkte erfordern alle den APPROVAL_RESPOND-Scope: Externe Systeme können offene Genehmigungen auflisten, Genehmigungsdetails lesen (inkl. bearbeitbarer Genehmigungsformulardaten), genehmigen oder ablehnen. Nach der Genehmigung wird die Ausführung fortgesetzt; bei Ablehnung stoppt sie; wird das im Genehmigungsschritt konfigurierte timeout überschritten, erfolgt eine automatische Ablehnung.

GET `/api/v1/approvals`

Scope: APPROVAL_RESPOND

Listet die für den aktuellen Token-Owner sichtbaren Genehmigungsdatensätze auf. Filterbar über ?status= (z. B. PENDING); Paginierung wird unterstützt über ?page=1&size=20 (Standard 20, Maximum 200).

bash

curl 'https://braidrun.com/api/v1/approvals?status=PENDING&page=1&size=20' \
  -H "Authorization: Bearer dyk_<id>_<secret>"

Antwort:

json

{
  "approvals": [
    {
      "id": "apr-001",
      "executionId": "exec_a3b9c8...",
      "workflowId": "wf-001",
      "stepName": "review_bid_changes",
      "status": "PENDING",
      "approvalMessage": "42 条出价调整待确认",
      "timeout": 86400,
      "createdAt": 1735632891234,
      "expiresAt": 1735719291234,
      "reviewableGroups": [
        {
          "name": "bid_changes",
          "title": "出价调整",
          "items": [],
          "itemsCount": 42
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20
}

Der Listen-Endpunkt gibt keine Details des Genehmigungsformulars zurück

Um die Größe der Antwort zu begrenzen, setzt der Listen-Endpunkt (inkl. Abfrage nach Ausführung) die items in reviewableGroups auf ein leeres Array und behält nur itemsCount als Zeilenzahl. Für die vollständigen Details rufen Sie den Detail-Endpunkt GET /api/v1/approvals/{id} auf.

GET `/api/v1/approvals/{id}`

Scope: APPROVAL_RESPOND

Liest den vollständigen Inhalt einer einzelnen Genehmigung: status / stepName / approvalMessage / expiresAt sowie die vollständigen items der reviewableGroups (Zeilendaten des Genehmigungsformulars und Spaltendefinitionen).

bash

curl https://braidrun.com/api/v1/approvals/apr-001 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

GET `/api/v1/approvals/execution/{executionId}`

Scope: APPROVAL_RESPOND

Genehmigungen nach Ausführung abfragen: gibt alle von dieser execution erzeugten Genehmigungsdatensätze zurück (items werden ebenfalls entfernt). Stellen Sie beim Pollen des Ausführungsstatus eine Pause fest, lokalisieren Sie damit die zu bearbeitende Genehmigung.

bash

curl https://braidrun.com/api/v1/approvals/execution/exec_a3b9c8 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

POST `/api/v1/approvals/{id}/approve`

Scope: APPROVAL_RESPOND

Genehmigen und die Ausführung fortsetzen. Beide Felder im Request-Body sind optional: comment ist der Genehmigungskommentar; editedItems reicht je Gruppenname die bearbeitete Teilmenge der Zeilen ein — wird es nicht übergeben, werden die Originaldaten freigegeben, wird es übergeben, führt die Engine nur die von Ihnen eingereichten Zeilen aus (entspricht der Fähigkeit „bearbeitbar“ des Genehmigungsformulars, etwa das Gebot direkt ändern und dann genehmigen).

bash

curl -X POST https://braidrun.com/api/v1/approvals/apr-001/approve \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "确认执行，两条出价手动下调",
    "editedItems": {
      "bid_changes": [
        {"keyword": "photo editor", "newBid": 0.65},
        {"keyword": "collage maker", "newBid": 0.55}
      ]
    }
  }'

Die Antwort ist der aktualisierte Genehmigungsdatensatz (status = APPROVED). Existiert die Genehmigung nicht oder wurde sie bereits bearbeitet, wird 404 zurückgegeben.

POST `/api/v1/approvals/{id}/reject`

Scope: APPROVAL_RESPOND

Lehnt die Genehmigung ab, woraufhin die Ausführung stoppt, ohne dass produktive Änderungen entstehen. Das optionale Feld comment im Request-Body hält den Ablehnungsgrund fest.

bash

curl -X POST https://braidrun.com/api/v1/approvals/apr-001/reject \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"comment": "本周预算已用完，先不调整"}'

Produktkategorie

GET `/api/v1/executions/{id}/artifacts`

Scope: ARTIFACT_READ

Listen Sie alle durch diese Ausführung generierten Produkte auf (einschließlich Dateien, Berichte, Screenshots usw., die bei jedem Schritt generiert werden).

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8/artifacts \
  -H "Authorization: Bearer dyk_<id>_<secret>"

Antwort:

json

{
  "artifacts": [
    {
      "id": "art-001",
      "name": "daily-report.xlsx",
      "path": "executions/exec_a3b9c8/.../daily-report.xlsx",
      "storageKey": "executions/exec_a3b9c8/.../daily-report.xlsx",
      "downloadUrl": "/api/executions/exec_a3b9c8/artifacts/art-001/download",
      "previewable": false
    }
  ],
  "total": 1
}

GET `/api/v1/executions/{id}/artifacts/{aid}`

Scope: ARTIFACT_READ

Metainformationen eines einzelnen Produkts, einschließlich downloadUrl-Feld. Der Client verwendet downloadUrl, um den tatsächlichen Dateiinhalt direkt abzurufen (nicht über den v1-Endpunkt, sondern nutzt das Kontingent kostenlos).

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8/artifacts/art-001 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

Vollständiger cURL-Ablauf: Auslösen → Umfrage → Produkt abrufen

bash

# 1. 启动执行
EXEC_ID=$(curl -s -X POST \
  https://braidrun.com/api/v1/workflows/wf-001/executions \
  -H "Authorization: Bearer $DYK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"customer_id": "12345"}}' \
  | jq -r .executionId)

# 2. 轮询直到完成
while true; do
  STATUS=$(curl -s \
    "https://braidrun.com/api/v1/executions/$EXEC_ID" \
    -H "Authorization: Bearer $DYK_TOKEN" \
    | jq -r .status)
  echo "$EXEC_ID: $STATUS"
  case $STATUS in
    COMPLETED|FAILED|CANCELLED) break ;;
  esac
  sleep 5
done

# 3. 拿产物列表
curl -s "https://braidrun.com/api/v1/executions/$EXEC_ID/artifacts" \
  -H "Authorization: Bearer $DYK_TOKEN" | jq .artifacts

Zukunftspläne

OpenAPI 3-Spezifikationsdatei – für Swagger UI / automatisch generiertes SDK
Offizielles Python/Node.js/Go SDK
Vom Server gesendete Ereignisse: GET /api/v1/executions/{id}/events Push-Fortschritt in Echtzeit
Webhook-Ereignisrückruf (zurückschieben, wenn die Ausführung abgeschlossen ist)

Workflow-klasse

GET /api/v1/workflows

GET /api/v1/workflows/{id}

POST /api/v1/workflows/{id}/executions

Ausführungsklasse

GET /api/v1/executions

GET /api/v1/executions/{id}

GET /api/v1/executions/{id}/result

POST /api/v1/executions/{id}/cancel

Genehmigungen

GET /api/v1/approvals

GET /api/v1/approvals/{id}

GET /api/v1/approvals/execution/{executionId}

POST /api/v1/approvals/{id}/approve

POST /api/v1/approvals/{id}/reject

Produktkategorie

GET /api/v1/executions/{id}/artifacts

GET /api/v1/executions/{id}/artifacts/{aid}

Vollständiger cURL-Ablauf: Auslösen → Umfrage → Produkt abrufen

Zukunftspläne

GET `/api/v1/workflows`

GET `/api/v1/workflows/{id}`

POST `/api/v1/workflows/{id}/executions`

GET `/api/v1/executions`

GET `/api/v1/executions/{id}`

GET `/api/v1/executions/{id}/result`

POST `/api/v1/executions/{id}/cancel`

GET `/api/v1/approvals`

GET `/api/v1/approvals/{id}`

GET `/api/v1/approvals/execution/{executionId}`

POST `/api/v1/approvals/{id}/approve`

POST `/api/v1/approvals/{id}/reject`

GET `/api/v1/executions/{id}/artifacts`

GET `/api/v1/executions/{id}/artifacts/{aid}`