Orchestrator API — bRRAIn Docs

Programmatic API for the Agent Orchestrator extension — list, run, replay, and observe orchestrations.

Orchestrator API

The Orchestrator API lets you list, fire, observe, and integrate with orchestrations programmatically. It's the API behind the Agent Orchestrator iframe and is also available to your own integrations.

Available when the Agent Orchestrator extension is installed in the organization.

Base path

https://<your-org-slug>.brrain.io/api/orchestrator

For multi-org operators, each organization has its own subdomain. The API requires an authenticated bearer token (see API: Authentication).

Orchestrations

List

GET /orchestrations?limit=50&cursor=&zone=engineering

Returns paginated orchestrations. Filterable by zone, owner, tag, status (active / paused / draft).

Get one

GET /orchestrations/{id}

Returns the full definition of an orchestration — nodes, edges, triggers, settings.

Create

POST /orchestrations
Content-Type: application/json

{
  "name": "...",
  "description": "...",
  "trigger": { "kind": "manual" },
  "nodes": [ ... ],
  "edges": [ ... ]
}

Validates the structure and creates a draft. Use state=active to skip the draft step.

Update

PUT /orchestrations/{id}

Replaces the orchestration's definition. Optimistic concurrency via If-Match against the orchestration's version etag.

Delete

DELETE /orchestrations/{id}

Soft-deletes the orchestration. Pending runs continue; new runs blocked. Hard-delete via ?purge=true (Sovereign only).

Manual fire

POST /orchestrations/{id}/runs
Content-Type: application/json

{
  "input": { ... }
}

Returns the run ID immediately. The run executes asynchronously.

List runs

GET /orchestrations/{id}/runs?from=&to=&status=&limit=

Statuses: running, succeeded, failed, cancelled.

Get run trace

GET /orchestrations/{id}/runs/{run_id}

Returns the full structured trace: each node's input, output, duration, status.

Replay a run

POST /orchestrations/{id}/runs/{run_id}/replay

Creates a new run with the same input as the original. New run links back to the original via replays_run_id.

Cancel a run

DELETE /orchestrations/{id}/runs/{run_id}

Best-effort cancellation. In-progress nodes finish; subsequent nodes are skipped.

Templates

List

GET /templates

Returns the catalog of available starter templates.

Instantiate

POST /templates/{template_id}/instantiate
Content-Type: application/json

{
  "name": "..."
}

Creates a new orchestration from the template. You then customize and activate it.

Approvals

List pending

GET /approvals?pending=true

Returns approval-gated actions waiting for human action.

Approve / deny

POST /approvals/{id}/approve
POST /approvals/{id}/deny
Content-Type: application/json

{ "comment": "..." }

Resumes (or terminates) the orchestration.

Webhooks (orchestration-triggered)

Each orchestration with a webhook trigger has a unique URL we generate at activation:

https://<your-org-slug>.brrain.io/api/orchestrator/webhooks/{orchestration_id}/{secret}

Inbound payloads are HMAC-verified using the orchestration's signing secret. See API: Webhooks for signature semantics.

Metrics

Prometheus-compatible metrics endpoint:

GET /metrics
Authorization: Bearer {service-account-token}

Returns counters, gauges, and histograms for orchestration runs, durations, error rates, queue depth.

A pre-built Grafana dashboard is at:

GET /grafana.json

When an orchestration is marked public, it appears in the public gallery:

GET /gallery

No authentication required. Returns publicly-shared orchestration metadata (definitions are not exposed unless the owner opts into a public read).

Errors

Standard API errors. Orchestration-specific:

  • orchestration_not_active — can't fire a paused or draft orchestration.
  • trigger_mismatch — input shape doesn't match the trigger spec.
  • subflow_depth_exceeded — nested sub-orchestration calls exceed the depth limit.
  • approval_pending — action requires approval (returned by sync runs that hit an approval gate).

Where to next