Create Workflow

{
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "user_id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "name": "Customer Onboarding Workflow",
    "definition": {},
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "description": "Workflow to automate the customer onboarding process including data validation and welcome email.",
    "runs_count": 0,
    "last_run_at": "2024-01-15T09:30:00Z",
    "last_run_status": "pending"
  },
  "meta": {
    "request_id": "req_4f5e6d7c8b9a0d1e2f3a4b5c",
    "timestamp": "2024-01-15T09:30:00Z"
  }
}

Create a new workflow in the current workspace.

Validates the workflow definition (graph structure, node types, edge connectivity) before persisting. Returns 422 with structured details if the definition fails validation. Requires at least editor role in the workspace; viewers cannot create workflows.

The definition contains a graph (nodes and edges) and an execution block (ordered step list and execution params). Omitting definition creates a workflow with an empty graph that can be edited later.

Create a new workflow in the current workspace. Validates the workflow `definition` (graph structure, node types, edge connectivity) before persisting. Returns 422 with structured details if the definition fails validation. Requires at least `editor` role in the workspace; viewers cannot create workflows. The `definition` contains a `graph` (nodes and edges) and an `execution` block (ordered step list and execution params). Omitting `definition` creates a workflow with an empty graph that can be edited later.

Authentication

AuthorizationBearer

Clerk JWT token

AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Headers

X-Workspace-Idstring or nullOptional

Request

This endpoint expects an object.

namestringRequired1-200 characters

Human-readable workflow name (1–200 characters, non-blank).

descriptionstring or nullOptional<=5000 characters

Optional description shown in the workflow list (max 5000 characters).

definitionobjectOptional

Graph and execution config. Omit to create an empty workflow.

Response

Successful Response

dataobject

metaobject

Errors

422

Unprocessable Entity Error

$	curl -X POST https://api.onepin.ai/api/v1/workflows \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "Customer Onboarding Workflow"
>	}'