---
title: "Create an approval workflow"
method: POST
path: "/api/v1/workspaces/{workspace_id}/approval-workflows"
tags: ["✅ Approval Workflows"]
---

# Create an approval workflow

`POST /api/v1/workspaces/{workspace_id}/approval-workflows`

## Request

- Base URL: `https://api.contentstudio.io`
- URL: `https://api.contentstudio.io/api/v1/workspaces/{workspace_id}/approval-workflows`
- Auth: API key in header `X-API-Key`

Create a multi-level approval workflow with up to 5 levels. Every member referenced in `levels[].members[]` must belong to the workspace team. A workflow with any level that has no members is stored as a draft and cannot be set as default. `is_default` is not accepted — use the set-default endpoint. Requires the `manage_workflow` permission.

## Path parameters

- `workspace_id` string, required

## Request body

- object
  - `name` string, required
  - `is_draft` boolean: Force draft status. A workflow with an unstaffed level is a draft regardless.
  - `levels` object[], required
    - `level_number` integer, required: Unique across the payload.
    - `title` string, nullable
    - `rule` 'anyone' | 'everyone', required
    - `members` object[], required
      - `user_id` string

## Response `201`

Approval workflow created

- ApprovalWorkflowCreated
  - `status` boolean
  - `message` string
  - `data` ApprovalWorkflow
    - `id` string
    - `_id` string: Deprecated alias for `id` — will be removed once clients migrate.
    - `name` string
    - `is_draft` boolean: A workflow with any unstaffed level is a draft; a draft cannot be attached to a post or made the default.
    - `is_default` boolean: At most one workflow per workspace is the default.
    - `levels` ApprovalWorkflowLevel[]
      - `level_number` integer
      - `title` string, nullable
      - `rule` 'anyone' | 'everyone': `anyone` clears the level on the first approval; `everyone` needs all members.
      - `members` ApprovalWorkflowMember[]: Empty makes the whole workflow a draft.
        - `user_id` string: Reusable OpenAPI schemas for the public-API approval-workflow and cascade-job responses. The workflow object is returned by eight endpoints (list, create, show, update, duplicate, set-default, remove-default and the two 202 cascade shapes), so it is described once here and referenced via `@OA\JsonContent(ref="#/components/schemas/<Name>")`.

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.
- `422`: Validation failed — duplicate level numbers, duplicate members in a level, a member outside the workspace, or more than 5 levels — or the create failed (`APPROVAL_WORKFLOW_CREATE_FAILED`)
- `429`: Too Many Requests - Rate limit exceeded

## Changes

- **2026-09-22** `ad0b687289a3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/changes/api/v1/workspaces/:workspace_id/approval-workflows/post.md)

---

[API](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1.md) - [All operations](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/revisions/2ce09d50369c?raw)