Skip to main content
POST
/
v1
/
workflows
/
{workflow_id}
/
blocks
/
batch
from retab import Retab

client = Retab()

blocks = client.workflows.blocks.create_batch(
    workflow_id="wf_abc123xyz",
    blocks=[
        {
            "id": "start-1",
            "type": "start",
            "label": "Invoice Input",
            "position_x": 0,
            "position_y": 0,
        },
        {
            "id": "extract-1",
            "type": "extract",
            "label": "Extract Invoice Fields",
            "position_x": 320,
            "position_y": 0,
            "config": {
                "model": "gpt-5",
                "json_schema": {
                    "type": "object",
                    "properties": {"total": {"type": "number"}},
                },
            },
        },
        {
            "id": "hil-1",
            "type": "hil",
            "label": "Human Review",
            "position_x": 640,
            "position_y": 0,
        },
    ],
)

for block in blocks:
    print(block.id, block.type)

[
  {
    "id": "start-1",
    "workflow_id": "wf_abc123xyz",
    "organization_id": "org_123",
    "draft_version": "draft_v3",
    "type": "start",
    "label": "Invoice Input",
    "position_x": 0,
    "position_y": 0,
    "width": null,
    "height": null,
    "config": null,
    "parent_id": null,
    "resolved_schemas": {"input_schemas": {}, "output_schemas": {}},
    "updated_at": "2026-05-01T14:30:00Z"
  },
  {
    "id": "extract-1",
    "workflow_id": "wf_abc123xyz",
    "organization_id": "org_123",
    "draft_version": "draft_v3",
    "type": "extract",
    "label": "Extract Invoice Fields",
    "position_x": 320,
    "position_y": 0,
    "width": null,
    "height": null,
    "config": {
      "model": "gpt-5",
      "json_schema": {
        "type": "object",
        "properties": {"total": {"type": "number"}}
      }
    },
    "parent_id": null,
    "resolved_schemas": {
      "input_schemas": {},
      "output_schemas": {
        "output-json-0": {
          "type": "object",
          "properties": {"total": {"type": "number"}}
        }
      }
    },
    "updated_at": "2026-05-01T14:30:00Z"
  },
  {
    "id": "hil-1",
    "workflow_id": "wf_abc123xyz",
    "organization_id": "org_123",
    "draft_version": "draft_v3",
    "type": "hil",
    "label": "Human Review",
    "position_x": 640,
    "position_y": 0,
    "width": null,
    "height": null,
    "config": null,
    "parent_id": null,
    "resolved_schemas": {"input_schemas": {}, "output_schemas": {}},
    "updated_at": "2026-05-01T14:30:00Z"
  }
]

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 multiple blocks in a single request. Useful when scaffolding a workflow programmatically — pair it with Create Edges (batch) to build the whole graph in two calls. Each entry has the same shape as the body of Create Block. The whole batch is rejected if any entry is invalid (duplicate ID, input block inside a container, unknown parent_id, …). 
from retab import Retab

client = Retab()

blocks = client.workflows.blocks.create_batch(
    workflow_id="wf_abc123xyz",
    blocks=[
        {
            "id": "start-1",
            "type": "start",
            "label": "Invoice Input",
            "position_x": 0,
            "position_y": 0,
        },
        {
            "id": "extract-1",
            "type": "extract",
            "label": "Extract Invoice Fields",
            "position_x": 320,
            "position_y": 0,
            "config": {
                "model": "gpt-5",
                "json_schema": {
                    "type": "object",
                    "properties": {"total": {"type": "number"}},
                },
            },
        },
        {
            "id": "hil-1",
            "type": "hil",
            "label": "Human Review",
            "position_x": 640,
            "position_y": 0,
        },
    ],
)

for block in blocks:
    print(block.id, block.type)

[
  {
    "id": "start-1",
    "workflow_id": "wf_abc123xyz",
    "organization_id": "org_123",
    "draft_version": "draft_v3",
    "type": "start",
    "label": "Invoice Input",
    "position_x": 0,
    "position_y": 0,
    "width": null,
    "height": null,
    "config": null,
    "parent_id": null,
    "resolved_schemas": {"input_schemas": {}, "output_schemas": {}},
    "updated_at": "2026-05-01T14:30:00Z"
  },
  {
    "id": "extract-1",
    "workflow_id": "wf_abc123xyz",
    "organization_id": "org_123",
    "draft_version": "draft_v3",
    "type": "extract",
    "label": "Extract Invoice Fields",
    "position_x": 320,
    "position_y": 0,
    "width": null,
    "height": null,
    "config": {
      "model": "gpt-5",
      "json_schema": {
        "type": "object",
        "properties": {"total": {"type": "number"}}
      }
    },
    "parent_id": null,
    "resolved_schemas": {
      "input_schemas": {},
      "output_schemas": {
        "output-json-0": {
          "type": "object",
          "properties": {"total": {"type": "number"}}
        }
      }
    },
    "updated_at": "2026-05-01T14:30:00Z"
  },
  {
    "id": "hil-1",
    "workflow_id": "wf_abc123xyz",
    "organization_id": "org_123",
    "draft_version": "draft_v3",
    "type": "hil",
    "label": "Human Review",
    "position_x": 640,
    "position_y": 0,
    "width": null,
    "height": null,
    "config": null,
    "parent_id": null,
    "resolved_schemas": {"input_schemas": {}, "output_schemas": {}},
    "updated_at": "2026-05-01T14:30:00Z"
  }
]

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
workflow_id
string
required

Query Parameters

​
access_token
string | null

Body

application/json
​
id
string
required

Client-provided block ID

​
type
enum<string>
required

Block type

Available options:
start,
start_json,
note,
parse,
edit,
extract,
split,
classifier,
conditional,
hil,
api_call,
function,
while_loop,
for_each,
merge_dicts,
while_loop_sentinel_start,
while_loop_sentinel_end,
for_each_sentinel_start,
for_each_sentinel_end
​
label
string
default:""

Display label

​
position_x
number
default:0

X position

​
position_y
number
default:0

Y position

​
width
number | null

Block width

​
height
number | null

Block height

​
config
Config · object

Block configuration

​
parent_id
string | null

ID of parent container block (while_loop, for_each)

Response

Successful Response

​
workflow_id
string
required

Foreign key to workflow

​
organization_id
string
required

Organization ID for data isolation

​
type
enum<string>
required

Block type (extract, parse, classifier, etc.)

Available options:
start,
start_json,
note,
parse,
edit,
extract,
split,
classifier,
conditional,
hil,
api_call,
function,
while_loop,
for_each,
merge_dicts,
while_loop_sentinel_start,
while_loop_sentinel_end,
for_each_sentinel_start,
for_each_sentinel_end
​
id
string
​
draft_version
string | null

Draft version for live entities

​
label
string
default:""

Display label for the block

​
position_x
number
default:0

X position on canvas

​
position_y
number
default:0

Y position on canvas

​
width
number | null

Block width for resizable blocks

​
height
number | null

Block height for resizable blocks

​
config
Config · object

Block-specific configuration

​
field_ref_snapshot
Field Ref Snapshot · object

Merkle subtree hashes for authored field references; refreshed by schema propagation. Block metadata, not authored config.

​
resolved_schemas
Resolved Schemas · object

Transient sidecar of graph-derived schemas (input_schemas, output_schemas, field_ref_drift). Attached on transport responses; never persisted. Exclude from all DB writes via .model_dump(exclude={'resolved_schemas'}).

​
parent_id
string | null

ID of parent container (while_loop, for_each)

​
updated_at
string<date-time>