SCscipot
knowledge-gaps
knowledge-gaps

Record a knowledge gap

Changed on

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).

post/pots/{pot_id}/knowledge-gaps

Request

Path parameters

pot_idstring required

POT identifier (UUID or slug)

Request body

query_textstring required

The original question the brain could not confidently answer.

contextstring nullable

The asker's case, as they told it: where it happens, what they see, what they already tried. Shown with the question to whoever answers it, so they never have to go back to the asker; never used to retrieve or to deduplicate (query_text is the question the brain is asked again).

requester_idstring required

Opaque integrator id of the asker, so it can be re-answered on resolve.

domainstring 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_scorenumber nullable

The gap_signal value that fired the gap, if any (for later threshold tuning).

idempotency_keystring nullable

Optional dedup key. Repeated create calls with the same key + workspace return the existing gap instead of creating a duplicate.

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
contextstring nullable

The asker's case (where, what they see, what they tried); null when none was given. Gaps written before 0.7.24.0 have none.

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

Deprecated, always null: a hook for a Knowledge Cluster that was never built. Kept so stored items and clients keep validating.

capsule_idstring uuid nullable

Deprecated, always null in production: set only by the Capsules coverage evaluation, behind capsules_enabled (off). Marks the ORIGIN only; the trigger vocabulary is unchanged, so existing integrator payloads keep validating.

idempotency_keystring nullable
timeout_atstring date-time nullable

Deprecated, always null: no route sets it and the core never expires a gap; an SLA is the integrator's, which drives the gap to 'expired' itself.

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

Changes

  • e6f2189e7b2fRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

  • 9c8cf6ae7c8bRevision changes
    • info

      added the optional property to the response with the status