Skip to main content
POST
/
v1
/
workflows
/
{workflow_id}
/
edges
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)

{
  "id": "edge-start-to-extract",
  "workflow_id": "wf_abc123xyz",
  "organization_id": "org_123",
  "draft_version": "draft_v3",
  "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"
}

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.

Connect two blocks by creating an edge. 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-true, output-false, output-approved, …
  • input-file-0, input-json-0, …
You can read each block’s resolved_schemas.input_schemas / resolved_schemas.output_schemas to see exactly which handles exist. To insert many edges in one round-trip, use Create Edges (batch). 
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)

{
  "id": "edge-start-to-extract",
  "workflow_id": "wf_abc123xyz",
  "organization_id": "org_123",
  "draft_version": "draft_v3",
  "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

Path Parameters

​
workflow_id
string
required

Query Parameters

​
access_token
string | null

Body

application/json

Request to create a new edge.

​
id
string
required

Client-provided edge ID

​
source_block
string
required

Source block ID

​
target_block
string
required

Target block ID

​
source_handle
string | null

Output handle

​
target_handle
string | null

Input handle

Response

Successful Response

Edge document connecting two blocks.

Stored in workflow_edges collection. Edges are independently creatable and deletable without affecting block documents.

​
workflow_id
string
required

Foreign key to workflow

​
organization_id
string
required

Organization ID for data isolation

​
source_block
string
required

ID of the source block

​
target_block
string
required

ID of the target block

​
id
string
​
draft_version
string | null

Draft version for live entities

​
source_handle
string | null

Output handle on source block

​
target_handle
string | null

Input handle on target block

​
updated_at
string<date-time>