> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Workflow
> Create a new workflow.
The workflow starts unpublished with a default "Document" input block.
Create a new workflow. The workflow is created unpublished, with a default `start_document` block at canvas position `(0, 0)`. Use the [Blocks](/api-reference/workflows/blocks/create) and [Edges](/api-reference/workflows/edges/create) endpoints to build out the graph, then [Publish](/api-reference/workflows/publish) when you're ready to run it.
```python Python theme={null}
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
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const workflow = await client.workflows.create("Invoice Processing", "Extract invoice fields and route for review");
console.log(workflow.id);
console.log(workflow.published);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
retab "github.com/retab-dev/retab/clients/go"
)
func ptr[T any](v T) *T { return &v }
func main() {
ctx := context.Background()
client, err := retab.NewClient("")
if err != nil {
log.Fatal(err)
}
workflow, err := client.Workflows.Create(ctx, &retab.WorkflowsCreateParams{
Name: ptr("Invoice Processing"),
Description: ptr("Extract invoice fields and route for review"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(workflow.ID)
fmt.Println(workflow.Published)
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
workflow = client.workflows.create(
name: 'Invoice Processing',
description: 'Extract invoice fields and route for review',
)
puts workflow.id
puts workflow.published
```
```rust Rust theme={null}
use retab::models::CreateWorkflowRequest;
use retab::resources::workflows::CreateParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let workflow = client
.workflows()
.create(CreateParams::new(CreateWorkflowRequest {
name: Some("Invoice Processing".into()),
description: Some("Extract invoice fields and route for review".into()),
project_id: "project_abc".into(),
}))
.await?;
println!("{}", workflow.id);
println!("{:?}", workflow.published);
Ok(())
}
```
```php PHP theme={null}
workflows()->create();
print_r($result);
```
```csharp C# theme={null}
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Workflows.CreateAsync(new WorkflowsCreateOptions());
Console.WriteLine(result);
```
```java Java theme={null}
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.workflows().create("Invoice Processing", "Extract invoice fields", null);
System.out.println(result);
}
}
```
```curl cURL theme={null}
curl -X 'POST' \
'https://api.retab.com/v1/workflows' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"name": "Invoice Processing",
"description": "Extract invoice fields and route for review"
}'
```
```json 201 theme={null}
{
"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"
}
```
## OpenAPI
````yaml POST /v1/workflows
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows:
post:
tags:
- Workflows
summary: Create Workflow
description: |-
Create a new workflow.
The workflow starts unpublished with a default "Document" input block.
operationId: create_workflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWorkflowRequest'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Workflow'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
CreateWorkflowRequest:
properties:
name:
type: string
maxLength: 200
title: Name
description: The name of the workflow
default: Untitled Workflow
description:
type: string
maxLength: 4000
title: Description
description: Description of the workflow
default: ''
project_id:
type: string
title: Project Id
description: Project that should own this workflow.
type: object
required:
- project_id
title: CreateWorkflowRequest
description: >-
Body for creating a workflow. Supply a `name` and optional
`description`; the workflow starts empty.
Workflow:
properties:
id:
type: string
title: Id
description: Unique ID for this workflow
name:
type: string
title: Name
description: The name of the workflow
default: Untitled Workflow
description:
type: string
title: Description
description: Description of the workflow
default: ''
project_id:
anyOf:
- type: string
- type: 'null'
title: Project Id
description: >-
Project that owns this workflow. Null only on legacy rows that
predate the project backfill.
published:
anyOf:
- $ref: '#/components/schemas/WorkflowPublished'
- type: 'null'
description: Published workflow metadata when a published version exists
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- created_at
- id
- updated_at
title: Workflow
description: A workflow and its current configuration.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
WorkflowPublished:
properties:
version_id:
anyOf:
- type: string
- type: 'null'
title: Version Id
description: Published content-addressed workflow version ID
published_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Published At
description: When the workflow was last published
description:
type: string
title: Description
description: >-
Release note attached to the currently published version. Echoes the
`description` body passed to `POST /v1/workflows/{id}/publish` so
the caller can confirm it was stored without a separate fetch.
default: ''
type: object
title: WorkflowPublished
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
default: null
ctx:
type: object
title: Context
default: {}
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````