---
title: "Record a knowledge gap"
method: POST
path: "/pots/{pot_id}/knowledge-gaps"
tags: ["knowledge-gaps", "knowledge-gaps"]
---

# Record a knowledge gap

`POST /pots/{pot_id}/knowledge-gaps`

Record that the brain could not confidently answer a question against this POT. Idempotent on `idempotency_key` within the workspace — a repeated create with the same key returns the existing gap instead of a duplicate. The integrator decides *when* to create a gap (e.g. when a synthesis response has `is_knowledge_gap=true`).

## Path parameters

- `pot_id` string, required — POT identifier (UUID or slug)

## Request body

- KnowledgeGapCreateRequest — JSON body for ``POST /pots/{pot_id}/knowledge-gaps``. ``extra='forbid'`` rejects unknown fields with a 422 (mirrors ContextAttachmentCreateRequest / IngestionRequest discipline).
  - `query_text` string, required — The original question the brain could not confidently answer.
  - `requester_id` string, required — Opaque integrator id of the asker, so it can be re-answered on resolve.
  - `domain` string, required — Routing key — typically the fact classification domain. The integrator routes on this; core does not interpret it.
  - `trigger` 'low_confidence' | 'no_coverage' | 'manual' — Why the gap fired (low_confidence | no_coverage | manual).
  - `trigger_score` number, nullable — The gap_signal value that fired the gap, if any (for later threshold tuning).
  - `idempotency_key` string, nullable — Optional dedup key. Repeated create calls with the same key + workspace return the existing gap instead of creating a duplicate.

## Response `201`

Successful Response

- KnowledgeGap — Persisted gap item — repository row shape and API response body.
  - `gap_id` string, uuid — UUIDv7 — chronologically sortable.
  - `workspace_id` string, uuid, required — Owning workspace; multi-tenant isolation key.
  - `pot_id` string, uuid, required — POT the question was asked against.
  - `query_text` string, required
  - `requester_id` string, required
  - `domain` string, required
  - `trigger` 'low_confidence' | 'no_coverage' | 'manual'
  - `trigger_score` number, nullable
  - `state` 'open' | 'routed' | 'ingested' | 'resolved' | 'expired' | 'dismissed' | 'duplicate' | 'reopened'
  - `assigned_to` string, nullable — Opaque id of the expert/DRI the integrator routed to. Core stores, never decides, this value.
  - `resolved_cluster_id` string, 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_id` string, 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_key` string, nullable
  - `transitions` GapTransition[] — Append-only transition history (actor + timestamp per state change).
    - `from_state` 'open' | 'routed' | 'ingested' | 'resolved' | 'expired' | 'dismissed' | 'duplicate' | 'reopened', required
    - `to_state` 'open' | 'routed' | 'ingested' | 'resolved' | 'expired' | 'dismissed' | 'duplicate' | 'reopened', required
    - `actor` string, required — Who/what performed the transition (opaque integrator id).
    - `at` string, date-time
    - `note` string, nullable
    - `evidence_ref` string, nullable — Optional link to the ingestion job / contribution that drove this transition.
  - `timeout_at` string, 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_at` string, date-time
  - `updated_at` string, date-time
  - `resolved_at` string, date-time, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/scipot/apis/scipot-core-api.md) · [All operations](https://skmtc.dev/scipot/apis/scipot-core-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scipot/scipot-core-api/revisions/e8712e9ffeae/schema)