# Workflows API Reference

> Complete API reference for the Stack0 AI Workflows API.

Complete REST API reference for AI Workflows.

## Base URL

base-urlCopy

```
https://api.stack0.dev/v1
```

## Authentication

All API requests require authentication using your API key:

authenticationCopy

```
curl -X POST https://api.stack0.dev/v1/workflows \  -H "Authorization: Bearer sk_live_your_api_key" \  -H "Content-Type: application/json" \  -d '{"projectSlug": "my-project", "slug": "my-workflow", "name": "My Workflow"}'
```

POST`/workflows`

Create a new workflow.

#### Request Body

| Field | Type | Description |
| --- | --- | --- |
| projectSlug | string | Project identifier (required) |
| slug | string | Unique workflow slug (required) |
| name | string | Display name (required) |
| description | string | Workflow description |
| steps | StepDefinition[] | Array of step definitions |
| variables | object | Variable definitions |

request-body.jsonCopy

```
{  "projectSlug": "my-project",  "slug": "content-pipeline",  "name": "Content Pipeline",  "steps": [    {      "id": "step-1",      "type": "llm",      "name": "Generate",      "provider": "anthropic",      "model": "claude-3-5-sonnet-20241022",      "prompt": "Write about {{topic}}"    }  ],  "variables": {    "topic": { "type": "string", "required": true }  }}
```

GET`/workflows`

List all workflows for a project.

#### Query Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| projectSlug | string | Project identifier (required) |
| limit | number | Max results (default: 20) |
| offset | number | Pagination offset |

GET`/workflows/:id`

Get a specific workflow by ID.

PATCH`/workflows/:id`

Update a workflow.

DELETE`/workflows/:id`

Delete a workflow.

POST`/workflows/:id/run`

Start a workflow run.

#### Request Body

| Field | Type | Description |
| --- | --- | --- |
| projectSlug | string | Project identifier (required) |
| variables | object | Input variables |
| webhook | object | Webhook configuration |
| metadata | object | Custom metadata |

run-request.jsonCopy

```
{  "projectSlug": "my-project",  "variables": {    "topic": "AI in Healthcare"  },  "webhook": {    "url": "https://yourapp.com/webhook",    "secret": "your-secret"  },  "metadata": {    "userId": "user_123"  }}
```

#### Response

run-response.jsonCopy

```
{  "id": "run_xyz789",  "workflowId": "workflow_abc123",  "status": "pending",  "variables": { "topic": "AI in Healthcare" },  "metadata": { "userId": "user_123" },  "totalSteps": 2,  "completedSteps": 0,  "createdAt": "2025-01-15T10:30:00Z"}
```

GET`/workflows/runs/:id`

Get a workflow run by ID.

#### Response

get-run-response.jsonCopy

```
{  "id": "run_xyz789",  "workflowId": "workflow_abc123",  "status": "completed",  "variables": { "topic": "AI in Healthcare" },  "output": {    "outline": "1. Introduction...",    "content": "AI is transforming healthcare..."  },  "stepStates": {    "generate-outline": {      "status": "completed",      "startedAt": "2025-01-15T10:30:01Z",      "completedAt": "2025-01-15T10:30:05Z",      "attempts": 1    },    "write-content": {      "status": "completed",      "startedAt": "2025-01-15T10:30:05Z",      "completedAt": "2025-01-15T10:30:12Z",      "attempts": 1    }  },  "totalSteps": 2,  "completedSteps": 2,  "totalDurationMs": 11000,  "creditsUsed": 15,  "startedAt": "2025-01-15T10:30:01Z",  "completedAt": "2025-01-15T10:30:12Z",  "createdAt": "2025-01-15T10:30:00Z"}
```

GET`/workflows/runs`

List workflow runs.

#### Query Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| projectSlug | string | Project identifier (required) |
| workflowId | string | Filter by workflow ID |
| status | string | pending, running, completed, failed, cancelled |
| limit | number | Max results (default: 50) |
| offset | number | Pagination offset |

POST`/workflows/runs/:id/cancel`

Cancel a running workflow.

## Step Definition

Structure of a workflow step:

| Field | Type | Description |
| --- | --- | --- |
| id | string | Unique step identifier |
| type | string | llm, image, video, audio, code, http, transform, condition, loop |
| name | string | Display name |
| provider | string | anthropic, openai, gemini, replicate, stack0 |
| model | string | Model identifier |
| prompt | string | Prompt template (supports {{variables}}) |
| dependsOn | string[] | Step IDs this step depends on |
| outputVariable | string | Name for output in result |

## Run Status Values

| Status | Description |
| --- | --- |
| pending | Run created, waiting to start |
| running | Workflow executing steps |
| completed | All steps completed successfully |
| failed | One or more steps failed |
| cancelled | Run was cancelled |

### Related

[SDK Examples](https://www.stack0.dev/docs/sdk/workflows)[Authentication](https://www.stack0.dev/docs/authentication)[Error Handling](https://www.stack0.dev/docs/errors)

---

Source: https://www.stack0.dev/docs/api-reference/workflows
llms.txt: https://www.stack0.dev/llms.txt
Sitemap: https://www.stack0.dev/sitemap.xml
Documentation: https://www.stack0.dev/docs
OpenAPI spec: https://www.stack0.dev/openapi.json
MCP server: https://api.stack0.dev/mcp
