A tag you can apply across the workspace — to tasks, documents, files and more.
Labels are workspace-wide; this surface has no project-scoped labels.
Nifty's seeded labels report default: true and are protected — renaming or deleting one returns 403.
Deleting a label moves it to the trash: purgeAt is then a FUTURE date, 30 days out, when it will be purged for good.
List Labels
List labels. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by createdAt unless you pass sort.
Required scope: labels:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: createdAt.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
purgeAt[null]Filter where purgeAt is null (pass true).
purgeAt[notNull]Filter where purgeAt is not null (pass true).
purgeAt[gt]Filter where purgeAt is greater than.
purgeAt[gte]Filter where purgeAt is greater than or equal to.
purgeAt[lt]Filter where purgeAt is less than.
purgeAt[lte]Filter where purgeAt is less than or equal to.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
color[eq]Filter where color equals.
color[in]Filter where color is one of (comma-separated list).
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
List Labels › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Label
Create a Label. Server-assigned fields are ignored if sent. Send at least one of name or color; an empty body is rejected. Label names are unique per workspace among live labels, so reusing one returns 409.
Required scope: labels:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Label › Request Body
nameThe label text. Send at least one of name or color when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.
color^#([0-9A-Fa-f]{3}|[0…Hex color, #RGB or #RRGGBB. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so #00A99B reads back as #00a99b. Send at least one of name or color when creating a label.
typeWhat the label is for: others for an ordinary tag, member for the labels used to group people. Defaults to others, and cannot be changed afterwards.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: name | |
| type = object · requires: color |
nameThe label text. Send at least one of name or color when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.
color^#([0-9A-Fa-f]{3}|[0…Hex color, #RGB or #RRGGBB. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so #00A99B reads back as #00a99b. Send at least one of name or color when creating a label.
typeWhat the label is for: others for an ordinary tag, member for the labels used to group people. Defaults to others, and cannot be changed afterwards.
Create Label › Responses
Created
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameThe label text. Send at least one of name or color when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.
colorHex color, #RGB or #RRGGBB. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so #00A99B reads back as #00a99b. Send at least one of name or color when creating a label.
defaultTrue for the labels Nifty seeds into a workspace. Server-managed, and those labels are protected: renaming or deleting one returns 403.
typeWhat the label is for: others for an ordinary tag, member for the labels used to group people. Defaults to others, and cannot be changed afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who moved this label to the trash. A member id — resolve it with GET /members/{id}.
The related Actor, present only when you pass ?expand=createdByActor.
The related Team Member, present only when you pass ?expand=deletedBy.
Get Label
Retrieve a single Label by id.
Required scope: labels:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Label.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Label › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameThe label text. Send at least one of name or color when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.
colorHex color, #RGB or #RRGGBB. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so #00A99B reads back as #00a99b. Send at least one of name or color when creating a label.
defaultTrue for the labels Nifty seeds into a workspace. Server-managed, and those labels are protected: renaming or deleting one returns 403.
typeWhat the label is for: others for an ordinary tag, member for the labels used to group people. Defaults to others, and cannot be changed afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who moved this label to the trash. A member id — resolve it with GET /members/{id}.
The related Actor, present only when you pass ?expand=createdByActor.
The related Team Member, present only when you pass ?expand=deletedBy.
Delete Label
Move this Label to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.
Required scope: labels:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Label.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Label › Responses
No Content
Update Label
Partially update a Label. Only the fields you send are changed.
Required scope: labels:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Label.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update Label › Request Body
nameThe label text. Send at least one of name or color when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.
color^#([0-9A-Fa-f]{3}|[0…Hex color, #RGB or #RRGGBB. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so #00A99B reads back as #00a99b. Send at least one of name or color when creating a label.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update Label › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameThe label text. Send at least one of name or color when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.
colorHex color, #RGB or #RRGGBB. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so #00A99B reads back as #00a99b. Send at least one of name or color when creating a label.
defaultTrue for the labels Nifty seeds into a workspace. Server-managed, and those labels are protected: renaming or deleting one returns 403.
typeWhat the label is for: others for an ordinary tag, member for the labels used to group people. Defaults to others, and cannot be changed afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who moved this label to the trash. A member id — resolve it with GET /members/{id}.
The related Actor, present only when you pass ?expand=createdByActor.
The related Team Member, present only when you pass ?expand=deletedBy.
Search Labels
Full-text ranked search across labels. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields.
Required scope: labels:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
purgeAt[null]Filter where purgeAt is null (pass true).
purgeAt[notNull]Filter where purgeAt is not null (pass true).
purgeAt[gt]Filter where purgeAt is greater than.
purgeAt[gte]Filter where purgeAt is greater than or equal to.
purgeAt[lt]Filter where purgeAt is less than.
purgeAt[lte]Filter where purgeAt is less than or equal to.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
color[eq]Filter where color equals.
color[in]Filter where color is one of (comma-separated list).
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
Search Labels › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Restore Label
Restore a Label that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.
Required scope: labels:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Label.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Restore Label › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameThe label text. Send at least one of name or color when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.
colorHex color, #RGB or #RRGGBB. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so #00A99B reads back as #00a99b. Send at least one of name or color when creating a label.
defaultTrue for the labels Nifty seeds into a workspace. Server-managed, and those labels are protected: renaming or deleting one returns 403.
typeWhat the label is for: others for an ordinary tag, member for the labels used to group people. Defaults to others, and cannot be changed afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who moved this label to the trash. A member id — resolve it with GET /members/{id}.