---
title: "Create a workflow"
method: POST
path: "/workflows"
tags: ["workflows"]
---

# Create a workflow

`POST /workflows`

## Request

- Base URL: `https://api.onplana.com/api`
- URL: `https://api.onplana.com/api/workflows`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

## Headers

- `X-Organization-Id` string, required

## Request body

- object
  - `name` string, required
  - `description` string
  - `projectId` string, uuid, nullable: null = org-wide.
  - `trigger` object, required
  - `graph` object, required
  - `isActive` boolean
  - `schedule` object, nullable
  - `maxRuns` integer, nullable

## Response `200`

Created

- Workflow
  - `id` string, uuid, required
  - `name` string, required
  - `description` string, nullable
  - `organizationId` string, uuid, required
  - `projectId` string, uuid, nullable: null = org-wide; set = scoped to one project.
  - `isActive` boolean, required
  - `trigger` object, required: Event that fires this workflow.
    - `event` string, required: e.g. "task.created", "project.status.changed", "intake.submitted"
  - `graph` object, required: Directed graph of conditions, actions, approval steps, and delays. See the Workflow Builder UI for the canonical shape.
  - `schedule` object, nullable: Cron-style schedule for time-triggered workflows.
  - `runCount` integer
  - `maxRuns` integer, nullable
  - `lastRunAt` string, date-time, nullable
  - `createdById` string, uuid
  - `createdAt` string, date-time, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized - missing or invalid JWT
- `402`: Plan gate. automations (Pro and above) for any workflow. A document trigger (DOCUMENT_UPLOADED, DOCUMENT_VERSION_ADDED) or a SET_DOCUMENT_STATUS step also needs documentApproval, Business and above, refused inside a downgrade's read-only window too (grace: true). Answered before the 400 WORKFLOW_DOCUMENT_TRIGGERS_OFF and WORKFLOW_DOCUMENT_ACTIONS_OFF of the server switch
- `403`: Forbidden - insufficient role

---

[API](https://skmtc.dev/onplana/apis/onplana-api.md) · [All operations](https://skmtc.dev/onplana/apis/onplana-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onplana/apis/onplana-api/revisions/c3d6c89e9dc8?raw)