Skip to main content
POST
Bind the taxonomy

Authorizations

Authorization
string
header
required

An Agent credential (nits_…), or a person token (nitp_…) on a deployment that enables them. GET /api/v1/session names the principal a credential proves.

Body

application/json

Invalid definitions answer INVALID_ARGUMENT with a field path inside the request body, such as definition.categories.1.groupId for an unknown group on the second category. An override vector whose length differs from the category count answers INVALID_ARGUMENT with the field path guaranteeOverrides. A category icon accepts only the first sixteen MarkIcon names (grid, folder, layers, scan, heart, lungs, brain, bone, cell, flask, camera, document, tag, star, bolt, target); the rest are for project marks, and a category carrying one answers INVALID_ARGUMENT at definition.categories.N.icon. A definition stored before this rule may still return one of the others from GET /api/v1/taxonomy; remove it before binding that definition again.

projectId
string
required
Required string length: 1 - 200
branchId
string
required
Required string length: 1 - 200
definition
object
required

Category, field and group ids are unique; a category's parentId names another declared category and parent chains do not cycle; every fieldIds entry names a declared field; a category's groupId names a declared group, a position needs a groupId, and positions are unique within a group. groups is absent rather than empty.

expectedTaxonomyVersion
string | null
required
Required string length: 1 - 200
idempotencyKey
string
required
Required string length: 1 - 200
guaranteeOverrides
boolean[]

Response

Bind the taxonomy

checkpointRequired
boolean
required
taxonomyVersion
string
required
unchanged
boolean
required