Reviews

Overview

When a workflow reaches a block with config.review and the predicate fires, the run pauses and creates a review. Address the review by its opaque id, such as rev_...; workflow context like run_id, block_id, step_id, and iteration_key is metadata for filtering and grounding. Reviews hold gate metadata and the terminal decision. Review versions hold immutable output snapshots and are managed separately through reviews.versions.*.

Review Shape

Field	What it holds
`id`	Opaque review id.
`run_id`	Run that is paused for review.
`block_id`	Workflow block that produced the reviewed output.
`step_id`	Exact execution step under review.
`decision`	Terminal verdict, or `null` while awaiting review.
`triggered_by`	Review predicate that opened the gate.

Review queue items return the same Review shape. Fetch the version history for a given review with reviews.versions.list(review_id=...) — the runtime-created seed is the version whose parent_id is null.

Version Shape

Field	What it holds
`id`	Content-addressed version id.
`review_id`	Review this version belongs to.
`parent_id`	Parent version id. `null` appears only on runtime-created seed versions in read responses.
`snapshot`	Complete reviewed output payload for this version.
`note`	Optional reviewer note.
`created_at`	When the version was created.

Versions are peers. There is no head pointer. Use created_at for display ordering, and approve or reject the exact version_id you inspected.

The Review Loop

1. Find the work

queue = client.workflows.reviews.list(
    workflow_id="wf_abc123",
    decision_status="pending",
)

for item in queue.data:
    print(item.id, item.run_id, item.block_id)

2. Inspect the output

item = queue.data[0]
review = client.workflows.reviews.get(item.id)
versions = client.workflows.reviews.versions.list(review_id=review.id)
seed_version = next(v for v in versions.data if v.parent_id is None)

print(review.run_id, review.step_id)
print(seed_version.snapshot)

Use run_id and step_id to inspect the source step and document before deciding.

3. Correct if needed

Create a new version (a complete replacement snapshot) with the reviewed version as parent_id, then approve the returned id. Public clients must provide parent_id when creating correction versions. Versions are a flat CRUD resource at POST /v1/workflows/reviews/versions; the parent id lives in the body, not the URL.

version = client.workflows.reviews.versions.create(
    review_id=review.id,
    parent_id=seed_version.id,
    snapshot={"total_amount": 325, "vendor_name": "Acme Corp"},
    note="Corrected total.",
)

version_id = version.id

Snapshot validation is block-specific:

Block type	Snapshot shape
`extract`	Raw extracted JSON object.
`classifier`	`{ "category": "booking_confirmation" }` only.
`split`	`{ "documents": [{ "name": "invoice", "pages": [1, 2] }] }`.
`for_each`	`{ "partitions": [{ "key": "INV-001", "pages": [1, 2] }] }`.

For split and for-each snapshots, pages must be positive integers, sorted, and unique within each item. The API does not support partial patches.

4. Decide

client.workflows.reviews.approve(review.id, version_id=version_id)

client.workflows.reviews.reject(
    review.id,
    version_id=seed_version.id,
    reason="Source document is illegible; cannot verify totals.",
)

resume_status="resumed" means the workflow accepted the signal. resume_status="pending" means the decision is durable and a backend reconciler will retry the resume.

API Reference

Endpoint	SDK method
List Reviews	`reviews.list(...)`
Get Review	`reviews.get(id)`
Approve Review	`reviews.approve(...)`
Reject Review	`reviews.reject(...)`
Create Version	`reviews.versions.create(...)`
Get Version	`reviews.versions.get(id)`
List Versions	`reviews.versions.list(...)`

Overview

Primitives

Workflows

Core Concepts

Enterprise

Overview

Review Shape

Version Shape

The Review Loop

1. Find the work

2. Inspect the output

3. Correct if needed

4. Decide

API Reference

​Overview

​Review Shape

​Version Shape

​The Review Loop

​1. Find the work

​2. Inspect the output

​3. Correct if needed

​4. Decide

​API Reference

Overview

Review Shape

Version Shape

The Review Loop

1. Find the work

2. Inspect the output

3. Correct if needed

4. Decide

API Reference