---
title: "Create a workflow"
method: POST
path: "/workflows"
---

# Create a workflow

`POST /workflows`

## Request

- Base URL: `https://api.bannerbear.com/v5`
- URL: `https://api.bannerbear.com/v5/workflows`
- Auth: HTTP bearer

Create a workflow with its inputs and steps in one call. Every step's `ref` is validated against its adapter — an unknown tool slug or a template UID outside this workspace is rejected — and a step may only reference steps before it.

## Request body

- object
  - `name` string, required
  - `description` string, nullable
  - `tags` string[]
  - `inputs` object: Inputs the workflow accepts, keyed by name. Omit to leave the existing inputs untouched; send {} to clear them.
  - `steps` object[]: The ordered step list, replaced wholesale. Array order IS execution order, so reorder by sending the array in the order you want. Omit to leave the existing steps untouched. A step dropped from the array is discarded, not deleted — its past runs still reference it.
    - `key` string, required: Stable handle for this step, unique within the workflow. Later steps reference its output as {{steps.<key>.<output>}}. Lowercase letters, numbers and underscores.
    - `type` 'tool' | 'image' | 'animation', required: What kind of operation this step performs
    - `ref` string, required: What it operates on — a tool slug for `tool` steps (see GET /tools), or a template UID for `image` and `animation` steps
    - `inputs` object: Step payload. Values may reference the workflow's own inputs as {{inputs.<name>}} or an EARLIER step's output as {{steps.<key>.<output>}} — referencing a later step is rejected.

## Response `201`

Workflow created

- object
  - `uid` string
  - `name` string
  - `description` string, nullable
  - `tags` string[]
  - `inputs` object: Inputs this workflow accepts, keyed by name. Each value is { type, required }. `url`-typed inputs are validated as http(s) URLs when a run is created.
  - `steps` object[]: Steps in run order
    - `key` string: Stable handle for this step; later steps reference it as {{steps.<key>.<output>}}
    - `type` 'tool' | 'image' | 'animation': What kind of operation this step performs
    - `ref` string: Tool slug, or template UID for image / animation steps
    - `label` string: Human name of the step's target — the tool's label or the template's name
    - `inputs` object: Step payload, with {{inputs.x}} / {{steps.x.y}} references unresolved
  - `ui_write_access` 'owner_only' | 'team'
  - `api_write_access` 'team' | 'owner_only' | 'nobody': Who may run this workflow via the API
  - `created_at` string, date-time

## Other responses

- `422`: Validation failure — missing name, duplicate step key, unknown ref, or a forward step reference

## Changes

- **2026-09-09** `b98735eaab44`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api/changes/workflows/post.md)

---

[API](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api.md) - [All operations](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api/revisions/357256cbd1e5?raw)