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

client = Retab()

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

overlay = client.workflows.runs.reviews.claim(
    "run_abc123", "block_extract", version_stamp=overlay.version_stamp,
)
print("claimed by:", overlay.claim.holder.display_name)

{
  "_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": 4,
  "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"
  },
  "audit": [
    {
      "event": "claimed",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T08:55:00.000Z"
    }
  ]
}

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.

Take the advisory review claim on an overlay. The claim records, in claim, a ReviewClaim ({holder, claimed_at, expires_at}) naming the Actor currently working a review. It is advisory — it does not lock the overlay or prevent another actor from editing or deciding. It exists so a review inbox can show “Dana is reviewing this” and avoid two people picking up the same item. The hard concurrency guarantee comes from the version_stamp compare-and-swap on every mutating call, not from the claim. The request body carries only the version_stamp you last read.
version_stamp is a compare-and-swap token. Send the value you last read from Get Review. If the overlay has advanced, the call returns 409 — re-read the overlay and retry. A stale stamp raises retab.exceptions.ConflictError in Python and surfaces as an APIError with .status === 409 in JavaScript.
Release the claim with Release Review when you step away without deciding. Submitting a decision does not require holding the claim. 
from retab import Retab

client = Retab()

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

overlay = client.workflows.runs.reviews.claim(
    "run_abc123", "block_extract", version_stamp=overlay.version_stamp,
)
print("claimed by:", overlay.claim.holder.display_name)

{
  "_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": 4,
  "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"
  },
  "audit": [
    {
      "event": "claimed",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T08:55:00.000Z"
    }
  ]
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required
​
block_id
string
required

Body

application/json

Take or release the advisory review claim.

​
version_stamp
integer
required

CAS token (overlay rev).

Required range: x >= 0
​
ttl_seconds
integer
default:900

How long the advisory claim holds before it expires.

Required range: 30 <= x <= 86400

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.