mask, box2d, box3d or landmark), and its fields. On the Taxonomy page (project Guidance tab, then Taxonomy), the geometry kind is the Annotation shape of a category. Every saved change binds a new version; the API calls saving a Taxonomy “bind”. The version is a hash of the canonical definition, so saving an unchanged Taxonomy writes nothing.
The Taxonomy page is part of the dashboard, which runs on Team and Enterprise. The Community self-host stack does not include the Nitsor dashboard. An Auto-label stage needs a hosted model run, which Community does not have.
Nitsor refuses a Taxonomy change that removes or re-kinds a category an Auto-label stage uses; see A guard for Auto-label categories. A Dataset Version records the Taxonomy version it was created under, with a class index of that version’s category names. A raw read of the version graph carries neither; see Exports and Taxonomy versions.
Four rules behind every change
- A Task keeps the Taxonomy version it was created under. The pin is written once and never updated. The review Task that follows it and any rework Task inherit the same pin. A new Task takes the version bound when it is created.
- The editor draws a Task’s categories from its pinned version. When the project has moved on, the label list says: “This Task is pinned to a different Taxonomy than the project now carries.”
- A commit is checked against the Task’s pinned version, not the branch’s current one. The dashboard refuses an edit made under any other version.
- An annotation stores its category’s id (
classId), not its name or colour. The id is the category’s identity. On the Taxonomy page it is fixed once the category is saved.
What each change does
On the Taxonomy page, Remove category takes a category out of the draft, and the Archived option archives it. Name, Annotation shape and colour edit a category in place.
Auto-label stages
An Auto-label stage pairs categories by id: the category the model proposes masks on, and, for a prompt, the category a person draws boxes or points in. Adding, renaming and recolouring leave the pairing intact. Nitsor checks the pairing from both sides on each branch:- Applying a pipeline refuses a stage that names a category the bound Taxonomy does not have (
workflow_runner_category_unnamed), or whose kind does not fit its role (workflow_runner_category_geometry_mismatch). A proposal category must be a mask category, and a prompt category must be the kind its prompt reads. - Saving a Taxonomy refuses removing a paired category or changing its kind; see the guard.
POST /api/v1/taxonomy/bind a caller can change an id, and a changed id is a removal plus an addition, with the effects of both.
A guard for Auto-label categories
Nitsor refuses a Taxonomy bind that removes a category, or changes its geometry kind, while the pipeline bound on that branch pairs it in an Auto-label stage. Nothing is saved. The refusal names the stage and the category, for example:Stage “auto-label” proposes on “Gland” (gland), so this Taxonomy cannot remove it. Archive the category instead, or take it out of that stage first.Through
POST /api/v1/taxonomy/bind the refusal is a 409 with the code taxonomy_category_runner_paired. Archiving stays allowed, because an archived category keeps its id and kind. A category no stage pairs can still be removed. To remove a paired category, take it out of the Auto-label stage on the Pipeline tab and apply the pipeline first.
Exports and Taxonomy versions
Two reads return annotations, and they differ in what they say about the Taxonomy.- A Dataset Version names its Taxonomy version. It pins a commit and records the Taxonomy version bound at that commit as
taxonomyVersion.GET /api/v1/dataset-versions/{id}returns it, and so does the manifest header. A class index sits beside the manifest: thetaxonomyVersionplus a{classId, name}entry for each category that version defines. It carries no colour and no geometry kind. A Dataset Version is immutable, so a later rename leaves its names alone, and a Dataset Version created after the rename takes the new name. An annotation in it carries only itsclassId, which you resolve through the class index. A category removed before the version’s commit is not in the index, so an annotation that still carries that id does not resolve there. When no Taxonomy was bound at that commit, the version has notaxonomyVersionand the index lists no classes. Release a dataset covers creating one. - A raw version-graph read does not.
GET /api/v1/version-graph/positionreturns each annotation with itsclassIdand no Taxonomy version, and nothing else in the response resolves that id.GET /api/v1/taxonomydoes, but it reads the branch’s current Taxonomy. So a renamed category resolves to its new name, a removed one does not resolve at all, and an archived one still resolves. Read the Taxonomy at the same time and keep its version with what you read.
Recommended practice
- Rename only to fix wording. A rename keeps the id, so every existing annotation takes the new name wherever the current Taxonomy is read, and so does each Dataset Version you create afterwards. A Dataset Version created earlier keeps the old name. When the meaning changes, for example “Nodule” becoming “Solid nodule” with part-solid nodules split out, add a new category and archive the old one.
- Archive rather than remove. Archive keeps old annotations resolvable and editable and stops new labels. Remove leaves ids that the current Taxonomy cannot resolve.
- Change the Auto-label stage first. Before you archive, remove or re-kind a category an Auto-label stage uses, point the stage at another category and apply the pipeline.
- Expect in-flight work to keep the old categories. A category you add today appears on Tasks created after the save. Pipelines describes the same rule for pipeline versions.
Next step
Read Pipelines to see how the same pinning applies to stages, then Version model for how Taxonomy versions sit in commit content.| Plans | All plans |
|---|---|
| Last verified | 2026-10-03 |