Plan Workflow Spec

Preview the changes a declarative YAML spec would make to the draft workflow.

Compares the spec against the current draft and returns the resulting changes without applying them. A spec that already matches the draft plans as a no-op.

POST /v1/workflows/spec/plan

Python

from retab import Retab

client = Retab()

plan = client.workflows.spec.plan(yaml_definition)

print(plan.action)
print(plan.rendered_plan)
for change in plan.resource_changes:
    print(change.actions, change.target, change.target_id)

200

{
  "workflow_id": "wf_abc123",
  "action": "update",
  "block_count": 2,
  "edge_count": 1,
  "diagnostics": {
    "issues": []
  },
  "format_version": "workflows-plan/v1",
  "summary": {
    "add": 0,
    "change": 1,
    "destroy": 0,
    "replace": 0,
    "noop": 0,
    "total": 1,
    "has_changes": true
  },
  "resource_changes": [
    {
      "address": "workflow.wf_abc123.block.block_extract",
      "target": "block",
      "target_id": "block_extract",
      "name": "Extract Fields",
      "type": "extract",
      "actions": ["update"],
      "summary": "Update block 'Extract Fields'",
      "change": {
        "before": {
          "label": "Extract Fields",
          "config": {
            "model": "gpt-4.1"
          }
        },
        "after": {
          "label": "Extract Fields",
          "config": {
            "model": "gpt-5.1"
          }
        },
        "before_sensitive": {},
        "after_sensitive": {},
        "field_changes": [
          {
            "path": ["config", "model"],
            "path_display": "config.model",
            "action": "update",
            "before": "gpt-4.1",
            "after": "gpt-5.1",
            "before_sensitive": false,
            "after_sensitive": false,
            "unified_diff": null
          }
        ]
      },
      "path": "extract-node"
    }
  ],
  "rendered_plan": "Workflow: wf_abc123\nPlan: 0 to add, 1 to change, 0 to destroy.\n\n~ workflow.wf_abc123.block.block_extract\n  block \"Extract Fields\" will be updated\n  ~ config.model\n    - 'gpt-4.1'\n    + 'gpt-5.1'"
}

Compute the reconcile plan for a declarative workflow YAML spec against the current draft workflow. This does not mutate workflow state.

Use this before apply() to see whether the spec will create a workflow, update blocks and edges, or no-op.

Python

from retab import Retab

client = Retab()

plan = client.workflows.spec.plan(yaml_definition)

print(plan.action)
print(plan.rendered_plan)
for change in plan.resource_changes:
    print(change.actions, change.target, change.target_id)

200

{
  "workflow_id": "wf_abc123",
  "action": "update",
  "block_count": 2,
  "edge_count": 1,
  "diagnostics": {
    "issues": []
  },
  "format_version": "workflows-plan/v1",
  "summary": {
    "add": 0,
    "change": 1,
    "destroy": 0,
    "replace": 0,
    "noop": 0,
    "total": 1,
    "has_changes": true
  },
  "resource_changes": [
    {
      "address": "workflow.wf_abc123.block.block_extract",
      "target": "block",
      "target_id": "block_extract",
      "name": "Extract Fields",
      "type": "extract",
      "actions": ["update"],
      "summary": "Update block 'Extract Fields'",
      "change": {
        "before": {
          "label": "Extract Fields",
          "config": {
            "model": "gpt-4.1"
          }
        },
        "after": {
          "label": "Extract Fields",
          "config": {
            "model": "gpt-5.1"
          }
        },
        "before_sensitive": {},
        "after_sensitive": {},
        "field_changes": [
          {
            "path": ["config", "model"],
            "path_display": "config.model",
            "action": "update",
            "before": "gpt-4.1",
            "after": "gpt-5.1",
            "before_sensitive": false,
            "after_sensitive": false,
            "unified_diff": null
          }
        ]
      },
      "path": "extract-node"
    }
  ],
  "rendered_plan": "Workflow: wf_abc123\nPlan: 0 to add, 1 to change, 0 to destroy.\n\n~ workflow.wf_abc123.block.block_extract\n  block \"Extract Fields\" will be updated\n  ~ config.model\n    - 'gpt-4.1'\n    + 'gpt-5.1'"
}

Authorizations

Api-Key · string · header · required

Body

application/json

Body carrying a workflow's full YAML definition for validate, plan, apply, or export.

yaml_definition · string · required

Workflow YAML definition

Response

200

application/json

Successful Response

A preview of the changes a workflow YAML definition would make, with a per-resource diff and a human-readable rendered_plan.

workflow_id · string · required

action · enum<string> · required

Available options: create, update, noop

block_count · integer · required

edge_count · integer · required

diagnostics · Diagnostics · object · required

format_version · string · default: workflows-plan/v1

summary · DeclarativePlanSummary · object

Show child attributes

resource_changes · DeclarativePlanResourceChange · object[]

Show child attributes

rendered_plan · string · default: No changes. Workflow spec is up to date.