Workflows

A workflow is a graph of steps built on a Blon canvas. A run always targets one exact revision of a workflow, identified by its id, with a fixed list of inputs and outputs. Workflow responses use camelCase field names.

Read the interface

curl https://api.blon.ai/v1/workflows/$REVISION_ID \
  -H "Authorization: Bearer $BLON_API_KEY"

The response describes the revision:

Field	Meaning
`id`, `version`	The revision and its version number
`inputs`	Each with `id`, `description`, `required`, `schema`, `cardinality` and an optional `default`
`outputs`	Each with `id`, `label`, `schema` and `cardinality`

An input’s schema.kind is one of the same value kinds as model inputs: text, number, boolean, media, list or voice. A media value is { "asset_id": "…" } or { "url": "https://…" }.

Start a run

Idempotency-Key is required. Without it the request fails with 400 bad_request.

curl https://api.blon.ai/v1/workflows/$REVISION_ID/runs \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"inputs":{"prompt":"A ceramic teapot on a linen table"}}'

The 202 response holds runId, status and statusUrl. The same key returns the same run; the same key with different inputs returns 409 idempotency_conflict.

Read the run

curl https://api.blon.ai/v1/workflow-runs/$RUN_ID \
  -H "Authorization: Bearer $BLON_API_KEY"

Field	Meaning
`status`	`PLANNED`, `RUNNING`, `SUCCEEDED`, `PARTIAL`, `FAILED` or `CANCELLED`
`nodes`	Each step’s `nodeId`, `status` and `progress`
`errors`	`nodeId` and `message` for each failed step
`creditSummary`	`quotedCredits` and `chargedCredits`
`outputs`, `missing`	The declared outputs once the run has produced them, and the ones it did not
`createdAt`, `startedAt`, `completedAt`	Timestamps

SUCCEEDED, PARTIAL, FAILED and CANCELLED are terminal.

From the CLI

blon workflows get $REVISION_ID
blon workflows run $REVISION_ID --prompt "A ceramic teapot" --wait

Each workflow input becomes a --<inputId> flag. Media, list and voice values take JSON.

Errors

Error	When
`404 not_found`	No such revision or run, or you cannot read it
`400 invalid_input`	The body is not `{ "inputs": { … } }`
`402 insufficient_credits`	The balance does not cover the run
`412 precondition_failed`	The revision cannot be run as is

Get started

Concepts

How-to

Models

Help

Read the interface

Start a run

Read the run

From the CLI

Errors

​Read the interface

​Start a run

​Read the run

​From the CLI

​Errors

Read the interface

Start a run

Read the run

From the CLI

Errors