> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/manage/manage-workflows.md).

# Manage Workflows

## About

[Roboflow Workflows](https://docs.roboflow.com/workflows/build/create-a-workflow) are visual computer-vision pipelines you build in the web app and deploy as a hosted endpoint. This page covers the management surface - listing, retrieving, creating, and updating the Workflows in a workspace - through the REST API and Python SDK. To run a Workflow against an image or video stream, see the [Workflows runtime docs](https://docs.roboflow.com/workflows/deploy/deploy-a-workflow).

## HTTP API

[Roboflow Workflows](https://docs.roboflow.com/workflows/build/create-a-workflow) are visual computer-vision pipelines you can build in the web app and deploy as a hosted endpoint. The REST API exposes the management surface; for executing a workflow against an image or video stream, see [Run a Model on an Image](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api#http-api) and the [Workflows runtime docs](https://docs.roboflow.com/workflows/deploy/deploy-a-workflow).

`api_key` may be passed as a query parameter or in the request body. Required scopes are noted on each endpoint.

### List Workflows

<mark style="color:green;">`GET`</mark> `/:workspace/workflows`

Lists all workflows in the workspace.

**Query**

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>api_key</code></td><td>string</td><td>API key for the workspace.</td><td>true</td></tr></tbody></table>

**Example Request**

```bash
curl "https://api.roboflow.com/my-workspace/workflows?api_key=$ROBOFLOW_API_KEY"
```

**Response**

```json
{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Slow webhooks",
      "url": "slow-webhooks",
      "createdAt": "2026-04-12T17:05:33.000Z"
    }
  ],
  "status": "ok"
}
```

Required scope: `workflow:read`.

### Get a Workflow

<mark style="color:green;">`GET`</mark> `/:workspace/workflows/:workflowUrl`

Returns the workflow's specification, metadata, and (for non-public workflows) authorization status.

```bash
curl "https://api.roboflow.com/my-workspace/workflows/slow-webhooks?api_key=$ROBOFLOW_API_KEY"
```

Public workflows can be accessed without an `api_key`. Private workflows require the `workflow:read` scope.

### List Workflow Versions

<mark style="color:green;">`GET`</mark> `/:workspace/workflows/:workflowUrl/versions`

```bash
curl "https://api.roboflow.com/my-workspace/workflows/slow-webhooks/versions?api_key=$ROBOFLOW_API_KEY"
```

Returns the versioned snapshots of the workflow specification.

### Create a Workflow

<mark style="color:green;">`POST`</mark> `/:workspace/createWorkflow`

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Query**

<table><thead><tr><th width="180">Name</th><th width="140">Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>api_key</code></td><td>string</td><td>Workspace API key.</td><td>true</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name.</td><td>true</td></tr><tr><td><code>url</code></td><td>string</td><td>URL slug for the workflow. Auto-generated from <code>name</code> if omitted.</td><td>true</td></tr><tr><td><code>config</code></td><td>string</td><td>JSON-encoded workflow specification (see note below).</td><td>true</td></tr><tr><td><code>template</code></td><td>string</td><td>JSON-encoded template metadata. Pass <code>"{}"</code> if you don't have one.</td><td>true</td></tr></tbody></table>

**Note on `config`**: the API expects the stored shape `{"specification": {...}}`. Passing a bare specification works through the SDK adapter, which auto-wraps it; for direct REST calls, wrap it yourself.

**Example Request**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/createWorkflow" \
  --get \
  --data-urlencode "api_key=$ROBOFLOW_API_KEY" \
  --data-urlencode "name=My Workflow" \
  --data-urlencode "url=my-workflow" \
  --data-urlencode 'config={"specification":{"version":"1.0","inputs":[],"steps":[],"outputs":[]}}' \
  --data-urlencode 'template={}'
```

**Response**

```json
{
  "workflows": { "id": "wf_xyz789", "url": "my-workflow" },
  "status": "ok"
}
```

Required scope: `workflow:create`.

### Update a Workflow

<mark style="color:green;">`POST`</mark> `/:workspace/updateWorkflow`

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Workflow's internal ID.</td><td>true</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name.</td><td>true</td></tr><tr><td><code>url</code></td><td>string</td><td>URL slug.</td><td>true</td></tr><tr><td><code>config</code></td><td>string</td><td>JSON-encoded workflow specification (see note on Create).</td><td>true</td></tr></tbody></table>

```bash
curl -X POST "https://api.roboflow.com/my-workspace/updateWorkflow?api_key=$ROBOFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"id":"wf_xyz789","name":"My Workflow","url":"my-workflow","config":"{\"specification\":{\"version\":\"1.0\",\"steps\":[]}}"}'
```

Required scope: `workflow:update`.

### Fork a Workflow

<mark style="color:green;">`POST`</mark> `/:workspace/forkWorkflow`

Copy a workflow from another workspace into this one.

**Body**

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>source_workspace</code></td><td>string</td><td>Slug of the workspace that owns the source workflow.</td><td>true</td></tr><tr><td><code>source_workflow</code></td><td>string</td><td>URL slug of the source workflow.</td><td>true</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name for the fork. Defaults to source name.</td><td>false</td></tr><tr><td><code>url</code></td><td>string</td><td>URL slug for the fork. Auto-generated if omitted.</td><td>false</td></tr></tbody></table>

```bash
curl -X POST "https://api.roboflow.com/my-workspace/forkWorkflow?api_key=$ROBOFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"source_workspace":"other-workspace","source_workflow":"their-workflow","name":"My Fork","url":"my-fork"}'
```

Required scope: `workflow:create`.

### Generate a Workflow Token

<mark style="color:green;">`POST`</mark> `/:workspace/workflowToken`

Generate a short-lived token suitable for executing a workflow from a public client (e.g. a browser).

```bash
curl -X POST "https://api.roboflow.com/my-workspace/workflowToken?api_key=$ROBOFLOW_API_KEY"
```

### Delete (soft-delete) a Workflow

<mark style="color:red;">`DELETE`</mark> `/:workspace/workflows/:workflowUrl`

Moves the workflow to Trash. See [Manage Trash](https://docs.roboflow.com/platform/workspaces/trash#delete-a-workflow) for the response shape and restore flow.

### Run a Workflow

Workflow execution lives at `https://serverless.roboflow.com`, not the management API. See [Run a Model on an Image](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api#http-api) and the product docs on [deploying a workflow](https://docs.roboflow.com/workflows/deploy/deploy-a-workflow).

## Python SDK

[Roboflow Workflows](https://docs.roboflow.com/workflows/build/create-a-workflow) are visual computer-vision pipelines. The SDK exposes list / get / create directly on `Workspace`; update, fork, and delete live in the low-level `rfapi` adapter.

### List workflows

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()

workflows = workspace.list_workflows()
for w in workflows:
    print(w["id"], w["name"], w["url"])
```

### Get a workflow

```python
workflow = workspace.get_workflow("slow-webhooks")
print(workflow["specification"])
```

The `url` argument is the workflow's slug (visible in the web app's URL bar) - not its Firestore id.

### Create a workflow

```python
workflow = workspace.create_workflow(
    name="My Workflow",
    definition={
        "version": "1.0",
        "inputs": [...],
        "steps": [...],
        "outputs": [...],
    },
)
print(workflow["id"], workflow["url"])
```

Pass `definition=None` to create an empty workflow shell that you'll edit in the web app afterwards.

The SDK accepts either a bare specification dict (`{"version": ..., "steps": ...}`) or a wrapped one (`{"specification": {...}}`); it normalizes the wrapping for you and strips a UTF-8 BOM if present.

### Update a workflow

`Workspace` doesn't expose update directly - use the low-level adapter:

```python
from roboflow.adapters import rfapi

rfapi.update_workflow(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    workflow_id=workflow["id"],
    workflow_name="My Workflow",
    workflow_url="my-workflow",
    config={"version": "1.0", "steps": [...]},
)
```

### Fork a workflow

Copy a workflow from another workspace into your own. Useful for adopting a public template:

```python
from roboflow.adapters import rfapi

forked = rfapi.fork_workflow(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    source_workspace="other-workspace",
    source_workflow="their-workflow",
    name="My Fork",       # optional; defaults to the source name
    url="my-fork",        # optional; defaults to a generated slug
)
```

### List workflow versions

```python
versions = rfapi.list_workflow_versions(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    workflow_url="my-workflow",
)
```

### Delete (soft-delete) a workflow

```python
rfapi.delete_workflow(api_key="YOUR_API_KEY", workspace_url=workspace.url, workflow_url="my-workflow")
```

This moves the workflow to the workspace [Trash](https://docs.roboflow.com/platform/workspaces/trash#python-sdk) where it remains for 30 days before permanent cleanup. Restore via `Workspace.restore_from_trash("workflow", id)` - see [Delete and Restore](https://docs.roboflow.com/platform/workspaces/trash#workflows).

### Run a workflow

Workflow execution lives in the [Inference SDK](https://inference.roboflow.com) and the [Workflows runtime](https://docs.roboflow.com/workflows/deploy/deploy-a-workflow), not the `roboflow` package. From Python:

```python
from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key="YOUR_API_KEY",
)
result = client.run_workflow(
    workspace_name="my-workspace",
    workflow_id="my-workflow",
    images={"image": "photo.jpg"},
)
```

### REST and CLI equivalents

* REST: see [Manage Workflows](#http-api).
* CLI: see [Manage Workflows (CLI)](#cli).

## CLI

You can list, create, update, fork, and version workflows from the command line.

### List Workflows

```bash
roboflow workflow list
```

```bash
roboflow workflow list --json
```

### Get Workflow Details

```bash
roboflow workflow get my-workflow
```

```bash
roboflow workflow get my-workflow --json
```

### Create a Workflow

```bash
roboflow workflow create --name "My Workflow"
```

With a JSON definition file:

```bash
roboflow workflow create --name "My Workflow" --definition workflow.json
```

#### Options

| Flag            | Description                  |
| --------------- | ---------------------------- |
| `--name`        | Workflow name (required)     |
| `--definition`  | Path to JSON definition file |
| `--description` | Workflow description         |

### Update a Workflow

Update a workflow's definition:

```bash
roboflow workflow update my-workflow --definition updated.json
```

### List Workflow Versions

```bash
roboflow workflow version list my-workflow
```

```bash
roboflow workflow version list my-workflow --json
```

### Fork a Workflow

Fork a workflow from the current workspace:

```bash
roboflow workflow fork my-workflow
```

Fork from another workspace:

```bash
roboflow workflow fork other-workspace/their-workflow
```

### JSON Output

All workflow commands support `--json` for structured output:

```bash
roboflow workflow list --json | jq '.[].name'
roboflow workflow create --name "Test" --json
```

Exit codes: 0 = success, 1 = error, 2 = auth error, 3 = not found.