Sign in

v2

latestOpenAPI 3.1.02026-08-0382170235.8 KB
knowledge-gaps
knowledge-gaps

Transition a knowledge gap

Drive the gap state machine (open → routed → ingested → resolved, plus dismissed/duplicate/expired/reopened). expected_from is a compare-and-set guard: if the gap already moved, the write loses with 409. Illegal transitions return 422.

post/knowledge-gaps/{gap_id}/transitions

Path parameters

gap_idstring uuid required

Request body

expected_from'open' | 'routed' | 'ingested' | 'resolved' | 'expired' | 'dismissed' | 'duplicate' | 'reopened' required

State the caller believes the gap is in (compare-and-set guard).

to_state'open' | 'routed' | 'ingested' | 'resolved' | 'expired' | 'dismissed' | 'duplicate' | 'reopened' required

Target state.

actorstring required

Who performed the transition.

notestring nullable
evidence_refstring nullable

Optional link to the ingestion job / contribution that drove this transition.

assigned_tostring nullable

Opaque expert/DRI id the integrator routed to (set when moving to 'routed').

Response

Successful Response

gap_idstring uuid

UUIDv7 — chronologically sortable.

workspace_idstring uuid required

Owning workspace; multi-tenant isolation key.

pot_idstring uuid required

POT the question was asked against.

query_textstring required
requester_idstring required
domainstring required
trigger'low_confidence' | 'no_coverage' | 'manual'
trigger_scorenumber nullable
state'open' | 'routed' | 'ingested' | 'resolved' | 'expired' | 'dismissed' | 'duplicate' | 'reopened'
assigned_tostring nullable

Opaque id of the expert/DRI the integrator routed to. Core stores, never decides, this value.

resolved_cluster_idstring uuid nullable

Forward-compat hook: the Knowledge Cluster (nebula) a filled gap will seed in Phase 2. Always null in the pilot; the Cluster table is not built yet.

capsule_idstring uuid nullable

Capsule whose coverage evaluation created this gap (Capsules PR1b). Null for gaps born on the /query path or created manually. Marks the ORIGIN only — the trigger vocabulary is unchanged (no GapTrigger extension), so existing integrator payloads keep validating.

idempotency_keystring nullable
timeout_atstring date-time nullable

Optional SLA deadline. When elapsed, the integrator transitions the gap to 'expired' (core does not auto-expire — no scheduler in scope).

created_atstring date-time
updated_atstring date-time
resolved_atstring date-time nullable