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

client = Retab()

overlay = client.workflows.runs.reviews.get("run_abc123", "block_extract")

print(overlay.status, overlay.rev)

# Version 0 is always the model's original output
original = overlay.versions[0]
print(original.origin, original.author.kind)

# The effective output is the latest version
latest = overlay.versions[-1]
print(latest.snapshot)

{
  "_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",
  "status": "awaiting_review",
  "rev": 3,
  "claim": {
    "holder": {
      "kind": "human",
      "id": "user_42",
      "display_name": "Dana Rivera"
    },
    "claimed_at": "2026-05-13T08:55:00.000Z",
    "expires_at": "2026-05-13T09:55:00.000Z"
  },
  "versions": [
    {
      "seq": 0,
      "origin": "model_output",
      "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"
    },
    {
      "seq": 1,
      "origin": "human_edit",
      "author": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "snapshot": { "total_amount": 325, "vendor_name": "Acme Corp" },
      "note": "Corrected total to match ATM + checks subtotal.",
      "created_at": "2026-05-13T09:02:51.118Z"
    }
  ],
  "decisions": [],
  "audit": [
    {
      "event": "overlay_created",
      "actor": { "kind": "model", "id": "retab-small", "display_name": "Retab Small" },
      "at": "2026-05-13T08:14:02.341Z"
    },
    {
      "event": "claimed",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T08:55:00.000Z"
    },
    {
      "event": "version_appended",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T09:02:51.118Z"
    }
  ],
  "created_at": "2026-05-13T08:14:02.341Z",
  "updated_at": "2026-05-13T09:02:51.118Z"
}

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.

Get the full review overlay for a gated block run. The overlay is a versioned sidecar attached to a single (run_id, block_id) pair. It records:
FieldNotes
versions[]Every version of the gated block’s output. Sequence 0 is the model’s original; later sequences are corrective edits.
decisions[]Every verdict submitted against the overlay (approved / rejected).
audit[]The append-only audit trail — every claim, release, edit, and decision, with the acting Actor.
revThe overlay’s compare-and-swap token. Read it here, pass it back (as the version_stamp request parameter) on every mutating call.
claimThe ReviewClaim currently held on the overlay ({holder, claimed_at, expires_at}), or null.
Every actor — model, agent, or human — is described by the same symmetric Actor shape: {kind, id, display_name}.
The rev you read here is what every mutating call (append version, submit decision, claim, release) must echo back. If it has advanced since you read it, the mutating call returns 409 — re-read and retry.
from retab import Retab

client = Retab()

overlay = client.workflows.runs.reviews.get("run_abc123", "block_extract")

print(overlay.status, overlay.rev)

# Version 0 is always the model's original output
original = overlay.versions[0]
print(original.origin, original.author.kind)

# The effective output is the latest version
latest = overlay.versions[-1]
print(latest.snapshot)

{
  "_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",
  "status": "awaiting_review",
  "rev": 3,
  "claim": {
    "holder": {
      "kind": "human",
      "id": "user_42",
      "display_name": "Dana Rivera"
    },
    "claimed_at": "2026-05-13T08:55:00.000Z",
    "expires_at": "2026-05-13T09:55:00.000Z"
  },
  "versions": [
    {
      "seq": 0,
      "origin": "model_output",
      "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"
    },
    {
      "seq": 1,
      "origin": "human_edit",
      "author": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "snapshot": { "total_amount": 325, "vendor_name": "Acme Corp" },
      "note": "Corrected total to match ATM + checks subtotal.",
      "created_at": "2026-05-13T09:02:51.118Z"
    }
  ],
  "decisions": [],
  "audit": [
    {
      "event": "overlay_created",
      "actor": { "kind": "model", "id": "retab-small", "display_name": "Retab Small" },
      "at": "2026-05-13T08:14:02.341Z"
    },
    {
      "event": "claimed",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T08:55:00.000Z"
    },
    {
      "event": "version_appended",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T09:02:51.118Z"
    }
  ],
  "created_at": "2026-05-13T08:14:02.341Z",
  "updated_at": "2026-05-13T09:02:51.118Z"
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required
​
block_id
string
required

Response

Successful Response

The HIL review sidecar for one gated block run. Replaces v1 HilRunState.

Stored 1:1 in hil_overlays with _id == block_run_id.

​
_id
string
required

Equals block_run_id — 1:1 with the gated run.

​
workflow_id
string
required
​
workflow_version_id
string
required

Pinned at gate-fire; resume runs THIS version.

​
workflow_run_id
string
required
​
block_id
string
required
​
block_run_id
string
required
​
block_type
enum<string>
required
Available options:
extract,
classifier,
split,
conditional
​
triggered_by
HilAlways · object
required

Gate every run.

​
versions
OutputVersion · object[]
required

Ascending seq. versions[0] is always the model's seq=0 output.

Minimum array length: 1
​
head_seq
integer
required

seq of the newest version (== versions[-1].seq).

Required range: x >= 0
​
status
enum<string>
default:awaiting_review
Available options:
awaiting_review,
approved,
rejected
​
awaiting_since
string<date-time>
​
decided_at
string<date-time> | null
​
priority
integer
default:0

Higher sorts first in the queue.

​
rev
integer
default:0

Whole-document CAS token. +1 on every mutating write.

Required range: x >= 0
​
claim
ReviewClaim · object

A soft lease so the UI can show 'Dana is reviewing this'. NOT a lock — correctness rests entirely on the rev CAS. Claims expire.

​
decisions
ReviewDecision · object[]

Append-only. Empty while awaiting. len>1 means reopened.

​
audit
AuditEntry · object[]
​
effective_seq
integer | null

seq of the version downstream consumes. Set ONLY by an 'approved' decision. None while awaiting / rejected.