Skip to main content

Labels Manager

The Labels Manager is an org-level label library that lets you define a set of labels once and reuse them across projects. Useful when several projects share an ontology (e.g. "PII categories", "sentiment values", "African-language POS tags") and you want one canonical source of truth.

Without Labels Manager, every project's <Labels> / <Choices> list is hard-coded into its XML — meaning a label-naming change has to be made N times if N projects use it.

Where it lives​

Organization → Resources → Labels (/organization/resources/labels). The Resources tab groups the org's reusable assets — Templates, Consent, Labels and Knowledge bases — behind one top-level tab with a rail of sections on the left. Visible to org Owner, Admin, and Manager.

Concepts​

Two model types:

  • Label — a single label entry. Has a value (the string the XML uses and annotation results store), a title (the human-friendly display annotators see), and an optional description (tooltip shown to annotators).
  • LabelLink — joins a Label to one project's <Labels> / <Choices> tag, identified by the tag's name (from_name). A label can be linked into many projects via many LabelLinks. Editing the Label updates everywhere it's linked.

So the model is:

Two LabelLinks — same label, two projects.

Create a label​

  1. Organization → Resources → Labels → + New label
  2. Fill in:
    • Value — the literal string used in XML and stored in annotation results (e.g. POSITIVE). Pick it carefully — titles can be renamed safely later, values require an annotation-history rewrite.
    • Title — the display label shown to annotators (e.g. Positive sentiment)
    • Description — optional tooltip / help text
    • Link to projects — type to search, click to add one or more projects. At least one is required — a label is always created linked.
    • from_name — the name of the <Labels> / <Choices> tag in the linked project's config (e.g. sentiment). Applied to every project you picked; if a project uses a different tag name, link it separately afterwards.
  3. Click Create

The label lands in the library with a LabelLink to each project you picked.

From the label's card in the library:

  1. In + link to project…, type the project name and pick it
  2. Enter the tag's from_name in that project's config
  3. Click Link

Each link shows as a chip: project name, from_name, and the count of annotations using the label there. Click the chip's × to unlink.

Editing labels​

Two renames, with very different blast radii:

  • Rename title — safe. Display-only; propagates to every linked project. The stored annotation values don't change.
  • Rename value… — risky, and the UI says so. This rewrites the value in existing annotations across the label's linked projects (via POST /api/labels/bulk), then updates the library entry. The confirmation toast reports how many annotations were updated. Use it only when you mean to rewrite history — exports made before the rename will still carry the old value.

Delete a label​

Delete is only available after every LabelLink has been removed — unlink it from each project first (links keep annotations attributable). Deleting removes the label from the library; existing annotations are not touched.

There is no archive state — a label is either in the library or deleted.

Why use it​

A few common scenarios:

Shared ontologies across projects​

Your org runs five sentiment-analysis projects on five different text corpora. Without Labels Manager, you'd hard-code POSITIVE / NEUTRAL / NEGATIVE into each project's XML. Six months later you decide to add MIXED — you'd have to edit five XMLs.

With Labels Manager, you add MIXED to the library once and link it into each project.

Hierarchical taxonomies​

Your team labels animals with a 3-level taxonomy (kingdom → phylum → species, with hundreds of entries). Maintaining that as inline XML is painful. As a library, you define each label once, then link it into every project that needs it.

API​

Labels Manager is exposed via REST. All endpoints are scoped to your active organization:

# List labels with their project links
curl "{{platformURL}}/api/labels/?expand=links" \
  -H "Authorization: Bearer YOUR_PAT"

# Create a label linked to a project (takes an array; one project
# per request — add more projects via label_links)
curl -X POST "{{platformURL}}/api/labels/" \
  -H "Authorization: Bearer YOUR_PAT" \
  -H "Content-Type: application/json" \
  -d '[{"value": "POSITIVE", "title": "Positive", "description": "",
        "project": 12, "from_name": "sent"}]'

# Link an existing label to another project
curl -X POST "{{platformURL}}/api/label_links/" \
  -H "Authorization: Bearer YOUR_PAT" \
  -H "Content-Type: application/json" \
  -d '{"label": 42, "project": 13, "from_name": "kind"}'

# Safe title edit
curl -X PATCH "{{platformURL}}/api/labels/42/" \
  -H "Authorization: Bearer YOUR_PAT" \
  -H "Content-Type: application/json" \
  -d '{"title": "Positive sentiment"}'

# Risky value rename — rewrites existing annotation values
curl -X POST "{{platformURL}}/api/labels/bulk" \
  -H "Authorization: Bearer YOUR_PAT" \
  -H "Content-Type: application/json" \
  -d '{"old_label": "POSITIVE", "new_label": "POS"}'

When NOT to use Labels Manager​

For projects with one-off, project-specific labels that won't ever be reused, inlining in XML is fine. Labels Manager has a small overhead — every label needs a row in the database, every link adds a join. For 5-label classification projects that don't share labels with anything else, hard-coded XML is simpler.

What's next​