Reviews

Review, correct, and decide on gated workflow block outputs

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(...)