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

client = Retab()

# A typical extract block with a JSON schema config
block = client.workflows.blocks.create(
    workflow_id="wf_abc123xyz",
    id="extract-1",
    type="extract",
    label="Extract Invoice Fields",
    position_x=320,
    position_y=0,
    config={
        "model": "gpt-5",
        "json_schema": {
            "type": "object",
            "properties": {
                "invoice_number": {"type": "string"},
                "total": {"type": "number"},
            },
        },
    },
)

print(block.id)

{
  "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": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"}
      }
    }
  },
  "parent_id": null,
  "resolved_schemas": {
    "input_schemas": {},
    "output_schemas": {
      "output-json-0": {
        "type": "object",
        "properties": {
          "invoice_number": {"type": "string"},
          "total": {"type": "number"}
        }
      }
    }
  },
  "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.

Add a new block to a workflow’s draft graph. You provide the block ID — it must be unique within the workflow. Pick something descriptive (e.g. extract-invoice, classifier-language) so edges and assertions stay readable. The config shape depends on type. See Workflow Blocks for the per-type config reference. A few invariants the API enforces:
  • Input blocks (start, start_json) cannot be placed inside containers — parent_id must be null for them.
  • parent_id is reserved for placing blocks inside container blocks (while_loop, for_each).
To insert many blocks in one round-trip, use Create Blocks (batch). 
from retab import Retab

client = Retab()

# A typical extract block with a JSON schema config
block = client.workflows.blocks.create(
    workflow_id="wf_abc123xyz",
    id="extract-1",
    type="extract",
    label="Extract Invoice Fields",
    position_x=320,
    position_y=0,
    config={
        "model": "gpt-5",
        "json_schema": {
            "type": "object",
            "properties": {
                "invoice_number": {"type": "string"},
                "total": {"type": "number"},
            },
        },
    },
)

print(block.id)

{
  "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": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"}
      }
    }
  },
  "parent_id": null,
  "resolved_schemas": {
    "input_schemas": {},
    "output_schemas": {
      "output-json-0": {
        "type": "object",
        "properties": {
          "invoice_number": {"type": "string"},
          "total": {"type": "number"}
        }
      }
    }
  },
  "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

Request to create a new block.

​
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

Individual block document for live editing.

Stored in workflow_blocks collection. Each block is independently updatable, enabling targeted position and config updates without loading the entire workflow.

​
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>