Skip to Main Content
For Developers

Use AI agent workflowsas an API

Trigger, check results, respond to approvals, and fetch artifacts—all over REST, with no model calls, retries, or queues to maintain yourself.

Start for FreeRead the API Docs
14 v1 endpoints6 permission scopes7-language sandbox
braidrun v1 APIREST · JSON
# Trigger an execution
POST /api/webhooks/{id}/trigger
→ {"executionId": "exec_51a2"}

# Poll status: this one paused at manual approval
GET  /api/v1/executions/exec_51a2
→ {"status": "AWAITING_APPROVAL"}

# Continue after approval (values can be edited before approving)
POST /api/v1/approvals/{approvalId}/approve

# Fetch the result and artifacts once done
GET  /api/v1/executions/exec_51a2/result
GET  /api/v1/executions/exec_51a2/artifacts
Integration Path

15 minutes, from creating a Webhook to getting your first result

Four HTTP requests run the whole flow, no SDK needed; any language that can make requests can integrate.

  1. Create a Webhook, get the URL and Key WEBHOOK_TRIGGERAdd a Webhook trigger to your workflow in the console to get a dedicated URL; then create an API Key with the WEBHOOK_TRIGGER scope.
  2. One POST triggers an execution POSTTop-level JSON fields map automatically to workflow variables of the same name, or you can map explicitly with variableMapping; the payload is capped at 1MB.
  3. Poll the execution status and get the result GET /api/v1/executions/{id}Use the returned executionId to check execution details; once done, get the output from the result endpoint and download files from the artifacts endpoint.
  4. Actions needing human review go through the approval API APPROVAL_RESPONDThe execution pauses at a manual_approval step; use the approval endpoints to list pending items and approve or reject, and on rejection or timeout nothing changes.
terminalX-API-Key · JSON ≤ 1MB
# Step 2: send a POST from your system
curl -X POST https://your-host/api/webhooks/{id}/trigger \
  -H "X-API-Key: <your-api-key>" \
  -d '{"ticket_id": "T-1024", "lang": "zh"}'
# Top-level fields map automatically to workflow variables of the same name
→ {"executionId": "exec_51a2"}

# Step 3: poll status and get the result once done
curl https://your-host/api/v1/executions/exec_51a2/result \
  -H "X-API-Key: <your-api-key>"
Capability List

Six things developers care about

  • Sandboxed code steps in 7 languagesWF_VAR_*30s timeoutWrite in Python, JavaScript, TypeScript, Bash, Ruby, Lua, or the CLI; variables are injected as WF_VAR_* environment variables, the default timeout is 30 seconds, and in production it runs in a Docker sandbox with controlled egress.
  • YAML definitions that fit your Git workflowworkflow.yamlgit diffA workflow is a single YAML file: commit, diff, and roll back all happen in the repo you already know; the canvas and YAML stay in two-way sync, so edit either side.
  • MCP for connecting your own toolsMCPagent toolsWrap an internal service as an MCP Server and attach it to an Agent, and AI steps can call your system directly, without waiting for the platform to build a connector.
  • Breakpoint Debugger9 breakpointsPro9 breakpoint types pause on a hit so you can edit variables and continue; after a failure, rerun from a specified step, with completed LLM steps not billed again.
  • 14-endpoint v1 API, least privilegev16 scopesTriggering executions, checking results, responding to approvals, and downloading artifacts each have their own permission scope; combine the 6 scopes as needed and issue each connected system its own Key.
  • Chained triggers with DELAYED_COMPLETIONDELAYED_COMPLETIONmaxRunsAfter A finishes, B triggers automatically N seconds later, with a settable maxRuns cap; split a long process into segments, each with its own logs and cost.
Honest Boundaries

Three Things, Said Upfront

So you don't find out halfway through integrating.

No hundreds of SaaS connectorsCalls to external systems go in code steps, or wrap them as MCP tools attached to an Agent; for a team that writes code, this step is just a few lines of HTTP requests.
No pre-run cost estimate APIEach execution's token usage and cost are recorded per run, so after-the-fact accounting is granular; but there's no quote before running, so budget control relies on approval gates and maxRuns.
Limits Stated Plainly UpfrontWebhook payload capped at 1MB; code steps default to a 30-second timeout; HMAC-SHA256 signatures are kept only as a compatibility mode, and new integrations use API Key.
Docs

Three worth reading before you integrate

GET /api/v1/*v1 API ReferenceRequest and response fields and error codes for the 14 endpoints, plus how to set up the 6 permission scopes.Open the Docs POST /api/webhooks/*Webhook TriggerGetting the URL and Key, variable mapping rules, the HMAC compatibility mode, and the 1MB limit.Open the Docs workflow.yamlYAML SyntaxThe 8 step types, plus how to write modifiers like condition, retry, and manual_approval.Open the Docs
Connect your first workflow to your system
The Free plan lets you build a workflow and run it manually; upgrade to Pro when you need Webhook triggers and scheduling.
Start for FreeRead the API Docs