Diagnose Workflow Graph

Validate workflow blocks and edges before publishing. You can pass a draft graph directly to this endpoint.

The check covers:

• Missing or duplicate start_document blocks
• Disconnected blocks
• Dangling edges (one endpoint missing)
• Unreachable blocks
• Type mismatches between source/target handles
• Missing required block configuration
• Incomplete authored config such as blank categories, subdocuments, or map keys
• Embedded review gate predicates and unavailable review signals
• Cycles in the directed graph

Severities:

Severity	Meaning
error	Must fix before publish — block runs would fail.
warning	Should fix; runs may still succeed.
info	Advisory only.

is_valid is true when the issue list contains no errors. re_propagate defaults to true so derived schemas are refreshed before validation.

The SDKs also expose a convenience helper:

Python

from retab import Retab
from retab.types.standards import PreparedRequest

client = Retab()

diagnosis = client._prepared_request(
    PreparedRequest(
        method="POST",
        url="/v1/workflows/wf_abc123/diagnose-graph",
        data={"re_propagate": True},
    )
)
for issue in diagnosis["issues"]:
    print(f"[{issue['severity']}] {issue['code']}: {issue['message']}")

200 (valid)

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