> 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

Organize Workflows in folders and manage them through the web app, REST API, Python SDK, and CLI.

## About

[Roboflow Workflows](https://docs.roboflow.com/workflows/build/create-a-workflow.md) are visual computer vision pipelines you build in the web app and deploy as a hosted endpoint. This page covers how to organize, list, get, create, update, and fork the Workflows in a Workspace through the web app, HTTP API, Python SDK, and CLI. To run a Workflow on an image or video stream, see [Deploy a Workflow](https://docs.roboflow.com/workflows/deploy/deploy-a-workflow.md).

## Web App

### Organize Workflows

To group related Workflows, click the folder-plus button on the Workflows page, enter a name, and click "Create Folder". To move a Workflow, open its three-dot menu, choose "Move Workflow", select a destination, and click "Move Workflow".

If your role can manage [Folder Permissions](https://docs.roboflow.com/datasets/manage/project-folders/project-folder-permissions), open a folder's three-dot menu and choose "Set Permissions" to control who can read or edit its Workflows.

## HTTP API

These endpoints manage Workflows. They do not run them: Workflows run on the Serverless Hosted API (ex: `https://serverless.roboflow.com`).

### Project Base Workflows

Each Project has a base Workflow that backs its hosted model endpoint. Use these endpoints to read that Workflow or pick the model it runs. To turn on data collection, set collection limits, or list images in the review queue, use the [Active Learning HTTP API](https://docs.roboflow.com/deployment/monitoring-and-analytics/active-learning#http-api).

#### Get a Project Base Workflow

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/{project}/deploy" method="get" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

#### Select a Project Base Workflow Model

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/{project}/deploy/model" method="post" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

### List Workflows

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/workflows" method="get" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

### Get a Workflow

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/workflows/{workflowId}" method="get" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

### List Workflow Versions

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/workflows/{workflowId}/versions" method="get" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

### Create a Workflow

Wrap the specification as `{"specification": {...}}` and send it as a JSON string in `config`. The Python SDK does the wrapping for you, but a direct HTTP call must do it.

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/createWorkflow" method="post" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

### Update a Workflow

An update replaces the whole specification, saves a new version, and publishes it when the Workflow has no deploy gates. A gated Workflow rejects this direct publish: use [Save and Publish a Version](#save-and-publish-a-version). Send the Workflow `id` from List Workflows, not its URL slug. Project base Workflows cannot be updated here.

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/updateWorkflow" method="post" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

### Save and Publish a Version

Select a saved version, or save a new candidate without publishing, then run its required checks and publish the version that passed. Fetch the Workspace's deploy gate OpenAPI document for the operation schemas and required scopes:

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/workspaces/{workspace}/workflows/deploy-gates/openapi.json" method="get" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

All paths below start with `https://api.roboflow.com/workspaces/{workspace}/workflows`:

1. Reuse the selected saved version when it has the intended definition. If you need a new candidate, send `POST /{workflowId}/versions` with the complete definition. This saves a draft without publishing or starting checks, including in Auto-Publish mode.
2. For an Eval gate, send `POST /{workflowId}/versions/{versionId}/deploy-gates/run`. This can use inference credits. For manual approval, read `GET /{workflowId}/versions/{versionId}/deploy-gates/manual-approval` and have an eligible person approve in the Roboflow app. A manual-only version needs no run call; the API cannot approve it.
3. Poll `GET /{workflowId}/versions/{versionId}/deploy-gates` while checks are pending. If a gate fails, errors, or is cancelled, or an approver rejects the version, stop and report the result. Send `POST /{workflowId}/versions/{versionId}/deploy` only when `publishable` is `true`. In Auto-Publish mode, the latest saved draft can publish automatically after every gate passes.

The save and check-run operations need a UUID v4 `Idempotency-Key` header. Reuse it when retrying the same request.

### Fork a Workflow

Copy a Workflow from this workspace or a Roboflow template into this workspace. A folder-scoped API key places the copy by the same folder rules as Create a Workflow. To copy a Workflow from another workspace, open its [share link](https://docs.roboflow.com/workflows/manage/share-a-workflow.md) and fork it there.

{% openapi src="/files/WtZ3qJUkrI479pp2yxE4" path="/{workspace}/forkWorkflow" method="post" %}
[manage-workflows.yaml](https://1126624165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-cb5465e92b4a63ad94cd20d120789841c53a3a27%2Fmanage-workflows.yaml?alt=media)
{% endopenapi %}

### Delete a Workflow

Deleting a Workflow moves it to Trash, where you can restore it. Learn how in [Manage Trash](https://docs.roboflow.com/platform/workspaces/trash#delete-a-workflow).

## Python SDK

[Roboflow Workflows](https://docs.roboflow.com/workflows/build/create-a-workflow.md) 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 within your workspace. To start from a Roboflow template, set `source_workspace` to `templates`:

```python
from roboflow.adapters import rfapi

forked = rfapi.fork_workflow(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    source_workspace=workspace.url,
    source_workflow="my-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.md), not the `roboflow` package. From Python:

```python
from inference_sdk import InferenceHTTPClient, InferenceConfiguration

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

## 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 a Roboflow template:

```bash
roboflow workflow fork templates/general-segmentation-api
```

### 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.

## MCP Server

Connect your AI agent to the [MCP Server](https://docs.roboflow.com/agents/mcp-server) to build and run Workflows.

Use `workflow_versions_save` to save a draft, `workflow_version_deploy_gates_run` for Eval checks, and `workflow_version_deploy_gates_get` to read every gate's verdict. For manual approval, read `workflow_version_approval_get` and ask an eligible person to decide in the Roboflow app. Call `workflow_version_deploy` only when `publishable` is `true`. MCP cannot approve a Workflow version.

<table data-search="false"><thead><tr><th width="290">Tool</th><th>Description</th></tr></thead><tbody><tr><td><code>workflows_list</code></td><td>List saved Workflows in the workspace.</td></tr><tr><td><code>workflows_get</code></td><td>Get details for a saved Workflow.</td></tr><tr><td><code>workflows_create</code></td><td>Create and save a new Workflow.</td></tr><tr><td><code>workflows_update</code></td><td>Update a saved Workflow's name and definition.</td></tr><tr><td><code>workflows_run</code></td><td>Execute a saved Workflow on one or more images.</td></tr><tr><td><code>workflows_delete</code></td><td>Delete a saved Workflow, moving it to the workspace Trash.</td></tr></tbody></table>
