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

After approval is rejected, the gated steps will not be executed, and the execution ends on the rejected path; upstream steps that have been completed before approval and their external side effects will not be automatically rolled back. 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": "本周预算已用完，先不调整"}'

Artifacts

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

Scope: ARTIFACT_READ

List every artifact generated by this execution (including files, reports, and screenshots produced by 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

Returns metadata for one artifact, including downloadUrl. The client then downloads the file from that URL. Although the download request no longer uses an /api/v1 path, it is still subject to the download endpoint’s own authentication and storage configuration.

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 Artifact

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

Supporting calling method

The official SDK provides clients for several languages. Choose one of the packages currently listed on the SDK page and present in the repository.
The current v1 execution process polls the status via GET /api/v1/executions/{id}. Do not rely on v1 event stream endpoints that are not already listed on this page.
External systems can use Webhooks to actively trigger workflows; the management and triggering endpoints of Webhooks do not belong to /api/v1.
If you need callbacks or OpenAPI description files that are not provided by the current version, please confirm through the deployer's public support channels and do not assume the endpoints according to the roadmap.

Last Updated · 2026-07-30

Was this page helpful?

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

Artifacts

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

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

Complete cURL Flow: Trigger → Poll → Get Artifact

Supporting calling method

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