Skip to main content

Get Field Review

Get reviewer detail for one held field: the queue item, schema field metadata, cell version history, validation verdicts, recovered source spans, and prior decisions.

Get the full reviewer view for one held field, addressed by its pipeline document id and field key. The response bundles everything a reviewer needs to decide: the queue item, the schema field metadata, the cell version history, the validation verdicts that flagged it, any recovered source spans, 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.

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

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.

Related

List Field Reviews
Resolve Field Review