Skip to main content
POST
/
v1
/
workflows
from retab import Retab

client = Retab()

workflow = client.workflows.create(
    name="Invoice Processing",
    description="Extract invoice fields and route for review",
    project_id="project_abc",
)

print(workflow.id)
print(workflow.published)  # None — newly created workflows are unpublished

{
  "id": "wf_abc123xyz",
  "name": "Invoice Processing",
  "description": "Extract invoice fields and route for review",
  "published": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}
Create a new workflow. The workflow is created unpublished, with a default start_document block at canvas position (0, 0). Use the Blocks and Edges endpoints to build out the graph, then Publish when you’re ready to run it. 
from retab import Retab

client = Retab()

workflow = client.workflows.create(
    name="Invoice Processing",
    description="Extract invoice fields and route for review",
    project_id="project_abc",
)

print(workflow.id)
print(workflow.published)  # None — newly created workflows are unpublished

{
  "id": "wf_abc123xyz",
  "name": "Invoice Processing",
  "description": "Extract invoice fields and route for review",
  "published": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body for creating a workflow. Supply a name and optional description; the workflow starts empty.

​
project_id
string
required

Project that should own this workflow.

​
name
string
default:Untitled Workflow

The name of the workflow

Maximum string length: 200
​
description
string
default:""

Description of the workflow

Maximum string length: 4000

Response

Successful Response

A workflow and its current configuration.

​
id
string
required

Unique ID for this workflow

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
name
string
default:Untitled Workflow

The name of the workflow

​
description
string
default:""

Description of the workflow

​
project_id
string | null

Project that owns this workflow. Null only on legacy rows that predate the project backfill.

​
published
WorkflowPublished · object

Published workflow metadata when a published version exists

​
capabilities
enum<string>[] | null

Server-derived permissions for the current actor.

Available options:
workflow:view,
workflow:edit,
workflow:run,
workflow:delete,
workflow:publish,
workflow:review,
workflow:manage
​
authz_status
enum<string> | null

Provisioning state of this workflow's WorkOS authorization resource.

Available options:
provisioning,
ready,
failed,
deleting,
deleted