API ReferenceContext Repository
Record a gap
Records a piece of context debt at version 1 under the release named in `opened_release` (the latest when omitted).
POST /context/v1/gaps
Records a piece of context debt at version 1 under the release named in opened_release (the latest when omitted). A gap takes effect at once, needs no review and no release. Two open gaps cannot share a kind and a detail: recording one that is already open is a 409 duplicate_key naming the gap that holds it; a hole found again after its gap was closed opens a new gap. A gap names no kit: add it to a kit with the kit members call, using the gap's id.
Requires the context:gaps scope.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
detail | string | yes | What is missing and what it was needed for, in plain language. |
evidence | string | no | The excerpt or reasoning that surfaced it. |
id | string or null | no | Leave out: the service mints the gap's id. |
kind | string | yes | A short label for the sort of debt, such as missing_tool, missing_skill or missing_knowledge. Any short label is accepted. |
metadata | map of string | no | Free-form key-value pairs. |
opened_release | integer or null | no | The context release the gap is opened under. Leave out for the latest release. |
origin_context_id | string or null | no | The recorded run it was discovered in. |
rationale | string | no | Why, recorded in the gap's journal. |
tags | array of string | no | Free-form labels. |
Responses
| Status | Meaning |
|---|---|
200 | OK |
201 | The request succeeded. |
401 | The token is missing, expired or invalid. |
403 | The token does not carry the scope this operation requires. |
404 | No such project, or the token belongs to a different project. |
422 | The request was not valid: a parameter or the body failed validation. |
The 200 response body:
| Field | Type | Required | Description |
|---|---|---|---|
closed_release | integer or null | no | The release that covered the gap. Empty while the gap is still open. |
content_key | string | yes | What makes two reports one open debt: a digest of the kind and the detail. |
detail | string | yes | What is missing and what it was needed for. |
evidence | string | yes | The excerpt or reasoning that surfaced it. |
id | string | yes | The gap's id. |
kind | string | yes | A short label for the sort of debt: missing_tool, missing_skill, missing_knowledge or any other short label. |
kits | array of GapKitRecord | yes | The kits that carry this gap. |
last_changed_by | string or null | no | Who last changed the gap. |
last_changed_by_kind | string or null | no | person or automation. |
last_updated | string or null | no | When the gap last changed. |
last_updated_by | string or null | no | Whether the last change was made by a person (human) or by an automation (ai). |
metadata | map of string | yes | The gap's free-form key-value pairs. |
name | string or null | no | The gap's canonical name, projects/{project}/gaps/{id}. It is null when the id cannot be written in a canonical name. |
opened_release | integer or null | no | The context release the gap was opened under. Provenance only: a gap is served from live state. |
origin_context_id | string or null | no | The recorded run it was discovered in. |
retired | boolean | yes | Whether the gap has been closed. |
tags | array of string | yes | The gap's free-form labels. |
version | integer | yes | The gap's version. It moves each time the gap is changed, retired or reverted. |
Shapes
The named shapes used above.
GapKitRecord
A kit that carries a gap.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The kit's id. |
title | string | yes | The kit's title. |
version | integer | yes | The kit version that holds the gap. |
Example
curl -sS -X POST "$API_URL/context/v1/gaps" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @body.json