DocumentPlateforme ouverte APIRéférence du point de terminaison v1

Référence complète pour les points de terminaison v1

Exemples de requête / réponse / cURL pour les 14 points de terminaison v1 + flux d'appel de bout en bout.

La plateforme ouverte v1 compte 14 endpoints (3 pour les workflows, 4 pour les exécutions, 5 pour les approbations, 2 pour les artefacts), tous montés sous le préfixe /api/v1/*. Chaque endpoint indique le scope requis, le format de requête, le format de réponse et un exemple curl.

Convention générale

Il est recommandé d'utiliser Authorization: Bearer dyk_<id>_<secret> ; le Header X-API-Key est également accepté (voir la page « Authentification et limitation de débit » pour la syntaxe)
Toutes les réponses sont en application/json
La réponse d'erreur est unifiée sous la forme {"error": "..."}. Pour la sémantique des codes d'état HTTP, veuillez consulter la page « Authentification et limitation de débit ».
triggerSource = "open_api" : L'exécution démarrée par la v1 ne participe pas à la reprise automatique, et l'appelant est responsable de la nouvelle tentative/idempotent

Classe de flux de travail

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

Répertorie les workflows visibles par le propriétaire actuel du jeton. Paging de support :?page=1&size=50 (par défaut 50, maximum 200).

bash

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

Réponse :

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

Lire une seule définition de flux de travail (avec vérifications de partage/autorisation).

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

Commencez une nouvelle exécution. Le corps de la requête prend en charge les champs d'entrée et d'enableMonitoring. Réponse 202 Acceptée (l'exécution se produira de manière asynchrone).

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
  }'

Réponse (202 acceptées) :

json

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

Après avoir reçu l'executionId, utilisez GET /api/v1/executions/{id} Statut du sondage.

Classe d'exécution

GET `/api/v1/executions`

Scope: EXECUTION_READ

Liste paginée des exécutions pour le propriétaire actuel. Peut être filtré par ?workflowId= ?status=.

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

Renvoie l'état en temps réel de l'exécution : status/currentStep/completeSteps/totalSteps/startAt/completeAt/error/stepResults.

bash

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

Signification du champ de réponse :

Champ	Tapez	Description
`status`	string	PENDING / RUNNING / COMPLETED / FAILED / CANCELLED / INTERRUPTED
`currentStep`	string?	Le nom de l'étape en cours d'exécution (nulle si terminée)
`completedSteps / totalSteps`	int	pour la barre de progression
`error`	string?	Message d'erreur à l'état FAILED
`stepResults`	map	nom de l'étape → StepResult, y compris l'état/la sortie/la durée de chaque étape

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

Scope: EXECUTION_READ

Renvoie le ExecutionResult complet, y compris stepResults + durée + sortie globale. La valeur n'est disponible qu'après le statut de résiliation (COMPLETED/FAILED/CANCELLED).

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

Annulez une exécution en cours. Renvoie 404 si l'exécution est terminée ou n'existe pas.

bash

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

Approbations

Lorsqu'une exécution atteint une étape manual_approval, elle se met en pause et génère un enregistrement d'approbation. Les 5 endpoints ci-dessous requièrent tous le scope APPROVAL_RESPOND : un système externe peut lister les approbations en attente, lire les détails d'une approbation (y compris les données modifiables du formulaire d'approbation), approuver ou rejeter. Après approbation, l'exécution se poursuit ; en cas de rejet, elle s'arrête ; le dépassement du timeout configuré pour l'approbation entraîne un rejet automatique.

GET `/api/v1/approvals`

Scope: APPROVAL_RESPOND

Liste les enregistrements d'approbation visibles par le propriétaire du Token courant. Filtrage possible via ?status= (par exemple PENDING) ; pagination prise en charge via ?page=1&size=20 (20 par défaut, 200 au maximum).

bash

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

Réponse :

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
}

L'endpoint de liste ne renvoie pas le détail du formulaire d'approbation

Pour limiter la taille de la réponse, l'endpoint de liste (y compris la requête par exécution) met les items de reviewableGroups à un tableau vide et ne conserve que le nombre de lignes itemsCount. Pour obtenir le détail complet, appelez l'endpoint de détail GET /api/v1/approvals/{id}.

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

Scope: APPROVAL_RESPOND

Lit le contenu complet d'une approbation : status / stepName / approvalMessage / expiresAt, ainsi que les items complets de reviewableGroups (données ligne par ligne du formulaire d'approbation et définitions de colonnes).

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

Interroger les approbations par exécution : renvoie tous les enregistrements d'approbation produits par cette execution (les items sont là aussi retirés). Lorsque le polling de l'état d'exécution révèle une mise en pause, utilisez cet endpoint pour localiser l'approbation à traiter.

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

Approuve et laisse l'exécution se poursuivre. Les deux champs du corps de requête sont facultatifs : comment est le commentaire d'approbation ; editedItems soumet, par nom de groupe, le sous-ensemble de lignes modifiées — s'il est omis, les données d'origine sont validées telles quelles ; s'il est fourni, le moteur n'exécute que les lignes que vous soumettez (correspond à la capacité « modifiable » du formulaire d'approbation, par exemple modifier directement l'enchère avant d'approuver).

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}
      ]
    }
  }'

La réponse est l'enregistrement d'approbation mis à jour (status = APPROVED). Renvoie 404 si l'approbation n'existe pas ou a déjà été traitée.

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

Scope: APPROVAL_RESPOND

Rejette l'approbation ; l'exécution s'arrête et aucune modification en production n'est effectuée. Le corps de requête accepte un champ comment facultatif pour consigner le motif du rejet.

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": "本周预算已用完，先不调整"}'

Catégorie de produit

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

Scope: ARTIFACT_READ

Répertoriez tous les produits générés par cette exécution (y compris les fichiers, rapports, captures d'écran, etc. générés à chaque étape).

bash

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

Réponse :

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

Méta-informations d'un seul produit, y compris le champ downloadUrl. Le client utilise downloadUrl pour extraire directement le contenu réel du fichier (pas via le point de terminaison v1, en utilisant le quota gratuitement).

bash

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

Flux cURL complet : déclencheur → sondage → obtenir le produit

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

Projets futurs

Fichier de spécifications OpenAPI 3 — pour l'interface utilisateur Swagger/SDK généré automatiquement
SDK officiel Python/Node.js/Go
Événements envoyés par le serveur : GET /api/v1/executions/{id}/events progression du push en temps réel
Rappel d'événement webhook (repoussé une fois l'exécution terminée)

Classe de flux de travail

GET /api/v1/workflows

GET /api/v1/workflows/{id}

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

Classe d'exécution

GET /api/v1/executions

GET /api/v1/executions/{id}

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

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

Approbations

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

Catégorie de produit

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

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

Flux cURL complet : déclencheur → sondage → obtenir le produit

Projets futurs

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}`