DocsAPI Open Platformv1 Endpoint Reference

Complete Reference for v1 Endpoints

Request/response and cURL examples for the 14 v1 endpoints, plus an end-to-end call flow.

The v1 open platform has 14 endpoints (3 for workflows, 4 for executions, 5 for approvals, 2 for artifacts), all mounted under the /api/v1/* prefix. Each endpoint lists its required scope, request format, response format, and a curl example.

General Convention

Use Authorization: Bearer dyk_<id>_<secret>; the X-API-Key header is also accepted (see the "Authentication and rate limits" page)
All responses are application/json
The error response is unified as {"error": "..."}. For the semantics of HTTP status codes, please see the "Authentication and Rate Limiting" page.
triggerSource = "open_api": The execution started by v1 does not participate in auto-resume, and the caller is responsible for retrying/idempotent

Workflow Classes

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

Lists the workflows visible to the current Token owner. Support paging:?page=1&size=50 (default 50, maximum 200).

bash

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

Response:

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

Read a single workflow definition (with share / permission checks).

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

Start a new execution. The request body supports inputs and enableMonitoring fields. Response 202 Accepted (execution will occur asynchronously).

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

Response (202 Accepted):

json

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

After receiving the executionId, use GET /api/v1/executions/{id} Polling status.

Execution Class

GET `/api/v1/executions`

Scope: EXECUTION_READ

Paginated list of executions for the current owner. Can be filtered by ?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

Returns the real-time status of the execution: status/currentStep/completeSteps/totalSteps/startAt/completeAt/error/stepResults.

bash

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

Response field meaning:

Field	Type	Description
`status`	string	PENDING / RUNNING / COMPLETED / FAILED / CANCELLED / INTERRUPTED
`currentStep`	string?	The name of the step currently being executed (null if completed)
`completedSteps / totalSteps`	int	for progress bar
`error`	string?	Error message in FAILED state
`stepResults`	map	step name → StepResult, including status / output / duration of each step

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

Scope: EXECUTION_READ

Returns the complete ExecutionResult, including stepResults + duration + overall output. The value is only available after the termination status (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

Cancel a running execution. Returns 404 if execution has completed or does not exist.

bash

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

Approvals

When an execution reaches a manual_approval step, it pauses and creates an approval record. The 5 endpoints below all require the APPROVAL_RESPOND scope: an external system can list pending approvals, read approval details (including the editable approval-form data), and approve or reject. On approval, execution continues; on rejection, it stops; exceeding the approval's configured timeout auto-rejects.

GET `/api/v1/approvals`

Scope: APPROVAL_RESPOND

List the approval records visible to the current token owner. Filter by ?status= (e.g. PENDING); paginate with ?page=1&size=20 (default 20, max 200).

bash

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

Response:

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
}

The list endpoint does not return approval-form details

To keep responses small, the list endpoints (including the by-execution query) return an empty items array inside reviewableGroups and keep only the itemsCount row count. For full details, call the detail endpoint GET /api/v1/approvals/{id}.

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

Scope: APPROVAL_RESPOND

Read a single approval in full: status / stepName / approvalMessage / expiresAt, plus the complete items in reviewableGroups (the approval form's row data and column definitions).

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

Look up approvals by execution: returns all approval records produced by that execution (items are stripped here too). When polling execution status reveals a pause, use it to find the approval to act on.

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

Approve and let execution continue. Both request-body fields are optional: comment is the reviewer's note; editedItems submits an edited subset of rows by group name — omit it to approve the original data as-is, or include it and the engine runs only the rows you submit (this maps to the approval form's "editable" capability, e.g. adjusting a bid before approving).

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

The response is the updated approval record (status = APPROVED). Returns 404 if the approval does not exist or has already been handled.

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

Scope: APPROVAL_RESPOND

Reject the approval; execution then stops and no live changes are made. The optional comment field in the request body records the reason for rejection.

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

Product Category

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

Scope: ARTIFACT_READ

List all products generated by this execution (including files, reports, screenshots, etc. generated at each step).

bash

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

Response:

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

Meta information of a single product, including downloadUrl field. The client uses downloadUrl to directly pull the actual file content (not through the v1 endpoint, using the quota for free).

bash

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

Complete cURL Flow: Trigger → Poll → GET Product

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

Future Plans

OpenAPI 3 spec file — for Swagger UI / auto-generated SDK
Official Python/Node.js/Go SDK
Server-sent events: GET /api/v1/executions/{id}/events real-time push progress
webhook event callback (push back when execution is completed)

Workflow Classes

GET /api/v1/workflows

GET /api/v1/workflows/{id}

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

Execution Class

GET /api/v1/executions

GET /api/v1/executions/{id}

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

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

Approvals

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

Product Category

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

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

Complete cURL Flow: Trigger → Poll → GET Product

Future Plans

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