Skip to navigation
ReferenceAPI Referenceworkflows

Create Workflow

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.

name is optional. Omit it to get the server-side placeholder "Untitled workflow" (name_source: "placeholder"), which the assistant auto-names from the first message via POST /workflows/{id}/name/generate. An explicit name is stored as-is with name_source: "user".

Authentication

AuthorizationBearer
Clerk JWT token
OR
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.
namestring or nullOptional1-200 characters

Human-readable workflow name (1–200 characters, non-blank). Omit to create an unnamed workflow that gets a server-side placeholder and is auto-named from the first assistant message.

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