HTTP API reference

The development API origin is http://127.0.0.1:3000. All workflow routes below use /v1. Send credentials as Authorization: Bearer <credential>.

“Developer” means an Auth0 user access token for an authorized account. “Invocation” means a Banh invocation key for that account.

Endpoints

Method	Route	Credential	Purpose
GET	/v1/auth/config	None	Public Auth0 device-login settings.
GET	/v1/me	Developer	Current user and account; optional accountId query.
POST	/v1/accounts/:accountId/workflows/:workflowSlug/versions	Developer	Deploy YAML.
POST	/v1/accounts/:accountId/workflows/:workflowSlug/runs	Developer or invocation	Invoke active version.
GET	/v1/accounts/:accountId/workflows/:workflowSlug/runs	Developer	List runs.
GET	/v1/accounts/:accountId/runs/:runId	Developer	Inspect a run, including input.
GET	/health	None	HTTP liveness.
GET	/ready	None	Database and schema readiness.

Deploy

{ "sourceYaml": "version: 1\nprocess: ..." }

The source must be a complete valid Banh workflow, with process matching workflowSlug. The server compiles the source itself and ignores optional client-provided compiled data. Success returns HTTP 201 and the deployment result, including its version. Every successful request creates a new version.

See the complete deployment example.

Invoke

{ "input": { "message": "My invoice has a duplicate charge." } }

The supplied input must match the workflow’s input type. Success returns HTTP 200 and the recorded run. Execution errors return HTTP 500 or 504 with the failed run, rather than the normal validation-error shape.

The cloud backend currently returns fixed test answers. See invocation.

List and inspect

List accepts limit (1–100, default 50) and offset (0–10000, default 0). It returns { "runs": [...], "limit": 50, "offset": 0 }. Inspect returns one run plus its stored input. See runs and versions.

Status codes

Status	Meaning
400	Invalid request, input, workflow, or process/slug mismatch.
401	Missing or invalid bearer credentials.
403	Credential lacks account access or the required developer role.
404	Workflow or run not found in the authorized account.
413	Request body or source YAML exceeds the allowed size.
429	Rate limit reached.
500	Server or execution failure.
504	Execution deadline exceeded.

Execution errors expose a generic diagnostic and run ID. Backend error text and stack traces are not returned. Request sizes, rate limits, and timeout behavior are documented under limits.