Skip to main content

Override

Manually override the selected N-Shot value for a document-field pair by choosing a shot number. The override is recorded with a full audit trail via the API.

POST /v1/jobs/runs/{runId}/nshot/override manually overrides the selected value for a specific document-field comparison by choosing a shot number. The override is recorded with an audit trail including the actor, timestamp, original value, and new value. Use this when the majority value is incorrect and a different shot produced the right extraction.

Pass a selected_shot that exists in the comparison's values array. A shot number that matches no shot is not rejected: the override is still recorded, with to_value set to null. All API-initiated overrides record actor_id as "api".
POST/v1/jobs/runs/{runId}/nshot/override

Body parameters

document_id*uuidDocument ID.
field_name*stringField name.
selected_shot*integerThe shot number to select as the override value.
reasonstringOptional reason for the override, stored in the audit trail.

Request

Response

Response fields

idstringComparison UUID.
run_idstringJob run UUID.
document_idstringDocument UUID.
field_namestringField name.
statusstringAgreement status.
majority_valueanyOriginal majority value.
valuesarrayPer-shot values.
overrideobjectOverride record with selected_shot, actor_id, overridden_at, from_value, to_value, and reason.
override.selected_shotintegerThe shot number that was selected.
override.actor_idstringAlways "api" when overridden via the API.
override.overridden_atstringISO 8601 timestamp of the override.
override.from_valueanyThe previous majority value.
override.to_valueanyThe new overridden value.
override.reasonstring | nullReason provided for the override.

Response

{
  "id": "cmp-uuid-1",
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_id": "doc-uuid-1",
  "field_name": "total_amount",
  "status": "yellow",
  "agreement_score": 0.6667,
  "majority_value": "12450.00",
  "comparison_method": "exact",
  "values": [
    { "shot_number": 1, "value": "12450.00" },
    { "shot_number": 2, "value": "12450.00" },
    { "shot_number": 3, "value": "12,450.00" }
  ],
  "override": {
    "selected_shot": 1,
    "actor_id": "api",
    "overridden_at": "2024-09-14T11:00:00.000Z",
    "from_value": "12450.00",
    "to_value": "12450.00",
    "reason": "Canonical decimal format preferred"
  },
  "judgement": null,
  "created_at": "2024-09-14T10:32:00.000Z",
  "links": {
    "self": "/v1/jobs/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/nshot/comparison?document_id=doc-uuid-1&field_name=total_amount"
  }
}

Use this when the majority value from the shots is incorrect and a different shot produced the right extraction. The override record captures a full audit trail including from_value, to_value, and overridden_at. Pair with the judge decision endpoint when you want to accept LLM recommendations programmatically instead of selecting shots manually.

Errors

Error responses

400validation_errorThe request body failed validation, e.g. document_id is not a UUID or selected_shot is not a number.
401unauthorizedMissing or invalid API key.
403forbiddenThe API key lacks the write scope required by this endpoint.
404not_foundNo job run with this ID exists for your organization, or no comparison found for the given document_id and field_name.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Single Comparison
Judge Decision
Summary