DocsAPI abrir plataformaReferência do ponto de avaliação v1

Referência completa para os parâmetros v1

Exemplos de pedido/resposta e de cURL para os parâmetros de 14 v1, mais um fluxo de chamada de ponta a ponta.

A plataforma aberta v1 tem 14 endpoints (3 para workflows, 4 para execuções, 5 para aprovações, 2 para artefatos), todos montados sob o prefixo /api/v1/*. Cada endpoint lista seu escopo, formato de solicitação, formato de resposta e um exemplo de curl.

Convenção geral

Autorização de uso: dyk <id> <secret>; o cabeçalho X-API-Key também é aceito (veja a página "Limites de autenticação e taxa")
Todas as respostas são aplicação/json
A resposta de erro é unificada como {"error": "..."}. Para a semântica dos códigos de estado HTTP, consulte a página "Autenticação e Limitação de Taxa".
triggerSource = "open api": A execução iniciada pelo v1 não participa do auto-resume, e o chamador é responsável pela repetição/idempotente

Classe de workflow

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

Lista os workflows visíveis para o proprietário atual do Token. Suporte de paging:?page=1&size=50 (padrão 50, máximo 200).

bash

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

Resposta:

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

Leia uma única definição de workflow (com verificação de compartilhamento / permissão).

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 uma nova execução. O corpo de solicitação suporta entradas e ativa campos de monitoramento. Resposta 202 Aceitada (a execução ocorrerá assíncrona).

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

Resposta (202 aceite):

json

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

Após receber a execuçãoId, utilizar GET /api/v1/executions/{id} Situação da sondagem.

Classe de execução

GET `/api/v1/executions`

Scope: EXECUTION_READ

Lista paginada de execuções para o proprietário atual. Pode ser filtrado 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

Retorna o status em tempo real da execução: 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 do campo de resposta:

Campo	Tipo	Designação das mercadorias
`status`	string	PENDING / RUNNING / COMPLETED / FAILED / CANCELLED / INTERRUPTED
`currentStep`	string?	O nome da etapa atualmente executada (null se concluída)
`completedSteps / totalSteps`	int	barra de progresso
`error`	string?	Mensagem de erro no estado FALHADO
`stepResults`	map	step name → StepResult, incluindo status / saída / duração de cada passo

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

Scope: EXECUTION_READ

Retorna a execução completaResultado, incluindo passoResultados + duração + saída global. O valor só está disponível após o estado de rescisão (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

Cancelar uma execução em execução. Retorna 404 se a execução tiver terminado ou não existir.

bash

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

Homologação

Quando uma execução atinge uma etapa de aprovação manual, ela pausa e cria um registro de aprovação. Os 5 endpoints abaixo de todos exigem o escopo APPROVAL RESPOND: um sistema externo pode listar as aprovações pendentes, ler detalhes da aprovação (incluindo os dados editáveis do formulário de aprovação) e aprovar ou rejeitar. Na aprovação, a execução continua; na rejeição, para; excedendo o tempo-out configurado da aprovação auto-rejeitos.

GET `/api/v1/approvals`

Scope: APPROVAL_RESPOND

Listar os registos de aprovação visíveis para o actual proprietário do símbolo. Filtrar por ?status= (por exemplo, PENDING); paginar com ?page=1&size=20 (padrão 20, max 200).

bash

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

Resposta:

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
}

O ponto final da lista não devolve os detalhes do formulário de homologação

Para manter as respostas pequenas, os endpoints da lista (incluindo a consulta por execução) retornam um array de itens vazios dentro do reviewableGroups e mantêm apenas os itensContar contagem de linhas. Para detalhes completos, ligue para o ponto final de detalhe GET /api/v1/aprovações/{id}.

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

Scope: APPROVAL_RESPOND

Leia uma única aprovação na íntegra: status / stepName / avalMensagem / expiraAt, além dos itens completos em Grupos revisáveis (dados da linha do formulário de aprovação e definições da coluna).

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

Procure aprovações por execução: retorna todos os registros de aprovação produzidos por essa execução (itens são despojados aqui também). Quando o status de execução de votação revela uma pausa, use-a para encontrar a aprovação para agir.

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

Aprovar e deixar a execução continuar. Ambos os campos request-body são opcionais: o comentário é a nota do revisor; editedItems submete um subconjunto editado de linhas por nome de grupo — omiti-lo para aprovar os dados originais como-is, ou incluí-lo e o motor executa apenas as linhas que você envia (estes mapas para a capacidade "editável" do formulário de aprovação, por exemplo, ajustar uma licitação antes de aprovar).

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

A resposta é o registo de homologação actualizado (status = HOPROVED). Devolve 404 se a homologação não existir ou já tiver sido tratada.

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

Scope: APPROVAL_RESPOND

Rejeite a aprovação; a execução então pára e nenhuma alteração ao vivo é feita. O campo opcional do comentário no corpo de solicitação registra o motivo da rejeição.

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

Categoria de produtos

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

Scope: ARTIFACT_READ

Listar todos os produtos gerados por esta execução (incluindo arquivos, relatórios, capturas de tela, etc. gerados em cada etapa).

bash

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

Resposta:

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-informação de um único produto, incluindo campo de downloadUrl. O cliente usa o downloadUrl para puxar diretamente o conteúdo do arquivo real (não através do endpoint v1, usando a quota gratuitamente).

bash

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

Fluxo cURL completo: gatilho → votação → obter produto

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

Planos futuros

OpenAPI 3 spec file — for Swagger UI / auto-gerado SDK
Python/Node.js/Go oficial SDK
Eventos enviados pelo servidor: GET /api/v1/executions/{id}/events real-time push progress
callback do evento webhook (empurrar para trás quando a execução estiver concluída)

Classe de workflow

GET /api/v1/workflows

GET /api/v1/workflows/{id}

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

Classe de execução

GET /api/v1/executions

GET /api/v1/executions/{id}

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

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

Homologação

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

Categoria de produtos

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

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

Fluxo cURL completo: gatilho → votação → obter produto

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