Sign in

v2

latestOpenAPI 3.1.02026-08-0382170235.8 KB
fact-scope
fact-scope

Override a fact's scope_inferred (human correction of Approach D)

Apply a human correction to a fact's scope_inferred value. The LLM-extracted scope (own / third_party / mixed_context / unknown) may be wrong for documents that mix scopes — this endpoint lets the integrator (KB2B) record the human's correction.

Side effects:

  • Fact.scope_inferred is overwritten with the request value.
  • Fact.scope_confidence is reset to 1.0 (human assertion supersedes LLM uncertainty).
  • If rationale is provided, it replaces Fact.scope_reason (truncated to 500 chars).
  • Document.scope_summary is recomputed from all facts of the document.
  • A FactScopeOverrideRecord is persisted for audit (24h TTL).

Idempotency: idempotency_key is required. Replays within 24h return the original response without re-mutating the fact.

post/pots/{pot_id}/facts/{fact_id}/scope

Path parameters

pot_idstring uuid required
fact_idstring uuid required

Request body

scope'own' | 'third_party' | 'mixed_context' | 'unknown' required

New scope value to set on the fact (overwrites scope_inferred).

contributor_idstring uuid required

Contributor registry ID — must be a registered, active contributor.

rationalestring nullable

Optional human-readable reason for the override (stored in audit trail).

idempotency_keystring required

Client-generated unique key (UUID v4 recommended). Server replays the original response for the same key within 24h.

Response

Scope override applied (or idempotency replay)

fact_idstring uuid required
scope_before'own' | 'third_party' | 'mixed_context' | 'unknown' nullable required

Prior scope_inferred value. None when the fact was pre-Approach-D legacy.

scope_after'own' | 'third_party' | 'mixed_context' | 'unknown' required

The scope_inferred value actually persisted on the fact. On normal calls this matches the request; on idempotency replays it reflects the original override (which may differ from the retry's scope if the client changed their mind between attempts under the same key).

override_idstring uuid required

ID of the audit record created for this override.

document_scope_summary_afterobject nullable

The document's per-scope summary AT REPLY TIME, recomputed from all facts of the document. NOT a snapshot: on idempotency replays this reflects the CURRENT summary (which may have changed if other facts of the same document were overridden between the original call and the replay), not the value from the first call. The override RECORD is what's idempotent; the summary is live so clients render correct counts at the moment they render. None when the fact has no associated document.

idempotent_replayboolean

True when this response was served from the idempotency cache (the request was a retry of a prior call with the same idempotency_key). The fact and document state were NOT mutated again — the prior state is what's returned.