Skip to main content
POST
/
v1
/
workflows
/
{workflow_id}
/
diagnose-graph
from retab import Retab

client = Retab()

# One-shot — fetches the persisted draft entities and diagnoses them.
diagnosis = client.workflows.diagnose("wf_abc123")
if not diagnosis.is_valid:
    for issue in diagnosis.issues:
        print(f"[{issue.severity}] {issue.code}: {issue.message}")

{
  "is_valid": true,
  "issues": [],
  "suggestions": [],
  "stats": {
    "total_blocks": 5,
    "total_edges": 4,
    "block_types": { "start": 1, "extract": 2, "classifier": 1, "split": 1 },
    "start_blocks": 1
  }
}

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.

Validate an in-memory workflow graph and return any structural issues. This is the authoritative validation surface for the workflow editor — both for an unsaved draft (passing blocks and edges directly) and for the persisted draft (fetching them first via Get Workflow Entities and forwarding them to this endpoint). The check covers:
  • Missing or duplicate start blocks
  • Disconnected blocks
  • Dangling edges (one endpoint missing)
  • Unreachable blocks
  • Type mismatches between source/target handles
  • Missing required block configuration
  • Cycles in the directed graph
Severities:
SeverityMeaning
errorMust fix before publish — block runs would fail.
warningShould fix; runs may still succeed.
infoAdvisory only.
is_valid is true when the issue list contains no errors. re_propagate defaults to true so derived schemas are recomputed before validation — turn it off if you’ve already propagated and want to validate the cached shape. The Python SDK exposes a one-shot helper that fetches the persisted draft and POSTs it for you: 
from retab import Retab

client = Retab()

# One-shot — fetches the persisted draft entities and diagnoses them.
diagnosis = client.workflows.diagnose("wf_abc123")
if not diagnosis.is_valid:
    for issue in diagnosis.issues:
        print(f"[{issue.severity}] {issue.code}: {issue.message}")

{
  "is_valid": true,
  "issues": [],
  "suggestions": [],
  "stats": {
    "total_blocks": 5,
    "total_edges": 4,
    "block_types": { "start": 1, "extract": 2, "classifier": 1, "split": 1 },
    "start_blocks": 1
  }
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
workflow_id
string
required

Query Parameters

​
access_token
string | null

Body

application/json
​
blocks
WorkflowConfigBlock · object[]

The blocks in this workflow version

​
edges
WorkflowConfigEdge · object[]

The edges in this workflow version

​
re_propagate
boolean
default:true

Recompute derived schemas before validating the graph

Response

Successful Response

​
is_valid
boolean
required

Whether the graph has no error-severity issues

​
issues
WorkflowDiagnosisIssue · object[]

Structured diagnosis issues

​
suggestions
string[]

Optional remediation suggestions

​
stats
WorkflowDiagnosisStats · object

Workflow graph statistics