Change a gap

Changes the gap's kind, detail, evidence, origin, tags or metadata and appends the next version.

PATCH /context/v1/gaps/{gap_id}

Changes the gap's kind, detail, evidence, origin, tags or metadata and appends the next version. Send the version you read as base_version: a gap that has moved is a 409 gap_moved carrying the current version. Fields you omit are unchanged. A request that changes nothing, a change onto the words of another gap, or a change to a retired gap is refused.

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.
`detail`	string or null	no	A sharper description of what is missing.
`evidence`	string or null	no	New evidence text.
`kind`	string or null	no	A new kind label.
`metadata`	map of string or null	no	The complete new key-value pairs.
`origin_context_id`	string or null	no	A different run it was discovered in.
`rationale`	string	no	Why, recorded in the gap's journal.
`tags`	array of string or null	no	The complete new tag list.

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 PATCH "$API_URL/context/v1/gaps/$GAP_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json