> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.awork.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server.

# Workflows

> Workflows API Reference.

![awork workflow status mapping from existing project statuses to a shared workflow](/_fern-img/d71b7e11e9c14d72bf38d944b809da7759a708e67538a750649a0d5df76c096b.webp)

Workflows are reusable process definitions that let you share project statuses and task statuses across multiple projects. Instead of maintaining statuses per project, you can manage them once in a workflow and keep linked projects aligned.

> **Note**
>
> Workflows are being rolled out gradually across workspaces and might not be available in every workspace yet.

## How to work with workflows

### Create a workflow

Create a reusable workflow in your workspace.

**`Create a workflow`**

```sh title="Create a workflow"
curl -X POST https://api.awork.com/api/v1/workflows \
-H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Client Delivery Workflow",
    "icon": "workflow"
  }'
```

### Link a workflow to a project

Linking applies workflow-controlled statuses to the project. If the project already has statuses, provide mappings to migrate safely.

**`Link workflow to a project`**

```sh title="Link workflow to a project" {5}
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/linkworkflow \
-H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "workflowId": "223e4567-e89b-12d3-a456-426614174000",
    "projectStatusMapping": [
      {
        "oldProjectStatusId": "323e4567-e89b-12d3-a456-426614174000",
        "newProjectStatusId": "423e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "taskStatusMapping": [
      {
        "oldTaskStatusId": "523e4567-e89b-12d3-a456-426614174000",
        "newTaskStatusId": "623e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "keepCustomFields": true,
    "keepCustomAutomations": true
  }'
```

### Create a workflow from an existing project

Use an existing project as a blueprint and optionally link that project to the newly created workflow.

**`Create workflow from project configuration`**

```sh title="Create workflow from project configuration"
curl -X POST https://api.awork.com/api/v1/workflows/fromproject/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Workflow from Consulting Template",
    "copyProjectStatuses": true,
    "copyTaskStatuses": true,
    "copyCustomFields": true,
    "copyAutomations": true,
    "linkProjectToWorkflow": true
  }'
```

### Manage shared statuses in a workflow

You can manage workflow-level statuses, which are then shared across linked projects.

**`Create task status in a workflow`**

```sh title="Create task status in a workflow"
curl -X POST https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/taskstatuses \
-H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Client Feedback",
    "type": "review",
    "order": 3,
    "icon": "comment"
  }'
```

**`Create project status in a workflow`**

```sh title="Create project status in a workflow"
curl -X POST https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/projectstatuses \
-H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Blocked by Client",
    "type": "stuck"
  }'
```

### Unlink a workflow from a project

Unlinking decouples the project from workflow sync and clones workflow statuses into editable project-specific statuses.

**`Unlink workflow from project`**

```sh title="Unlink workflow from project"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/unlinkworkflow \
-H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/json'
```