Create Edge

Create a new edge connecting two blocks.

Validates that:

• Both source and target blocks exist in the workflow
• The connection is semantically valid (type compatibility, container rules, etc.)

POST /v1/workflows/edges

Python

from retab import Retab

client = Retab()

edge = client.workflows.edges.create(
    workflow_id="wf_abc123xyz",
    id="edge-start-to-extract",
    source_block="start-1",
    target_block="extract-1",
    source_handle="output-file-0",
    target_handle="input-file-0",
)

print(edge.id)

201

{
  "id": "edge-start-to-extract",
  "workflow_id": "wf_abc123xyz",
  "source_block": "start-1",
  "target_block": "extract-1",
  "source_handle": "output-file-0",
  "target_handle": "input-file-0",
  "updated_at": "2026-05-01T14:30:00Z"
}

Connect two blocks by creating an edge.

The create route is flat: send workflow_id in the request body.

You provide the edge ID — it must be unique within the workflow. Use a readable convention (e.g. edge-start-to-extract) so the graph stays inspectable.

source_handle and target_handle reference handles declared by each block. The handle naming convention is direction + slot:

• output-file-0, output-json-0, output-file-booking-confirmation, output-json-needs-review, …
• input-file-0, input-json-0, …

Dynamic split/classifier/conditional outputs use the route handle_key, not the display label. Inspect the source block before wiring those edges.

Python

from retab import Retab

client = Retab()

edge = client.workflows.edges.create(
    workflow_id="wf_abc123xyz",
    id="edge-start-to-extract",
    source_block="start-1",
    target_block="extract-1",
    source_handle="output-file-0",
    target_handle="input-file-0",
)

print(edge.id)

201

{
  "id": "edge-start-to-extract",
  "workflow_id": "wf_abc123xyz",
  "source_block": "start-1",
  "target_block": "extract-1",
  "source_handle": "output-file-0",
  "target_handle": "input-file-0",
  "updated_at": "2026-05-01T14:30:00Z"
}

Authorizations

Api-Key · string · header · required

Body

application/json

Create a new edge connecting two blocks in a workflow.

workflow_id · string · required

Workflow to create the edge in.

source_block · string · required

Source block ID

target_block · string · required

Target block ID

id · string | null

Edge ID. Omit to let the server generate one (recommended).

source_handle · string | null

Output handle

target_handle · string | null

Input handle

Response

201

application/json

Successful Response

Public live workflow edge object.

id · string · required

workflow_id · string · required

Foreign key to workflow

source_block · string · required

ID of the source block

target_block · string · required

ID of the target block

updated_at · string<date-time> · required

source_handle · string | null

Output handle on source block

target_handle · string | null

Input handle on target block