Get Field Review

Get reviewer detail for one held field: cell version history, validation verdicts, recovered source spans for provenance, and the prior decision history.

Get the full reviewer view for one held field, addressed by its pipeline document id and field key. The response bundles everything a human reviewer needs to decide on an extracted value: the queue item, the schema field metadata, the cell version history, the validation verdicts that flagged it, source spans locating the value in the original document (provenance), and the prior decision history for the field.

The cellHistory is the chain of cell versions for the field, showing how the value moved through transfer, extraction, resolution, and any human edits. The verdicts array is the per-validator output (evidence, business rules, n-shot, LLM judge) with each verdict's reasoning. Together they explain why the field was parked and what the candidate values are.

Source spans are best-effort. When a phase recorded a verbatim span it is returned directly; otherwise the server recovers a span by locating the value in the document and may mark it approximate. The priorDecisions array lists earlier human actions on the field so a reviewer sees the full audit trail before deciding. This endpoint requires an API key with the read scope.

Source spans are what make review fast: instead of rereading the document, the reviewer sees the exact quote the value came from. A span flagged approximate: true was recovered after the fact rather than written by the extracting phase.

GET/v1/field-reviews/{docId}/{fieldKey}

curl

Response

Response fields

itemobjectThe queue item for this field (same shape as a list entry).

fieldobject | nullSchema field metadata (type, constraints, display name).

cellHistoryarrayCell versions for the field, oldest to newest, with source and span where available.

matchedSpanobject | nullRecovered source span for the current value. Carries approximate: true when recovered rather than written by a phase.

candidateSpansobject | nullPer-value spans for n-shot candidate values, keyed by value.

candidateSimilarityobject | nullPer-candidate similarity score to the current value (0-1), keyed by value.

verdictsarrayValidation verdicts that flagged the field.

verdicts[].validatorTypestringValidator that produced the verdict (evidence, business_rules, nshot, llm_judge).

verdicts[].verdictstringThe verdict band (e.g. pass, fail, different).

verdicts[].confidencenumber | nullValidator confidence.

verdicts[].reasoningstring | nullWhy the validator returned this verdict.

verdicts[].stageNamestring | nullValidation stage (gate) the verdict came from.

verdicts[].createdAtstringISO 8601 timestamp.

priorDecisionsarrayEarlier human decisions on this field.

priorDecisions[].actionstringapprove, correct, or override.

priorDecisions[].priorValuestring | nullValue before the decision.

priorDecisions[].finalValuestring | nullValue after the decision.

priorDecisions[].reasonstring | nullAudit note recorded with the decision.

priorDecisions[].decidedByNamestring | nullWho decided (api for API-driven decisions).

priorDecisions[].decidedAtstringISO 8601 timestamp.

Response

{
  "item": {
    "pipeline_document_id": "pd_uuid_1",
    "field_key": "total_amount",
    "field_display_name": "Total Amount",
    "status": "blocked",
    "trigger": "gate",
    "reason": "failed_check",
    "current_value": "12,500.00",
    "confidence": 0.62
  },
  "field": { "field_name": "total_amount", "field_type": "number", "display_name": "Total Amount" },
  "cellHistory": [
    { "cellVersion": 1, "source": "llm_extraction", "value": "12,500.00", "sourceText": "Total due: 12,500.00" }
  ],
  "matchedSpan": { "text": "12,500.00", "approximate": false },
  "candidateSpans": null,
  "candidateSimilarity": null,
  "verdicts": [
    {
      "validatorType": "evidence",
      "verdict": "fail",
      "confidence": 0.62,
      "reasoning": "Amount does not reconcile with the line-item subtotal.",
      "stageName": "Amount reconciliation",
      "createdAt": "2024-09-14T11:02:33.000Z"
    }
  ],
  "priorDecisions": []
}

Errors

Error responses

400validation_errorInvalid document ID format. Must be a UUID.

401unauthorizedMissing or invalid API key.

404not_foundNo pipeline document with this ID exists for your organization.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

List Field Reviews

Resolve Field Review

Get Field Review

Response

Errors

Related