Quick Summary: A label is a company-wide tag with a name, colour, icon and description. Labels form a tree of any depth, and the same label can be attached to skills, certifications, learning items and careers — one pool, four attachment points. Attaching is idempotent and all-or-nothing; deleting is guarded.
Attributes
The tree read returns the same object with a
children array, in position order.
Operations
Library
The flat list is filterable by
name, description and parentId, and sortable by name and position.
Create is plural by nature: { "labels": [{ name, color, description?, icon?, parentId? }] } in, the created labels out. color is required. Each new label is placed at the end of its sibling group.
Update takes name, description, icon and color; an explicit null clears the description or icon. Moving a label is its own operation (below).
Reorder sets positions within one sibling group: { "parentId": "4" | null, "ids": [...] } must list every label of that group exactly once, in the desired order. A partial or foreign list is 422 unprocessable.
Delete is guarded. If any object carries the label, or it has children, the call answers 409 conflict:
?confirm=true: the label is stripped from every object and each child is promoted to top level, renumbered after the existing roots — what the app does silently, now stated.
Hierarchy
Reparent takes
{ "parentId": "4" } to move the label, or { "parentId": null } to promote it to top level. It refuses with a 409 when the proposed parent is the label itself or one of its own descendants — the server checks the whole tree, not just the browser.
Attachment
The same three operations against each kind of object:
Attach and detach take
{ "labelIds": ["12", "15"] } and answer the object’s current labels. Attaching a label the object already carries succeeds without change, and the call applies wholly or not at all — a retry after a network failure is safe. Detaching a label the object does not carry is likewise a no-op. An unknown label is a 404; an unknown or foreign object is the same 404.
The in-use read returns only labels attached to at least one live object of the kind — the read that drives filter options — and works the same way for all four kinds.
Permissions
Any person who can read labels in the app can read them here. Creating, updating, reordering, reparenting, deleting, attaching and detaching are restricted to global administrators; a key acting as anyone else receives insufficient-permissions even when it holdslabels:write.
Excluded
People, skill, section and skill-group flags are a separate feature (see Flag). The labelled objects themselves belong to their own resources. CSV label import is an in-app path.Related errors
- not-found — the label, or the object being labelled, is not in your company
- validation-error — a missing name or colour, an unknown parent on create or reparent, a bad
kind - unprocessable — an incomplete reorder list
- conflict — a reparent that would create a cycle; the guarded delete