API ReferenceContext Repository
List gaps
Returns the project's gaps, by id.
GET /context/v1/gaps
Returns the project's gaps, by id. A gap is a piece of recorded context debt: something an agent needed that the context did not have. It is not an asset, so it is not listed with assets. By default only open gaps are returned; state asks for the retired ones or both, and kind keeps one sort of debt.
Requires the context:read scope.
Parameters
| Parameter | Location | Required | Description |
|---|---|---|---|
state | query | no | open (default), retired or all. |
kind | query | no | Only gaps of this kind, such as missing_tool. |
opened_release | query | no | Only gaps opened under this release. |
closed_release | query | no | Only gaps closed by this release. |
Responses
| Status | Meaning |
|---|---|
200 | 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 |
|---|---|---|---|
gaps | array of GapResponse | yes | The gaps asked for, by id. |
Shapes
The named shapes used above.
GapResponse
A gap: a piece of recorded context debt, something an agent needed that the context did not have. A gap is not an asset: it has its own versions and its own change journal, is written directly and is never part of a release.
| 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. |
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 "$API_URL/context/v1/gaps" \
-H "Authorization: Bearer $TOKEN"