---
title: "Update a workflow"
method: PATCH
path: "/workflows/{uid}"
---

# Update a workflow

`PATCH /workflows/{uid}`

## Request

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

Change metadata, inputs or steps. Each of `inputs` and `steps` is replaced wholesale when present and left alone when omitted, so renaming a workflow does not disturb its definition. Read the workflow first and send back the full array with your changes applied.

## Path parameters

- `uid` string, required

## Request body

- object
  - `name` string
  - `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 `200`

Updated workflow

- 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

- `403`: Workflow's api_write_access is `owner_only` and the caller's key is not owned by its creator
- `404`: Workflow not found in this workspace
- `422`: Validation failure — duplicate step key, unknown ref, or a forward step reference
- `423`: Workflow is locked from API updates

## Changes

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

[Operation history](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api/changes/workflows/:uid/patch.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)