Skip to main content

Review Queue

The review queue is the human-in-the-loop surface for pipelines. When a blocking gate fails a field, or a field marked for review survives the run undecided, it routes here. The queue is central and cross-pipeline: it aggregates every field awaiting a decision across all your runs, so a reviewer works one list rather than hunting through individual pipelines. Each item carries its current value, confidence, and the stored verdicts that flagged it.

A reviewer resolves an item one of three ways. Approve accepts the current value. Correct replaces it with a fixed value. Override accepts a value with a required reason. Every action writes a promotion cell (a new canonical version with full confidence and a human-review source) and appends a row to an append-only decision log. The log records who decided, when, the prior value, and the final value, and it exports with the data product so your customer receives the full handover trail.

The queue is built for volume. Items are classified by reason (missing value, disagreement, failed check, low confidence, likely fine), so a reviewer can triage the worst first. Identical values across many documents cluster together for one-click bulk approval, and a bulk-resolve call can clear up to 500 items at once, each running the same single-field decision path so one failure never aborts the batch. Items can be claimed for ownership, though the decision log, not the claim, remains the authority on who decided.

Review Mode: the workbench

Review Mode is the full-screen workbench a reviewer walks the queue in. A progress rail on the left tracks the walk (with a compact reason-filter chip row), the source document renders in the center, and the decision rail on the right carries the value, verdicts, candidates, and the approve/correct/override form. The decision rail is resizable — drag its edge between 320 and 720 pixels and the width persists across sessions and across both review surfaces — and collapsible; picking a candidate auto-expands it, because picking means deciding. The same Review Mode also opens over a data product's own review surface, so queue review and product review are one muscle memory.

A toggle on the rail header reveals the reference comparison rails: a two-column, strictly read-only panel with Schema fields on the left and Reference data on the right, showing the matched reference row (with its match key and table name) beside what the pipeline extracted. Rows annotate the matcher verdict — matched, shortlisted, no match, or ambiguous — so a reviewer deciding a held field sees the reference evidence without leaving the workbench. The panel splits the screen with the document viewer through a draggable divider whose position also persists.

The workbench is tuned for scanned PDFs. The document pane opens the original PDF immediately rather than waiting for the source highlight to be located: a cold span resolve (seconds of OCR on the server) runs behind a non-blocking "Locating source…" pill, and the highlight lands when found. While you decide the current item, the next two items' details, documents, PDF bytes, and span geometry are prefetched, so advancing through the queue reveals each workbench instantly instead of re-paying the load on every item.

Working the queue via API

List the queue and filter by pipeline (pipeline_id), trigger (gate for a blocking-gate block, declarative for a requires-review hold), and item status. Each item identifies the document and field key you act on. The richer reason and assignee filters drive the in-app queue UI.

List the review queue
curl "https://api.talonic.com/v1/field-reviews?trigger=gate" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Resolve an item by posting a decision for its document and field. Approve accepts the value; correct supplies a replacement; override supplies a value and a reason.

Resolve a field in review
curl -X POST https://api.talonic.com/v1/field-reviews/doc_7f3a1b2c/total_amount/resolve \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "correct", "corrected_value": "1480.00" }'

Pull the decision log for an audit view, or export it as CSV for handover. With no filter the log is workspace-wide; filter by pipeline or data product to scope it to one deliverable.

Export the decision log
curl "https://api.talonic.com/v1/field-reviews/decisions/export?pipeline_id=pl_x8k2m9" \
  -H "Authorization: Bearer $TALONIC_API_KEY" -o decisions.csv
A field marked requires_review never reaches completed without a decision row. The promotion cell is written before the field state flips, so the canonical value a data product reads can never lead the workflow state. The queue itself is a query over field states, so there is no separate queue table to drift out of sync.

Frequently asked questions

What lands in the review queue?+
Fields blocked by a blocking validation gate, and fields marked requires_review that survive a run without a decision. The queue is central and cross-pipeline: it aggregates every awaiting field across all your runs into one list, each item carrying its current value, confidence, and the verdicts that flagged it.
What are the ways to resolve a review item?+
Approve (accept the current value), correct (replace it with a fixed value), or override (accept a value with a required reason). Each writes a promotion cell as a new canonical version with full confidence and a human-review source, and appends a row to the append-only decision log.
How do I handle review at volume?+
Items are classified by reason for triage, and identical values cluster for one-click bulk approval. POST /v1/field-reviews/bulk-resolve clears up to 500 items in one call, each running the same single-field decision path, so one failure never aborts the batch. Items can also be claimed for ownership.
What does Review Mode add over the queue list?+
A full-screen workbench: a progress rail tracking the walk, the source document rendered centrally (PDFs open immediately, with a non-blocking "Locating source…" pill while the highlight is found), and a resizable decision rail carrying the value, verdicts, and decision form. A toggle reveals read-only reference comparison rails showing Schema fields beside the matched Reference data, and the next items are prefetched so advancing is instant.
Is there an audit trail for review decisions?+
Yes. Every decision appends to an append-only log recording who decided, when, the prior value, the action, and the final value. Pull it as JSON or export CSV via /v1/field-reviews/decisions, filtered by pipeline or data product or workspace-wide. The log exports with the data product for customer handover.

Related

Validation Checkpoints
Running a Pipeline
Review Gates