문서API 오픈 플랫폼v1 엔드포인트 참조

v1 엔드포인트에 대한 전체 참조

14개 v1 엔드포인트의 요청 / 응답 / cURL 예시와 엔드투엔드 호출 흐름입니다.

오픈 플랫폼 v1은 총 14개 엔드포인트(워크플로 3개, 실행 4개, 승인 5개, 아티팩트 2개)로, 모두 /api/v1/* 프리픽스 아래에 마운트됩니다. 각 엔드포인트는 필요한 scope, 요청 형식, 응답 형식, curl 예시를 나열합니다.

총회

Authorization: Bearer dyk_<id>_<secret> 사용을 권장합니다. X-API-Key Header도 허용됩니다(작성 방법은 「인증 및 속도 제한」 페이지 참고)
모든 응답은 application/json입니다
오류 응답은 {"error": "..."}로 통합됩니다. HTTP 상태 코드의 의미에 대해서는 "인증 및 속도 제한" 페이지를 참조하세요.
TriggerSource = "open_api": v1에 의해 시작된 실행은 자동 재개에 참여하지 않으며 호출자는 재시도/멱등성을 담당합니다.

워크플로 클래스

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

현재 토큰 소유자에게 표시되는 워크플로를 나열합니다. 페이징 지원:?page=1&size=50(기본값 50, 최대 200).

bash

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

응답:

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

단일 워크플로 정의를 읽습니다(공유/권한 확인 포함).

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

새로운 실행을 시작합니다. 요청 본문은 입력 및 활성화Monitoring 필드를 지원합니다. 응답 202 승인됨(실행이 비동기적으로 발생함)

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

응답(202 승인):

json

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

실행 ID를 받은 후 사용 GET /api/v1/executions/{id} 폴링 상태.

실행 클래스

GET `/api/v1/executions`

Scope: EXECUTION_READ

현재 소유자에 대한 페이지가 매겨진 실행 목록입니다. ?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

실행의 실시간 상태를 반환합니다: status/currentStep/completeSteps/totalSteps/startAt/completeAt/error/stepResults.

bash

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

응답 필드 의미:

필드	유형	설명
`status`	string	PENDING / RUNNING / COMPLETED / FAILED / CANCELLED / INTERRUPTED
`currentStep`	string?	현재 실행 중인 단계의 이름(완료된 경우 null)
`completedSteps / totalSteps`	int	진행률 표시줄
`error`	string?	FAILED 상태의 오류 메시지
`stepResults`	map	단계 이름 → 각 단계의 상태/출력/기간을 포함한 StepResult

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

Scope: EXECUTION_READ

stepResults + 기간 + 전체 출력을 포함하여 전체 ExecutionResult를 반환합니다. 해당 값은 종료 상태(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

실행 중인 실행을 취소합니다. 실행이 완료되었거나 존재하지 않는 경우 404를 반환합니다.

bash

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

승인 계열

실행이 manual_approval 단계에 도달하면 일시 중지되고 승인 레코드 한 건이 생성됩니다. 아래 5개 엔드포인트는 모두 APPROVAL_RESPOND scope를 요구합니다. 외부 시스템은 대기 중 승인 목록 조회, 승인 상세 읽기(편집 가능한 승인표 데이터 포함), 승인 또는 거부를 할 수 있습니다. 승인하면 실행이 계속되고, 거부하면 실행이 중단되며, 승인 설정의 timeout을 초과하면 자동으로 거부됩니다.

GET `/api/v1/approvals`

Scope: APPROVAL_RESPOND

현재 Token owner에게 보이는 승인 레코드를 나열합니다. ?status=로 필터링할 수 있으며(예: PENDING), 페이지네이션 ?page=1&size=20을 지원합니다(기본 20, 최대 200).

bash

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

응답:

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
}

목록 엔드포인트는 승인표 상세를 반환하지 않습니다

응답 크기를 제어하기 위해 목록 엔드포인트(실행별 조회 포함)는 reviewableGroups의 items를 빈 배열로 설정하고 itemsCount 행 수만 유지합니다. 완전한 상세가 필요하면 상세 엔드포인트 GET /api/v1/approvals/{id}를 호출하십시오.

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

Scope: APPROVAL_RESPOND

단일 승인의 완전한 내용을 읽습니다: status / stepName / approvalMessage / expiresAt, 그리고 reviewableGroups의 완전한 items(승인표의 행별 데이터와 열 정의).

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

실행별 승인 조회: 해당 execution이 생성한 모든 승인 레코드를 반환합니다(items는 마찬가지로 제거됨). 실행 상태를 폴링하다가 일시 중지를 발견하면, 이를 사용해 처리할 승인을 찾습니다.

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

승인하고 실행을 계속하게 합니다. 요청 본문의 두 필드는 모두 선택입니다. comment는 승인 의견이고, editedItems는 그룹명 기준으로 편집된 행 서브셋을 제출합니다 — 전달하지 않으면 원본 데이터대로 통과시키고, 전달하면 엔진은 제출한 행만 실행합니다(승인표의 「편집 가능」 기능에 해당하며, 예를 들어 입찰가를 직접 수정한 뒤 승인).

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

응답은 갱신된 승인 레코드입니다(status = APPROVED). 승인이 존재하지 않거나 이미 처리된 경우 404를 반환합니다.

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

Scope: APPROVAL_RESPOND

승인을 거부하면 실행이 그에 따라 중단되며, 어떤 라이브 변경도 발생하지 않습니다. 요청 본문에는 거부 사유를 기록하는 comment 필드를 선택적으로 넣을 수 있습니다.

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

제품 카테고리

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

Scope: ARTIFACT_READ

이 실행으로 생성된 모든 제품을 나열합니다(각 단계에서 생성된 파일, 보고서, 스크린샷 등 포함).

bash

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

응답:

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

downloadUrl 필드를 포함한 단일 제품의 메타 정보입니다. 클라이언트는 downloadUrl을 사용하여 실제 파일 콘텐츠를 직접 가져옵니다(v1 엔드포인트를 통하지 않고 무료로 할당량을 사용함).

bash

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

cURL 흐름 완료: 트리거 → 폴링 → 제품 가져오기

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

향후 계획

OpenAPI 3 사양 파일 — Swagger UI/자동 생성 SDK용
공식 Python/Node.js/Go SDK
서버에서 보낸 이벤트: GET /api/v1/executions/{id}/events 실시간 푸시 진행률
웹훅 이벤트 콜백(실행 완료 시 푸시백)

워크플로 클래스

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}

cURL 흐름 완료: 트리거 → 폴링 → 제품 가져오기

향후 계획

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