Skip to main content
POST
/
v1
/
workflows
/
reviews
/
{run_id}
/
{block_id}
/
versions
from retab import Retab

client = Retab()

review = client.workflows.reviews.get("run_abc123", "block_extract")
parent_id = next(iter(review.versions_by_id))

review = client.workflows.reviews.create_version(
    "run_abc123",
    "block_extract",
    parent_id=parent_id,
    snapshot={"total_amount": 325, "vendor_name": "Acme Corp"},
    note="Corrected total.",
)
print("versions:", len(review.versions_by_id))

{
  "_id": "run_abc123:block_extract",
  "workflow_run_id": "run_abc123",
  "block_run_id": "run_abc123:block_extract",
  "block_id": "block_extract",
  "workflow_id": "wf_1",
  "workflow_version_id": "wfv_1",
  "block_type": "extract",
  "triggered_by": { "kind": "always" },
  "awaiting_since": "2026-05-13T08:14:02.341Z",
  "priority": 0,
  "versions_by_id": {
    "a9f4d2e7f50b8b7bc84f4d96d2ad831a2a3bfead9b46f945baf2f8eb2f457a18": {
      "parent_id": null,
      "author": { "kind": "model", "id": "retab-small", "display_name": "Retab Small" },
      "snapshot": { "total_amount": 505, "vendor_name": "Acme Corp" },
      "note": null,
      "created_at": "2026-05-13T08:14:02.341Z"
    },
    "b7d7f3ddc4ce98edbb5ea71d2ff8a7b711b3d4b70c20f481e14c03c7d53e15e2": {
      "parent_id": "a9f4d2e7f50b8b7bc84f4d96d2ad831a2a3bfead9b46f945baf2f8eb2f457a18",
      "author": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "snapshot": { "total_amount": 325, "vendor_name": "Acme Corp" },
      "note": "Corrected total.",
      "created_at": "2026-05-13T09:02:51.118Z"
    }
  },
  "decision": null
}

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.

Create a corrective output version in a review. This records a new immutable snapshot of the gated block’s output without submitting a verdict. The new version is addressed by the content hash of its snapshot. The request body carries:
FieldNotes
snapshotThe full corrected output payload. It must match the gated block’s canonical review snapshot shape.
parent_idThe content-hash id of the version this snapshot was edited from.
noteOptional free-text note explaining the correction.
Snapshot validation is block-specific:
Block typeRequired snapshot
extractRaw extracted JSON object.
classifier{ "category": "..." } only. Reasoning is not review state.
split{ "documents": [{ "name": "...", "pages": [1, 2] }] }.
for_each{ "partitions": [{ "key": "...", "pages": [1, 2] }] }. Only split-by-key for-each reviews are supported.
For split and for-each snapshots, page arrays must contain positive integers, sorted ascending, with no duplicates. Invalid snapshots return 422 and are not stored. The API does not support partial patches. Always submit the complete replacement snapshot you want reviewers to decide on. 
from retab import Retab

client = Retab()

review = client.workflows.reviews.get("run_abc123", "block_extract")
parent_id = next(iter(review.versions_by_id))

review = client.workflows.reviews.create_version(
    "run_abc123",
    "block_extract",
    parent_id=parent_id,
    snapshot={"total_amount": 325, "vendor_name": "Acme Corp"},
    note="Corrected total.",
)
print("versions:", len(review.versions_by_id))

{
  "_id": "run_abc123:block_extract",
  "workflow_run_id": "run_abc123",
  "block_run_id": "run_abc123:block_extract",
  "block_id": "block_extract",
  "workflow_id": "wf_1",
  "workflow_version_id": "wfv_1",
  "block_type": "extract",
  "triggered_by": { "kind": "always" },
  "awaiting_since": "2026-05-13T08:14:02.341Z",
  "priority": 0,
  "versions_by_id": {
    "a9f4d2e7f50b8b7bc84f4d96d2ad831a2a3bfead9b46f945baf2f8eb2f457a18": {
      "parent_id": null,
      "author": { "kind": "model", "id": "retab-small", "display_name": "Retab Small" },
      "snapshot": { "total_amount": 505, "vendor_name": "Acme Corp" },
      "note": null,
      "created_at": "2026-05-13T08:14:02.341Z"
    },
    "b7d7f3ddc4ce98edbb5ea71d2ff8a7b711b3d4b70c20f481e14c03c7d53e15e2": {
      "parent_id": "a9f4d2e7f50b8b7bc84f4d96d2ad831a2a3bfead9b46f945baf2f8eb2f457a18",
      "author": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "snapshot": { "total_amount": 325, "vendor_name": "Acme Corp" },
      "note": "Corrected total.",
      "created_at": "2026-05-13T09:02:51.118Z"
    }
  },
  "decision": null
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required
​
block_id
string
required

Body

application/json

Create a corrected snapshot version without deciding.

​
snapshot
Snapshot · object
required

The full reviewed snapshot to store as an immutable version. The object must match the gated block type: extract uses the raw output object; classifier uses {'category': string}; split uses {'documents': [{'name': string, 'pages': positive sorted int[]}]}; for_each uses {'partitions': [{'key': string, 'pages': positive sorted int[]}]}. The server validates the shape and stores the exact submitted object when valid.

​
parent_id
string
required

The version id this snapshot was authored from.

Pattern: ^[0-9a-f]{64}$
​
note
string | null

Response

Successful Response

Public API shape for the full review.

​
_id
string
required
​
workflow_id
string
required
​
workflow_version_id
string
required
​
workflow_run_id
string
required
​
block_id
string
required
​
block_run_id
string
required
​
block_type
enum<string>
required
Available options:
extract,
split,
classifier,
for_each
​
triggered_by
ReviewAlways · object
required

Gate every run.

​
awaiting_since
string<date-time>
required
​
versions_by_id
Versions By Id · object
required
​
priority
integer
default:0
​
decision
ReviewDecision · object

The one terminal decision over one exact output version.