Update Block

Update a block with partial data.

Only the provided fields are updated. This enables targeted updates like position changes without affecting other block properties.

PATCH /v1/workflows/blocks/{block_id}

Python

from retab import Retab

client = Retab()

# Move + rename
block = client.workflows.blocks.update(
    block_id="extract-1",
    label="Extract Invoice Fields v2",
    position_x=480,
    position_y=160,
)

# Replace the config (e.g. tighten the schema, switch model)
block = client.workflows.blocks.update(
    block_id="extract-1",
    config={
        "model": "gpt-5-mini",
        "json_schema": {
            "type": "object",
            "properties": {
                "invoice_number": {"type": "string"},
                "total": {"type": "number"},
                "vendor": {
                    "type": "object",
                    "properties": {"name": {"type": "string"}}
                }
            },
        },
    },
)

200

{
  "id": "extract-1",
  "workflow_id": "wf_abc123xyz",
  "type": "extract",
  "label": "Extract Invoice Fields v2",
  "position_x": 480,
  "position_y": 160,
  "width": null,
  "height": null,
  "config": {
    "model": "gpt-5",
    "json_schema": {
      "type": "object",
      "properties": { "total": { "type": "number" } }
    }
  },
  "parent_id": null,
  "updated_at": "2026-05-01T14:30:00Z"
}

Patch a block with partial data. Only the fields you supply are touched; everything else is left as-is.

Common reasons to call this:

• Reposition on the canvas — position_x / position_y / width / height
• Rename the block — label
• Reconfigure the block — config (replaces the existing config; merge it client-side first if you want a partial change)
• Reparent into or out of a container — parent_id

type is intentionally not patchable. To change a block’s type, delete it and create a new one with the same id.

Python

from retab import Retab

client = Retab()

# Move + rename
block = client.workflows.blocks.update(
    block_id="extract-1",
    label="Extract Invoice Fields v2",
    position_x=480,
    position_y=160,
)

# Replace the config (e.g. tighten the schema, switch model)
block = client.workflows.blocks.update(
    block_id="extract-1",
    config={
        "model": "gpt-5-mini",
        "json_schema": {
            "type": "object",
            "properties": {
                "invoice_number": {"type": "string"},
                "total": {"type": "number"},
                "vendor": {
                    "type": "object",
                    "properties": {"name": {"type": "string"}}
                }
            },
        },
    },
)

200

{
  "id": "extract-1",
  "workflow_id": "wf_abc123xyz",
  "type": "extract",
  "label": "Extract Invoice Fields v2",
  "position_x": 480,
  "position_y": 160,
  "width": null,
  "height": null,
  "config": {
    "model": "gpt-5",
    "json_schema": {
      "type": "object",
      "properties": { "total": { "type": "number" } }
    }
  },
  "parent_id": null,
  "updated_at": "2026-05-01T14:30:00Z"
}

Authorizations

Api-Key · string · header · required

Path Parameters

block_id · string · required

Query Parameters

workflow_id · string | null

Disambiguates a block id that is shared by more than one workflow. Required only when the block id is not unique within your organization.

Body

application/json

Update a block. Only the fields you provide are changed.

config_mode controls how config is applied:

• "merge" (default): the given config is merged into the existing one — nested objects are combined, and a null value deletes a key.
• "replace": the given config replaces the existing one entirely.

label · string | null

Maximum string length: 200

position_x · number | null

position_y · number | null

width · number | null

height · number | null

config · Config · object

parent_id · string | null

config_mode · enum<string> | null

How to apply the config field. 'merge' (default) deep-merges the patch into the existing config with null-as-delete; 'replace' uses the patch as the full new config.

Available options: merge, replace

Response

200

application/json

Successful Response

Public live workflow block object.

id · string · required

workflow_id · string · required

Foreign key to workflow

type · enum<string> · required

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

Available options: start_document, start_json, note, parse, edit, extract, split, classifier, conditional, 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

updated_at · string<date-time> · required

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

parent_id · string | null

ID of parent container (while_loop, for_each)

declarative_path · string | null

Canonical declarative block path used to reconcile imported specs.

declarative_source_block_id · string | null

Authored declarative block id before import-time id regeneration.

resolved_schemas · Resolved Schemas · object

Schemas resolved for this block from the workflow graph.