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

client = Retab()

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

overlay = client.workflows.runs.reviews.release(
    "run_abc123", "block_extract", version_stamp=overlay.version_stamp,
)
print("claim:", overlay.claim)  # None

{
  "_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": 5,
  "claim": null,
  "audit": [
    {
      "event": "released",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T09:30: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.

Release the advisory review claim on an overlay. Use this when you step away from a review without submitting a verdict — it clears claim so the item returns to the unclaimed pool and another reviewer can pick it up. The overlay’s status, versions, decisions, and audit trail are untouched; only the claim is dropped. 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.
Submitting an approved / rejected decision does not require releasing the claim first — a terminal decision settles the overlay regardless of who holds the claim.
from retab import Retab

client = Retab()

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

overlay = client.workflows.runs.reviews.release(
    "run_abc123", "block_extract", version_stamp=overlay.version_stamp,
)
print("claim:", overlay.claim)  # None

{
  "_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": 5,
  "claim": null,
  "audit": [
    {
      "event": "released",
      "actor": { "kind": "human", "id": "user_42", "display_name": "Dana Rivera" },
      "at": "2026-05-13T09:30:00.000Z"
    }
  ]
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required
​
block_id
string
required

Body

application/json
​
version_stamp
integer
required

CAS token (overlay rev).

Required range: x >= 0

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.