DocumentoPlataforma abierta APIReferencia del punto final v1

Referencia completa para puntos finales v1

Ejemplos de solicitud / respuesta / cURL de los 14 endpoints de v1 y flujo de llamadas de extremo a extremo.

La plataforma abierta v1 tiene 14 endpoints en total (3 de workflows, 4 de ejecuciones, 5 de aprobaciones, 2 de artefactos), todos montados bajo el prefijo /api/v1/*. Cada endpoint indica el scope requerido, el formato de solicitud, el formato de respuesta y un ejemplo con curl.

convención general

Se recomienda usar Authorization: Bearer dyk_<id>_<secret>; también se acepta el header X-API-Key (la sintaxis está en la página «Autenticación y límites de tasa»)
Todas las respuestas son application/json
La respuesta de error está unificada como {"error": "..."}. Para conocer la semántica de los códigos de estado HTTP, consulte la página "Autenticación y limitación de velocidad".
triggerSource = "open_api": la ejecución iniciada por v1 no participa en la reanudación automática y la persona que llama es responsable de volver a intentarlo/idempotente

Clase de flujo de trabajo

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

Enumera los flujos de trabajo visibles para el propietario actual del token. Paginación de soporte:?page=1&size=50 (50 predeterminado, máximo 200).

bash

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

Respuesta:

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

Lea una única definición de flujo de trabajo (con comprobaciones de compartir/permisos).

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

Iniciar una nueva ejecución. El cuerpo de la solicitud admite entradas y campos enableMonitoring. Respuesta 202 Aceptada (la ejecución se producirá de forma asincrónica).

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

Respuesta (202 Aceptada):

json

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

Después de recibir el ID de ejecución, use GET /api/v1/executions/{id} Estado de la encuesta.

Clase de ejecución

GET `/api/v1/executions`

Scope: EXECUTION_READ

Lista paginada de ejecuciones para el propietario actual. Se puede filtrar por ?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

Devuelve el estado de la ejecución en tiempo real: status/currentStep/completeSteps/totalSteps/startAt/completeAt/error/stepResults.

bash

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

Significado del campo de respuesta:

campo	Tipo	Descripción
`status`	string	PENDING / RUNNING / COMPLETED / FAILED / CANCELLED / INTERRUPTED
`currentStep`	string?	El nombre del paso que se está ejecutando actualmente (nulo si se completó)
`completedSteps / totalSteps`	int	para barra de progreso
`error`	string?	Mensaje de error en estado FALLADO
`stepResults`	map	nombre del paso → Resultado del paso, incluido el estado/salida/duración de cada paso

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

Scope: EXECUTION_READ

Devuelve el resultado de ejecución completo, incluidos los resultados de los pasos + la duración + el resultado general. El valor solo está disponible después del estado de terminación (COMPLETADO/FALLADO/CANCELADO).

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

Cancelar una ejecución en ejecución. Devuelve 404 si la ejecución se completó o no existe.

bash

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

Aprobaciones

Cuando una ejecución llega a un paso manual_approval, se pausa y genera un registro de aprobación. Los 5 endpoints siguientes requieren el scope APPROVAL_RESPOND: los sistemas externos pueden listar los pendientes, leer los detalles de una aprobación (incluidos los datos editables del formulario de aprobación) y aprobar o rechazar. Tras aprobar, la ejecución continúa; si se rechaza, la ejecución se detiene; si se supera el timeout configurado en la aprobación, se rechaza automáticamente.

GET `/api/v1/approvals`

Scope: APPROVAL_RESPOND

Lista los registros de aprobación visibles para el titular actual del Token. Se puede filtrar por ?status= (p. ej. PENDING); admite paginación ?page=1&size=20 (por defecto 20, máximo 200).

bash

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

Respuesta:

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
}

El endpoint de listado no devuelve el detalle del formulario de aprobación

Para controlar el tamaño de la respuesta, el endpoint de listado (incluida la consulta por ejecución) deja vacío el array items dentro de reviewableGroups y conserva solo el número de filas en itemsCount. Cuando necesite el detalle completo, llame al endpoint de detalle GET /api/v1/approvals/{id}.

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

Scope: APPROVAL_RESPOND

Lee el contenido completo de una aprobación: status / stepName / approvalMessage / expiresAt, además de los items completos de reviewableGroups (los datos fila a fila del formulario de aprobación y las definiciones de columna).

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

Consultar aprobaciones por ejecución: devuelve todos los registros de aprobación generados por esa execution (los items también se eliminan). Cuando al sondear el estado de la ejecución detecte una pausa, úselo para localizar la aprobación que hay que tramitar.

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

Aprobar y dejar que la ejecución continúe. Los dos campos del cuerpo de la solicitud son opcionales: comment es el comentario de aprobación; editedItems envía, por nombre de grupo, el subconjunto de filas editadas — si no se envía, se aprueba con los datos originales; si se envía, el motor solo ejecuta las filas que usted envíe (corresponde a la capacidad «editable» del formulario de aprobación, como cambiar la puja directamente y luego aprobar).

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 respuesta es el registro de aprobación actualizado (status = APPROVED). Si la aprobación no existe o ya se ha tramitado, devuelve 404.

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

Scope: APPROVAL_RESPOND

Rechaza la aprobación y la ejecución se detiene, sin producir ningún cambio en producción. El cuerpo de la solicitud admite el campo opcional comment para registrar el motivo del rechazo.

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

Categoría de producto

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

Scope: ARTIFACT_READ

Enumere todos los productos generados por esta ejecución (incluidos archivos, informes, capturas de pantalla, etc. generados en cada paso).

bash

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

Respuesta:

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

Metainformación de un solo producto, incluido el campo downloadUrl. El cliente usa downloadUrl para extraer directamente el contenido del archivo real (no a través del punto final v1, usando la cuota de forma gratuita).

bash

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

Flujo completo de cURL: desencadenador → encuesta → obtener producto

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

Planes futuros

Archivo de especificaciones OpenAPI 3: para Swagger UI/SDK generado automáticamente
SDK oficial de Python/Node.js/Go
Eventos enviados por el servidor: GET /api/v1/executions/{id}/events progreso de inserción en tiempo real
Devolución de llamada de evento de webhook (retroceder cuando se completa la ejecución)

Clase de flujo de trabajo

GET /api/v1/workflows

GET /api/v1/workflows/{id}

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

Clase de ejecución

GET /api/v1/executions

GET /api/v1/executions/{id}

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

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

Aprobaciones

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

Categoría de producto

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

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

Flujo completo de cURL: desencadenador → encuesta → obtener producto

Planes futuros

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