Create a kit

POST /context/v1/kits

Creates a kit at version 1, optionally with its first members. A kit is a named, versioned selection of assets an agent is given for a kind of work. It is not itself an asset: creating or changing one takes effect at once, needs no review and no release, and a release never changes a kit. Each member is an asset id; the role a kit holds it in follows from the asset's type, and an omitted rank appends. An asset that does not exist, or a kit named as a member, is a 422.

Requires the context:kits scope.

Request body

Field	Type	Required	Description
`auto_maintain`	boolean	no	Opt the kit in to automatic upkeep of its members. Off by default.
`description`	string	no	What the kit is for.
`id`	string or null	no	Leave out: the service mints the kit's id.
`members`	array of `KitMemberInput`	no	The assets the kit holds from the start, in serving order.
`metadata`	map of string	no	Free-form key-value pairs.
`rationale`	string	no	Why, recorded in the kit's journal.
`tags`	array of string	no	Free-form labels.
`title`	string	yes	The kit's title.

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
`auto_maintain`	boolean	yes	Whether the kit has opted in to automatic upkeep of its members. Off by default.
`description`	string	yes	What the kit is for.
`entries`	array of `KitEntry`	yes	The kit's skills and the tools each binds.
`gaps`	array of object	yes	Knowledge gaps the kit carries.
`id`	string	yes	The kit's id.
`ignored_members`	array of `KitIgnoredMemberRecord`	yes	Members the release this read named could not serve, with the reason. Empty when nothing was skipped.
`last_changed_by`	string or null	no	Who last changed the kit.
`last_changed_by_kind`	string or null	no	`person` or `automation`.
`last_updated`	string or null	no	When the kit last changed.
`last_updated_by`	string or null	no	Whether a person (`human`) or an automation (`ai`) last changed the kit.
`member_cards`	map of array of `AssetCard` or null	no	The short form of each served asset, grouped by asset type.
`member_roles`	map of string	yes	For each kind of asset id, the role a kit holds it in.
`members`	array of `KitMemberRecord`	yes	What this version of the kit holds, in serving order.
`members_by_type`	map of array of string	yes	The ids of the assets the kit served at that release, grouped by asset type.
`metadata`	map of string	yes	The kit's free-form key-value pairs.
`name`	string or null	no	The kit's canonical name, `projects/{project}/kits/{id}`. A request that takes a kit id in its body or query accepts this name in its place; a URL path takes the bare id. It is null when the id cannot be written in a canonical name.
`project_id`	string	yes	The project the kit belongs to.
`release`	integer or null	no	The release this read resolved the kit's assets at.
`retired`	boolean	yes	Whether the kit has been retired.
`tags`	array of string	yes	The kit's free-form labels.
`title`	string	yes	The kit's title.
`version`	integer	yes	The kit's version. It moves when the kit's fields or its members change.
`versions`	array of integer or null	no	Every version the kit has had. Present when a kit is read.

Shapes

The named shapes used above.

`KitMemberInput`

An asset to put in a kit, and optionally where.

Field	Type	Required	Description
`asset_id`	string	yes	The asset's id. It must exist; a kit cannot hold another kit.
`rank`	integer or null	no	Where in the kit's order of that role the asset goes. Leave out to append.
`role`	string, one of `contains`, `offers`, `carries` or null	no	Leave out. The role follows from the asset's type.

`KitEntry`

A skill a kit holds and the tools it binds.

Field	Type	Required	Description
`skill_id`	string	yes	The skill's id.
`skill_name`	string	yes	The skill's name.
`tool_ids`	array of string	yes	The ids of the tools the skill binds.

`KitIgnoredMemberRecord`

A held asset the kit did not serve at the release the read named, and why.

Field	Type	Required	Description
`member`	`KitMemberRecord`	yes	The held asset.
`reason`	string	yes	`retired` (a release retired it and nothing replaced it), `superseded` (a release retired it and the successors below were served in its place) or `unpublished` (the pinned release does not contain it yet).
`successor_ids`	array of string	yes	The assets served in its place, in order. Empty unless `superseded`.

`KitMemberRecord`

One asset a kit holds.

Field	Type	Required	Description
`asset_id`	string	yes	The held asset's id.
`asset_kind`	string	yes	The kind the id names: `skill`, `knowledge`, `tool`, `gap`, `memory`, `example`, `pointer` or `asset`.
`rank`	integer	yes	Its place within the role. Ranks are sparse, so an asset can be put between two others without renumbering them.
`role`	string	yes	How the kit holds it: `contains`, `offers` or `carries`.

`AssetCard`

The short form of an asset: enough to show it in a list without reading its body.

Field	Type	Required	Description
`id`	string	yes	The asset's id.
`summary`	string or null	no	A one- or two-line summary, or null when the asset's type has none.
`tags`	array of string	yes	The asset's tags.
`title`	string or null	no	A short title, or null when the asset's type has none.

Example

curl -sS -X POST "$API_URL/context/v1/kits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

On this page