Retire a gap

POST /context/v1/gaps/{gap_id}/retire

Closes the gap. covered_by is optional: it may name the assets that cover the debt (each must be an asset of the release the closure is recorded under, else a 422 naming it), and rationale is a free closing note shown with the closure so it can be judged and reverted. The release that closed it is recorded (closed_release, the latest when omitted). Every version stays readable. A kit that carries the gap is not changed: it skips the retired gap when served and drops the member later. A gap that has moved since base_version is a 409 gap_moved.

Requires the context:gaps scope.

Parameters

Parameter	Location	Required	Description
`gap_id`	path	yes	The gap's id.

Request body

Field	Type	Required	Description
`base_version`	integer	yes	The gap version you read. A gap that has moved is a 409.
`closed_release`	integer or null	no	The release that covered the gap. Leave out for the latest release.
`covered_by`	array of string	no	Optional. The ids of the assets that cover the debt: zero or more, each an asset of the release the closure is recorded under, else a 422 naming it.
`expected_release`	integer or null	no
`rationale`	string	no	Why, recorded in the gap's journal.

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
`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/$GAP_ID/retire" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json