> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Run a Blon workflow with your own inputs.

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

```bash theme={null}
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`.

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.