Taxonomies

Taxonomies are workspace-owned classification lenses for insights, ideas, and opportunities. Use these endpoints to read the current lens, validate proposed groups, iterate on drafts, preview AI assignments, publish reviewed changes, and refresh classifications with explicit guards.

18 endpoints

GET

List taxonomies

GET /external/v1/taxonomies

List taxonomy schemas in the current workspace, including active and draft version ids.

Requirements

API scopes required:

taxonomies:read

Responses

200

Success

Taxonomies were retrieved.

Schema

Array<Taxonomy>

Example Request

GET

/external/v1/taxonomies

curl

curl -X GET https://zentrik.ai/api/external/v1/taxonomies \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

[
  {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "draftVersionId": "taxonomy-version-uuid",
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "usage": {
      "inUse": false
    }
  }
]

GET

Get active taxonomy

GET /external/v1/taxonomies/current

Read the active published taxonomy used for workspace classification. Returns null when nothing is published.

Requirements

API scopes required:

taxonomies:read

Responses

200

Success

The current taxonomy was returned, or null if none is published.

Example Request

GET

/external/v1/taxonomies/current

curl

curl -X GET https://zentrik.ai/api/external/v1/taxonomies/current \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "taxonomySchemaId": "taxonomy-uuid",
  "taxonomyVersionId": "taxonomy-version-uuid",
  "groups": [
    {
      "id": "group-uuid",
      "key": "strategic_motion",
      "label": "Strategic motion",
      "description": "Product action implied by the evidence.",
      "displayOrder": 0,
      "selectionMode": "SINGLE",
      "appliesTo": [
        "INSIGHT"
      ],
      "aiManagedTargets": [
        "INSIGHT"
      ],
      "valueType": "LIST",
      "required": false,
      "options": [
        {
          "id": "option-uuid",
          "valueKey": "build",
          "label": "Build",
          "displayOrder": 0
        }
      ]
    }
  ]
}

GET

Get one taxonomy

GET /external/v1/taxonomies/:id

Read one taxonomy with active, draft, and historical versions.

Requirements

API scopes required:

taxonomies:read

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.

Responses

200

Success

The taxonomy was returned.

Schema

Taxonomy

404

Not Found

No taxonomy found with the provided id.

Example Request

GET

/external/v1/taxonomies/:id

curl

curl -X GET https://zentrik.ai/api/external/v1/taxonomies/taxonomy-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "taxonomy-uuid",
  "name": "Customer decision lens",
  "status": "DRAFT",
  "activeVersionId": null,
  "createdAt": "2026-07-05T10:00:00Z",
  "updatedAt": "2026-07-05T10:00:00Z",
  "activeVersion": null,
  "draftVersion": {
    "id": "taxonomy-version-uuid",
    "versionNumber": 1,
    "status": "DRAFT",
    "revision": "revision-hash",
    "publishedAt": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "groups": [
      {
        "id": "group-uuid",
        "key": "strategic_motion",
        "label": "Strategic motion",
        "description": "Product action implied by the evidence.",
        "llmDescription": "Which product action should the team consider because of this evidence?",
        "selectionMode": "SINGLE",
        "appliesTo": [
          "INSIGHT"
        ],
        "aiManagedTargets": [
          "INSIGHT"
        ],
        "valueType": "LIST",
        "required": false,
        "displayOrder": 0,
        "options": [
          {
            "id": "option-uuid",
            "valueKey": "build",
            "label": "Build",
            "llmDescription": "Use when the evidence points to building or improving native product capability.",
            "parentValueKey": null,
            "displayOrder": 0
          }
        ]
      }
    ]
  },
  "versions": [],
  "usage": {
    "inUse": false
  }
}

POST

Validate taxonomy design

POST /external/v1/taxonomies/validate

Validate proposed groups before writing. This is the safest first step for generated or migrated taxonomy specs.

Requirements

API scopes required:

taxonomies:read

Request

Request body (application/json)

groupsTaxonomyGroup[]

Required

Full taxonomy group definitions. Group keys and option value keys should be stable snake_case identifiers; STRING groups still need an empty options array.

Responses

200

Success

Validation returned lint results without writing.

Example Request

POST

/external/v1/taxonomies/validate

json

{
  "groups": [
    {
      "id": "group-uuid",
      "key": "strategic_motion",
      "label": "Strategic motion",
      "description": "Product action implied by the evidence.",
      "llmDescription": "Which product action should the team consider because of this evidence?",
      "selectionMode": "SINGLE",
      "appliesTo": [
        "INSIGHT"
      ],
      "aiManagedTargets": [
        "INSIGHT"
      ],
      "valueType": "LIST",
      "required": false,
      "displayOrder": 0,
      "options": [
        {
          "id": "option-uuid",
          "valueKey": "build",
          "label": "Build",
          "llmDescription": "Use when the evidence points to building or improving native product capability.",
          "parentValueKey": null,
          "displayOrder": 0
        }
      ]
    }
  ]
}

Example Response

200 OK

json

{
  "hasBlockingErrors": false,
  "errors": [],
  "warnings": []
}

POST

Create a taxonomy draft

POST /external/v1/taxonomies

Create a taxonomy schema with an editable draft. Supply groups directly or clone an existing taxonomy.

Requirements

API scopes required:

taxonomies:write

Request

Request body (application/json)

namestring

Required

Human-readable taxonomy name.

cloneFromTaxonomyIduuid

Existing taxonomy to clone into the new draft.

groupsTaxonomyGroup[]

Initial draft groups.

Responses

201

Created

The taxonomy draft was created.

Schema

Taxonomy

Example Request

POST

/external/v1/taxonomies

json

{
  "name": "Customer decision lens",
  "groups": [
    {
      "id": "group-uuid",
      "key": "strategic_motion",
      "label": "Strategic motion",
      "description": "Product action implied by the evidence.",
      "llmDescription": "Which product action should the team consider because of this evidence?",
      "selectionMode": "SINGLE",
      "appliesTo": [
        "INSIGHT"
      ],
      "aiManagedTargets": [
        "INSIGHT"
      ],
      "valueType": "LIST",
      "required": false,
      "displayOrder": 0,
      "options": [
        {
          "id": "option-uuid",
          "valueKey": "build",
          "label": "Build",
          "llmDescription": "Use when the evidence points to building or improving native product capability.",
          "parentValueKey": null,
          "displayOrder": 0
        }
      ]
    }
  ]
}

Example Response

201 Created

json

{
  "id": "taxonomy-uuid",
  "name": "Customer decision lens",
  "status": "DRAFT",
  "activeVersionId": null,
  "createdAt": "2026-07-05T10:00:00Z",
  "updatedAt": "2026-07-05T10:00:00Z",
  "activeVersion": null,
  "draftVersion": {
    "id": "taxonomy-version-uuid",
    "versionNumber": 1,
    "status": "DRAFT",
    "revision": "revision-hash",
    "publishedAt": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "groups": [
      {
        "id": "group-uuid",
        "key": "strategic_motion",
        "label": "Strategic motion",
        "description": "Product action implied by the evidence.",
        "llmDescription": "Which product action should the team consider because of this evidence?",
        "selectionMode": "SINGLE",
        "appliesTo": [
          "INSIGHT"
        ],
        "aiManagedTargets": [
          "INSIGHT"
        ],
        "valueType": "LIST",
        "required": false,
        "displayOrder": 0,
        "options": [
          {
            "id": "option-uuid",
            "valueKey": "build",
            "label": "Build",
            "llmDescription": "Use when the evidence points to building or improving native product capability.",
            "parentValueKey": null,
            "displayOrder": 0
          }
        ]
      }
    ]
  },
  "versions": [],
  "usage": {
    "inUse": false
  }
}

PATCH

Update taxonomy draft

PATCH /external/v1/taxonomies/:id/draft

Replace the full draft name and/or groups. Prefer group and option endpoints for small iterative edits.

Requirements

API scopes required:

taxonomies:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.

Request body (application/json)

namestring

Updated taxonomy name.

groupsTaxonomyGroup[]

Full replacement group list.

expectedDraftRevisionstring

Current draft revision from readback. Use it for stale-write protection.

dryRunboolean

When true, returns lint and diff without changing the draft.

Responses

200

Success

Draft mutation result, lint, diff, and taxonomy readback were returned.

Example Request

PATCH

/external/v1/taxonomies/:id/draft

json

{
  "groups": [
    {
      "id": "group-uuid",
      "key": "strategic_motion",
      "label": "Strategic motion",
      "description": "Product action implied by the evidence.",
      "llmDescription": "Which product action should the team consider because of this evidence?",
      "selectionMode": "SINGLE",
      "appliesTo": [
        "INSIGHT"
      ],
      "aiManagedTargets": [
        "INSIGHT"
      ],
      "valueType": "LIST",
      "required": false,
      "displayOrder": 0,
      "options": [
        {
          "id": "option-uuid",
          "valueKey": "build",
          "label": "Build",
          "llmDescription": "Use when the evidence points to building or improving native product capability.",
          "parentValueKey": null,
          "displayOrder": 0
        }
      ]
    }
  ],
  "dryRun": true,
  "expectedDraftRevision": "revision-before"
}

Example Response

200 OK

json

{
  "dryRun": true,
  "baseDraftRevision": "revision-before",
  "draftRevision": "revision-after",
  "lint": {
    "hasBlockingErrors": false,
    "errors": [],
    "warnings": []
  },
  "diff": {
    "addedGroupKeys": [
      "strategic_motion"
    ],
    "removedGroupKeys": []
  },
  "taxonomy": {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "activeVersion": null,
    "draftVersion": {
      "id": "taxonomy-version-uuid",
      "versionNumber": 1,
      "status": "DRAFT",
      "revision": "revision-hash",
      "publishedAt": null,
      "createdAt": "2026-07-05T10:00:00Z",
      "updatedAt": "2026-07-05T10:00:00Z",
      "groups": [
        {
          "id": "group-uuid",
          "key": "strategic_motion",
          "label": "Strategic motion",
          "description": "Product action implied by the evidence.",
          "llmDescription": "Which product action should the team consider because of this evidence?",
          "selectionMode": "SINGLE",
          "appliesTo": [
            "INSIGHT"
          ],
          "aiManagedTargets": [
            "INSIGHT"
          ],
          "valueType": "LIST",
          "required": false,
          "displayOrder": 0,
          "options": [
            {
              "id": "option-uuid",
              "valueKey": "build",
              "label": "Build",
              "llmDescription": "Use when the evidence points to building or improving native product capability.",
              "parentValueKey": null,
              "displayOrder": 0
            }
          ]
        }
      ]
    },
    "versions": [],
    "usage": {
      "inUse": false
    }
  }
}

PUT

Create or replace a draft group

PUT /external/v1/taxonomies/:id/draft/groups/:groupKey

Create or replace one draft group by key. Use dryRun first when iterating from an agent.

Requirements

API scopes required:

taxonomies:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.
groupKey *	string	Stable group key.

Request body (application/json)

labelstring

Human-readable group label.

descriptionstring

Optional human-facing description.

llmDescriptionstring

Decision question and evidence boundary the model uses for assignment.

selectionModeenum

SINGLE or MULTI.

appliesToenum[]

Entity types where the field is available: INSIGHT, IDEA, OPPORTUNITY.

aiManagedTargetsenum[]

Entity types where AI should suggest values.

valueTypeenum

LIST or STRING.

requiredboolean

Whether the field should always have a value.

optionsTaxonomyOption[]

Allowed values for LIST groups.

expectedDraftRevisionstring

Current draft revision from readback. Use it for stale-write protection.

dryRunboolean

When true, returns lint and diff without changing the draft.

Responses

200

Success

Group mutation result was returned.

Example Request

PUT

/external/v1/taxonomies/:id/draft/groups/:groupKey

json

{
  "id": "group-uuid",
  "key": "strategic_motion",
  "label": "Strategic motion",
  "description": "Product action implied by the evidence.",
  "llmDescription": "Which product action should the team consider because of this evidence?",
  "selectionMode": "SINGLE",
  "appliesTo": [
    "INSIGHT"
  ],
  "aiManagedTargets": [
    "INSIGHT"
  ],
  "valueType": "LIST",
  "required": false,
  "displayOrder": 0,
  "options": [
    {
      "id": "option-uuid",
      "valueKey": "build",
      "label": "Build",
      "llmDescription": "Use when the evidence points to building or improving native product capability.",
      "parentValueKey": null,
      "displayOrder": 0
    }
  ],
  "dryRun": true
}

Example Response

200 OK

json

{
  "dryRun": true,
  "baseDraftRevision": "revision-before",
  "draftRevision": "revision-after",
  "lint": {
    "hasBlockingErrors": false,
    "errors": [],
    "warnings": []
  },
  "diff": {
    "addedGroupKeys": [
      "strategic_motion"
    ],
    "removedGroupKeys": []
  },
  "taxonomy": {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "activeVersion": null,
    "draftVersion": {
      "id": "taxonomy-version-uuid",
      "versionNumber": 1,
      "status": "DRAFT",
      "revision": "revision-hash",
      "publishedAt": null,
      "createdAt": "2026-07-05T10:00:00Z",
      "updatedAt": "2026-07-05T10:00:00Z",
      "groups": [
        {
          "id": "group-uuid",
          "key": "strategic_motion",
          "label": "Strategic motion",
          "description": "Product action implied by the evidence.",
          "llmDescription": "Which product action should the team consider because of this evidence?",
          "selectionMode": "SINGLE",
          "appliesTo": [
            "INSIGHT"
          ],
          "aiManagedTargets": [
            "INSIGHT"
          ],
          "valueType": "LIST",
          "required": false,
          "displayOrder": 0,
          "options": [
            {
              "id": "option-uuid",
              "valueKey": "build",
              "label": "Build",
              "llmDescription": "Use when the evidence points to building or improving native product capability.",
              "parentValueKey": null,
              "displayOrder": 0
            }
          ]
        }
      ]
    },
    "versions": [],
    "usage": {
      "inUse": false
    }
  }
}

PATCH

Update a draft group

PATCH /external/v1/taxonomies/:id/draft/groups/:groupKey

Patch one draft group without replacing unrelated fields.

Requirements

API scopes required:

taxonomies:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.
groupKey *	string	Stable group key.

Request body (application/json)

labelstring

Human-readable group label.

descriptionstring

Optional human-facing description.

llmDescriptionstring

Decision question and evidence boundary the model uses for assignment.

selectionModeenum

SINGLE or MULTI.

appliesToenum[]

Entity types where the field is available: INSIGHT, IDEA, OPPORTUNITY.

aiManagedTargetsenum[]

Entity types where AI should suggest values.

valueTypeenum

LIST or STRING.

requiredboolean

Whether the field should always have a value.

optionsTaxonomyOption[]

Allowed values for LIST groups.

expectedDraftRevisionstring

Current draft revision from readback. Use it for stale-write protection.

dryRunboolean

When true, returns lint and diff without changing the draft.

Responses

200

Success

Group patch result was returned.

Example Request

PATCH

/external/v1/taxonomies/:id/draft/groups/:groupKey

json

{
  "label": "Strategic motion",
  "dryRun": true
}

Example Response

200 OK

json

{
  "dryRun": true,
  "baseDraftRevision": "revision-before",
  "draftRevision": "revision-after",
  "lint": {
    "hasBlockingErrors": false,
    "errors": [],
    "warnings": []
  },
  "diff": {
    "addedGroupKeys": [
      "strategic_motion"
    ],
    "removedGroupKeys": []
  },
  "taxonomy": {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "activeVersion": null,
    "draftVersion": {
      "id": "taxonomy-version-uuid",
      "versionNumber": 1,
      "status": "DRAFT",
      "revision": "revision-hash",
      "publishedAt": null,
      "createdAt": "2026-07-05T10:00:00Z",
      "updatedAt": "2026-07-05T10:00:00Z",
      "groups": [
        {
          "id": "group-uuid",
          "key": "strategic_motion",
          "label": "Strategic motion",
          "description": "Product action implied by the evidence.",
          "llmDescription": "Which product action should the team consider because of this evidence?",
          "selectionMode": "SINGLE",
          "appliesTo": [
            "INSIGHT"
          ],
          "aiManagedTargets": [
            "INSIGHT"
          ],
          "valueType": "LIST",
          "required": false,
          "displayOrder": 0,
          "options": [
            {
              "id": "option-uuid",
              "valueKey": "build",
              "label": "Build",
              "llmDescription": "Use when the evidence points to building or improving native product capability.",
              "parentValueKey": null,
              "displayOrder": 0
            }
          ]
        }
      ]
    },
    "versions": [],
    "usage": {
      "inUse": false
    }
  }
}

DELETE

Delete a draft group

DELETE /external/v1/taxonomies/:id/draft/groups/:groupKey

Delete one draft group by key. Use dryRun and impact preview before removing classifications that may be in use.

Requirements

API scopes required:

taxonomies:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.
groupKey *	string	Stable group key.
dryRun	boolean	Return diff without deleting.
expectedDraftRevision	string	Current draft revision.

Responses

200

Success

Delete diff or mutation result was returned.

Example Request

DELETE

/external/v1/taxonomies/:id/draft/groups/:groupKey

curl

curl -X DELETE 'https://zentrik.ai/api/external/v1/taxonomies/taxonomy-uuid/draft/groups/strategic_motion?dryRun=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "dryRun": true,
  "baseDraftRevision": "revision-before",
  "draftRevision": "revision-after",
  "lint": {
    "hasBlockingErrors": false,
    "errors": [],
    "warnings": []
  },
  "diff": {
    "addedGroupKeys": [
      "strategic_motion"
    ],
    "removedGroupKeys": []
  },
  "taxonomy": {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "activeVersion": null,
    "draftVersion": {
      "id": "taxonomy-version-uuid",
      "versionNumber": 1,
      "status": "DRAFT",
      "revision": "revision-hash",
      "publishedAt": null,
      "createdAt": "2026-07-05T10:00:00Z",
      "updatedAt": "2026-07-05T10:00:00Z",
      "groups": [
        {
          "id": "group-uuid",
          "key": "strategic_motion",
          "label": "Strategic motion",
          "description": "Product action implied by the evidence.",
          "llmDescription": "Which product action should the team consider because of this evidence?",
          "selectionMode": "SINGLE",
          "appliesTo": [
            "INSIGHT"
          ],
          "aiManagedTargets": [
            "INSIGHT"
          ],
          "valueType": "LIST",
          "required": false,
          "displayOrder": 0,
          "options": [
            {
              "id": "option-uuid",
              "valueKey": "build",
              "label": "Build",
              "llmDescription": "Use when the evidence points to building or improving native product capability.",
              "parentValueKey": null,
              "displayOrder": 0
            }
          ]
        }
      ]
    },
    "versions": [],
    "usage": {
      "inUse": false
    }
  }
}

PUT

Create or replace a draft option

PUT /external/v1/taxonomies/:id/draft/groups/:groupKey/options/:valueKey

Create or replace one option in a draft LIST group.

Requirements

API scopes required:

taxonomies:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.
groupKey *	string	Stable group key.
valueKey *	string	Stable option key.

Request body (application/json)

labelstring

Human-readable option label.

llmDescriptionstring

Boundary for when this option should be selected.

parentValueKeystring

Optional parent option key in the same group.

displayOrdernumber

Sort order within the group.

expectedDraftRevisionstring

Current draft revision from readback. Use it for stale-write protection.

dryRunboolean

When true, returns lint and diff without changing the draft.

Responses

200

Success

Option mutation result was returned.

Example Request

PUT

/external/v1/taxonomies/:id/draft/groups/:groupKey/options/:valueKey

json

{
  "id": "option-uuid",
  "valueKey": "build",
  "label": "Build",
  "llmDescription": "Use when the evidence points to building or improving native product capability.",
  "parentValueKey": null,
  "displayOrder": 0,
  "dryRun": true
}

Example Response

200 OK

json

{
  "dryRun": true,
  "baseDraftRevision": "revision-before",
  "draftRevision": "revision-after",
  "lint": {
    "hasBlockingErrors": false,
    "errors": [],
    "warnings": []
  },
  "diff": {
    "addedGroupKeys": [
      "strategic_motion"
    ],
    "removedGroupKeys": []
  },
  "taxonomy": {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "activeVersion": null,
    "draftVersion": {
      "id": "taxonomy-version-uuid",
      "versionNumber": 1,
      "status": "DRAFT",
      "revision": "revision-hash",
      "publishedAt": null,
      "createdAt": "2026-07-05T10:00:00Z",
      "updatedAt": "2026-07-05T10:00:00Z",
      "groups": [
        {
          "id": "group-uuid",
          "key": "strategic_motion",
          "label": "Strategic motion",
          "description": "Product action implied by the evidence.",
          "llmDescription": "Which product action should the team consider because of this evidence?",
          "selectionMode": "SINGLE",
          "appliesTo": [
            "INSIGHT"
          ],
          "aiManagedTargets": [
            "INSIGHT"
          ],
          "valueType": "LIST",
          "required": false,
          "displayOrder": 0,
          "options": [
            {
              "id": "option-uuid",
              "valueKey": "build",
              "label": "Build",
              "llmDescription": "Use when the evidence points to building or improving native product capability.",
              "parentValueKey": null,
              "displayOrder": 0
            }
          ]
        }
      ]
    },
    "versions": [],
    "usage": {
      "inUse": false
    }
  }
}

PATCH

Update a draft option

PATCH /external/v1/taxonomies/:id/draft/groups/:groupKey/options/:valueKey

Patch one option without replacing unrelated fields.

Requirements

API scopes required:

taxonomies:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.
groupKey *	string	Stable group key.
valueKey *	string	Stable option key.

Request body (application/json)

labelstring

Human-readable option label.

llmDescriptionstring

Boundary for when this option should be selected.

parentValueKeystring

Optional parent option key in the same group.

displayOrdernumber

Sort order within the group.

expectedDraftRevisionstring

Current draft revision from readback. Use it for stale-write protection.

dryRunboolean

When true, returns lint and diff without changing the draft.

Responses

200

Success

Option patch result was returned.

Example Request

PATCH

/external/v1/taxonomies/:id/draft/groups/:groupKey/options/:valueKey

json

{
  "label": "Build",
  "dryRun": true
}

Example Response

200 OK

json

{
  "dryRun": true,
  "baseDraftRevision": "revision-before",
  "draftRevision": "revision-after",
  "lint": {
    "hasBlockingErrors": false,
    "errors": [],
    "warnings": []
  },
  "diff": {
    "addedGroupKeys": [
      "strategic_motion"
    ],
    "removedGroupKeys": []
  },
  "taxonomy": {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "activeVersion": null,
    "draftVersion": {
      "id": "taxonomy-version-uuid",
      "versionNumber": 1,
      "status": "DRAFT",
      "revision": "revision-hash",
      "publishedAt": null,
      "createdAt": "2026-07-05T10:00:00Z",
      "updatedAt": "2026-07-05T10:00:00Z",
      "groups": [
        {
          "id": "group-uuid",
          "key": "strategic_motion",
          "label": "Strategic motion",
          "description": "Product action implied by the evidence.",
          "llmDescription": "Which product action should the team consider because of this evidence?",
          "selectionMode": "SINGLE",
          "appliesTo": [
            "INSIGHT"
          ],
          "aiManagedTargets": [
            "INSIGHT"
          ],
          "valueType": "LIST",
          "required": false,
          "displayOrder": 0,
          "options": [
            {
              "id": "option-uuid",
              "valueKey": "build",
              "label": "Build",
              "llmDescription": "Use when the evidence points to building or improving native product capability.",
              "parentValueKey": null,
              "displayOrder": 0
            }
          ]
        }
      ]
    },
    "versions": [],
    "usage": {
      "inUse": false
    }
  }
}

DELETE

Delete a draft option

DELETE /external/v1/taxonomies/:id/draft/groups/:groupKey/options/:valueKey

Delete one option from a draft group. Use dryRun first to inspect the diff.

Requirements

API scopes required:

taxonomies:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.
groupKey *	string	Stable group key.
valueKey *	string	Stable option key.
dryRun	boolean	Return diff without deleting.

Responses

200

Success

Delete diff or mutation result was returned.

Example Request

DELETE

/external/v1/taxonomies/:id/draft/groups/:groupKey/options/:valueKey

curl

curl -X DELETE 'https://zentrik.ai/api/external/v1/taxonomies/taxonomy-uuid/draft/groups/strategic_motion/options/build?dryRun=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "dryRun": true,
  "baseDraftRevision": "revision-before",
  "draftRevision": "revision-after",
  "lint": {
    "hasBlockingErrors": false,
    "errors": [],
    "warnings": []
  },
  "diff": {
    "addedGroupKeys": [
      "strategic_motion"
    ],
    "removedGroupKeys": []
  },
  "taxonomy": {
    "id": "taxonomy-uuid",
    "name": "Customer decision lens",
    "status": "DRAFT",
    "activeVersionId": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "activeVersion": null,
    "draftVersion": {
      "id": "taxonomy-version-uuid",
      "versionNumber": 1,
      "status": "DRAFT",
      "revision": "revision-hash",
      "publishedAt": null,
      "createdAt": "2026-07-05T10:00:00Z",
      "updatedAt": "2026-07-05T10:00:00Z",
      "groups": [
        {
          "id": "group-uuid",
          "key": "strategic_motion",
          "label": "Strategic motion",
          "description": "Product action implied by the evidence.",
          "llmDescription": "Which product action should the team consider because of this evidence?",
          "selectionMode": "SINGLE",
          "appliesTo": [
            "INSIGHT"
          ],
          "aiManagedTargets": [
            "INSIGHT"
          ],
          "valueType": "LIST",
          "required": false,
          "displayOrder": 0,
          "options": [
            {
              "id": "option-uuid",
              "valueKey": "build",
              "label": "Build",
              "llmDescription": "Use when the evidence points to building or improving native product capability.",
              "parentValueKey": null,
              "displayOrder": 0
            }
          ]
        }
      ]
    },
    "versions": [],
    "usage": {
      "inUse": false
    }
  }
}

POST

Preview AI assignments

POST /external/v1/taxonomies/:id/preview

Run a non-persisted AI assignment preview against selected entities or a sample. Use this before publish.

Requirements

API scopes required:

taxonomies:read

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.

Request body (application/json)

entityTypeenum

INSIGHT, IDEA, or OPPORTUNITY. Defaults to INSIGHT.

entityIdsuuid[]

Specific entity ids to preview.

insightIdsuuid[]

Legacy insight id list for insight previews.

sampleSizenumber

Number of representative entities to sample.

Responses

200

Success

Preview assignments and diagnostics were returned.

Example Request

POST

/external/v1/taxonomies/:id/preview

json

{
  "entityType": "INSIGHT",
  "sampleSize": 5
}

Example Response

200 OK

json

{
  "taxonomyId": "taxonomy-uuid",
  "sampleSize": 5,
  "results": [],
  "previewReport": {
    "sampleSize": 5,
    "groups": []
  }
}

POST

Preview publish impact

POST /external/v1/taxonomies/:id/impact-preview

Inspect publish impact, including changed groups, removed options, and affected classifications.

Requirements

API scopes required:

taxonomies:read

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.

Responses

200

Success

Impact preview was returned.

Example Request

POST

/external/v1/taxonomies/:id/impact-preview

curl

curl -X POST https://zentrik.ai/api/external/v1/taxonomies/taxonomy-uuid/impact-preview \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "taxonomyId": "taxonomy-uuid",
  "totalInsights": 42,
  "impactedInsights": 0,
  "changedGroups": [
    "strategic_motion"
  ],
  "removedOptions": [],
  "changedOptions": [],
  "hasDraft": true
}

POST

Publish taxonomy

POST /external/v1/taxonomies/:id/publish

Publish the current draft as the active taxonomy. This requires explicit confirmation and a draft revision guard.

Requirements

API scopes required:

taxonomies:publish

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.

Request body (application/json)

confirmationstring

Required

Must be PUBLISH_TAXONOMY.

expectedDraftVersionIduuid

Draft version id from readback.

expectedDraftRevisionstring

Draft revision from readback.

skipPreviewJustificationstring

Operator justification when intentionally bypassing preview.

Responses

200

Published

The taxonomy was published.

Schema

Taxonomy

Example Request

POST

/external/v1/taxonomies/:id/publish

json

{
  "confirmation": "PUBLISH_TAXONOMY",
  "expectedDraftRevision": "revision-after"
}

Example Response

200 OK

json

{
  "id": "taxonomy-uuid",
  "name": "Customer decision lens",
  "status": "PUBLISHED",
  "activeVersionId": "taxonomy-version-uuid",
  "createdAt": "2026-07-05T10:00:00Z",
  "updatedAt": "2026-07-05T10:00:00Z",
  "activeVersion": {
    "id": "taxonomy-version-uuid",
    "versionNumber": 1,
    "status": "DRAFT",
    "revision": "revision-hash",
    "publishedAt": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "groups": [
      {
        "id": "group-uuid",
        "key": "strategic_motion",
        "label": "Strategic motion",
        "description": "Product action implied by the evidence.",
        "llmDescription": "Which product action should the team consider because of this evidence?",
        "selectionMode": "SINGLE",
        "appliesTo": [
          "INSIGHT"
        ],
        "aiManagedTargets": [
          "INSIGHT"
        ],
        "valueType": "LIST",
        "required": false,
        "displayOrder": 0,
        "options": [
          {
            "id": "option-uuid",
            "valueKey": "build",
            "label": "Build",
            "llmDescription": "Use when the evidence points to building or improving native product capability.",
            "parentValueKey": null,
            "displayOrder": 0
          }
        ]
      }
    ]
  },
  "draftVersion": {
    "id": "taxonomy-version-uuid",
    "versionNumber": 1,
    "status": "DRAFT",
    "revision": "revision-hash",
    "publishedAt": null,
    "createdAt": "2026-07-05T10:00:00Z",
    "updatedAt": "2026-07-05T10:00:00Z",
    "groups": [
      {
        "id": "group-uuid",
        "key": "strategic_motion",
        "label": "Strategic motion",
        "description": "Product action implied by the evidence.",
        "llmDescription": "Which product action should the team consider because of this evidence?",
        "selectionMode": "SINGLE",
        "appliesTo": [
          "INSIGHT"
        ],
        "aiManagedTargets": [
          "INSIGHT"
        ],
        "valueType": "LIST",
        "required": false,
        "displayOrder": 0,
        "options": [
          {
            "id": "option-uuid",
            "valueKey": "build",
            "label": "Build",
            "llmDescription": "Use when the evidence points to building or improving native product capability.",
            "parentValueKey": null,
            "displayOrder": 0
          }
        ]
      }
    ]
  },
  "versions": [],
  "usage": {
    "inUse": false
  }
}

POST

Start classification run

POST /external/v1/taxonomies/:id/reclassify

Start a targeted or full classification run. Targeted runs can use entityIds; full runs require explicit confirmation.

Requirements

API scopes required:

classification-runs:write

Request

Parameters

Name	Type	Description
id *	uuid	The taxonomy schema UUID.

Request body (application/json)

modeenum

TARGETED, ENTITY_IDS, INSIGHT_IDS, or FULL.

entityTypeenum

INSIGHT, IDEA, or OPPORTUNITY.

entityIdsuuid[]

Specific entity ids for targeted runs.

insightIdsuuid[]

Legacy insight id list.

confirmationstring

FULL runs require RECLASSIFY_TAXONOMY_FULL.

expectedTaxonomyVersionIduuid

Published taxonomy version id for full-run guard.

Responses

201

Queued

The classification run was queued.

Schema

ClassificationRun

Example Request

POST

/external/v1/taxonomies/:id/reclassify

json

{
  "mode": "TARGETED",
  "entityType": "INSIGHT",
  "entityIds": [
    "insight-uuid"
  ]
}

Example Response

201 Created

json

{
  "id": "classification-run-uuid",
  "taxonomySchemaId": "taxonomy-uuid",
  "taxonomyVersionId": "taxonomy-version-uuid",
  "mode": "TARGETED",
  "entityType": "INSIGHT",
  "status": "PENDING",
  "totalItems": 5,
  "processedItems": 0,
  "autoAppliedItems": 0,
  "needsReviewItems": 0,
  "failedItems": 0,
  "requestedById": null,
  "metadata": null,
  "failedReason": null,
  "startedAt": null,
  "completedAt": null,
  "createdAt": "2026-07-05T10:00:00Z",
  "updatedAt": "2026-07-05T10:00:00Z"
}

GET

Get classification run

GET /external/v1/classification-runs/:runId

Poll a classification run until it completes or fails.

Requirements

API scopes required:

classification-runs:read

Request

Parameters

Name	Type	Description
runId *	uuid	The classification run UUID.

Responses

200

Success

The run state was returned.

Schema

ClassificationRun

Example Request

GET

/external/v1/classification-runs/:runId

curl

curl -X GET https://zentrik.ai/api/external/v1/classification-runs/classification-run-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "id": "classification-run-uuid",
  "taxonomySchemaId": "taxonomy-uuid",
  "taxonomyVersionId": "taxonomy-version-uuid",
  "mode": "TARGETED",
  "entityType": "INSIGHT",
  "status": "PENDING",
  "totalItems": 5,
  "processedItems": 0,
  "autoAppliedItems": 0,
  "needsReviewItems": 0,
  "failedItems": 0,
  "requestedById": null,
  "metadata": null,
  "failedReason": null,
  "startedAt": null,
  "completedAt": null,
  "createdAt": "2026-07-05T10:00:00Z",
  "updatedAt": "2026-07-05T10:00:00Z"
}

GET

List classification queue

GET /external/v1/classification-queue

List classification review work for the workspace.

Requirements

API scopes required:

classification-queue:read

Request

Parameters

Name	Type	Description
limit	number	Maximum number of queue items to return.
offset	number	Number of queue items to skip.
productId	uuid	Filter by product.
reviewStatuses	string	Comma-separated review statuses.

Responses

200

Success

Classification queue items were returned.

Example Request

GET

/external/v1/classification-queue

curl

curl -X GET 'https://zentrik.ai/api/external/v1/classification-queue?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK

json

{
  "items": [],
  "total": 0,
  "limit": 20,
  "offset": 0
}

Data Models

Taxonomy storage is versioned. Draft changes stay isolated until publish activates one coherent taxonomy version for the workspace.

Taxonomy Object

Field	Type	Description
id	uuid	The unique identifier for the taxonomy schema.
name	string	Human-readable taxonomy name.
status	enum	DRAFT or PUBLISHED lifecycle state.
activeVersionId	uuid \| null	Currently published version id, if one exists.
activeVersion	object \| null	Published taxonomy version with groups and options.
draftVersion	object \| null	Editable draft version with groups and options.
versions	object[]	Historical versions returned by detailed reads.
usage	object \| null	Usage summary such as whether the taxonomy is in use.
createdAt	iso-date	Timestamp when the taxonomy was created.
updatedAt	iso-date	Timestamp of the latest taxonomy update.

TaxonomyGroup Object

Field	Type	Description
id	uuid	The unique identifier for the group.
key	string	Stable key for the classification dimension.
label	string	Human-readable field name.
description	string \| null	Human-facing description shown in management surfaces.
llmDescription	string	Model-facing guidance for assigning the group.
selectionMode	enum	SINGLE or MULTI.
appliesTo	enum[]	Entity types where the field appears.
aiManagedTargets	enum[]	Entity types where AI suggests values.
valueType	enum	LIST for options or STRING for text values.
required	boolean	Whether the group should receive a value for every target entity.
displayOrder	number	Sort order across groups.
options	TaxonomyOption[]	Allowed values for LIST groups; use an empty array for STRING groups.

TaxonomyOption Object

Field	Type	Description
id	uuid	The unique identifier for the option.
valueKey	string	Stable key for the allowed value.
label	string	Human-readable option label.
llmDescription	string	Model-facing boundary for this option.
parentValueKey	string \| null	Optional parent option key for hierarchy.
displayOrder	number	Sort order within the group.

ClassificationRun Object

Field	Type	Description
id	uuid	The unique identifier for the classification run.
taxonomySchemaId	uuid	Taxonomy schema used by the run.
taxonomyVersionId	uuid	Published taxonomy version used by the run.
mode	enum	FULL, TARGETED, INSIGHT_IDS, or ENTITY_IDS.
entityType	enum	INSIGHT, IDEA, or OPPORTUNITY.
status	enum	PENDING, RUNNING, COMPLETED, FAILED, or CANCELED.
totalItems	number	Number of entities queued.
processedItems	number	Number of entities processed so far.
autoAppliedItems	number	Assignments applied without review.
needsReviewItems	number	Assignments left in review.
failedItems	number	Items that failed classification.
failedReason	string \| null	Failure reason when the run fails.
createdAt	iso-date	Timestamp when the run was created.
updatedAt	iso-date	Timestamp of the latest run update.