Status
A project-scoped status column for tasks (Kanban column, list stage). Carries a name, a hex color, a rank and an archived flag. Tasks reference their status by statusId. To mark a task done, set its completed flag. Completed tasks render in a virtual "Completed" column.
List Statuses
List statuses. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by order unless you pass sort.
Required scope: statuses:read
query Parameters
projectIdRestrict the list to one project. Omit to list statuses across every project you can access.
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: order. Listing without projectId orders by -updatedAt instead.
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.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
archived[eq]Filter where archived equals.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId 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.
updatedAt[gt]Filter where updatedAt is greater than.
updatedAt[gte]Filter where updatedAt is greater than or equal to.
updatedAt[lt]Filter where updatedAt is less than.
updatedAt[lte]Filter where updatedAt is less than or equal to.
List Statuses › 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 Status
Create a Status. Server-assigned fields are ignored if sent.
Required scope: statuses: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 Status › Request Body
nameStatus column name (e.g. "To Do", "In Progress"). 1–100 characters after trimming.
projectIdProject this status column belongs to. Set once on create — a status cannot be moved to another project.
color^#([0-9A-Fa-f]{3}|[0…Hex color (#RGB or #RRGGBB, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.
orderFractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.
archivedWhether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no archivedAt/archivedById stamp — use the audit log if you need to know who archived it and when.
Create Status › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
nameStatus column name (e.g. "To Do", "In Progress"). 1–100 characters after trimming.
archivedWhether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no archivedAt/archivedById stamp — use the audit log if you need to know who archived it and when.
projectIdProject this status column belongs to. Set once on create — a status cannot be moved to another project.
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.
colorHex color (#RGB or #RRGGBB, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.
orderFractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.
listIdWhen this status column is also rendered as a list, the id of that list. Null otherwise.
The related Actor, present only when you pass ?expand=createdByActor.
The related Project, present only when you pass ?expand=project.
The linked Team Member rows, present only when you pass ?expand=assignees.
The linked Role rows, present only when you pass ?expand=hiddenFor.
The related List, present only when you pass ?expand=list.
The linked Task rows, present only when you pass ?expand=tasks.
The linked Recurring Rule rows, present only when you pass ?expand=recurringRules.
Get Status
Retrieve a single Status by id.
Required scope: statuses:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Status.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Status › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
nameStatus column name (e.g. "To Do", "In Progress"). 1–100 characters after trimming.
archivedWhether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no archivedAt/archivedById stamp — use the audit log if you need to know who archived it and when.
projectIdProject this status column belongs to. Set once on create — a status cannot be moved to another project.
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.
colorHex color (#RGB or #RRGGBB, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.
orderFractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.
listIdWhen this status column is also rendered as a list, the id of that list. Null otherwise.
The related Actor, present only when you pass ?expand=createdByActor.
The related Project, present only when you pass ?expand=project.
The linked Team Member rows, present only when you pass ?expand=assignees.
The linked Role rows, present only when you pass ?expand=hiddenFor.
The related List, present only when you pass ?expand=list.
The linked Task rows, present only when you pass ?expand=tasks.
The linked Recurring Rule rows, present only when you pass ?expand=recurringRules.
Delete Status
Permanently delete this Status. This cannot be undone.
Required scope: statuses:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Status.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Status › Responses
No Content
Update Status
Partially update a Status. Only the fields you send are changed.
Required scope: statuses:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Status.
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 Status › Request Body
nameStatus column name (e.g. "To Do", "In Progress"). 1–100 characters after trimming.
color^#([0-9A-Fa-f]{3}|[0…Hex color (#RGB or #RRGGBB, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.
orderFractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.
archivedWhether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no archivedAt/archivedById stamp — use the audit log if you need to know who archived it and when.
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 Status › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
nameStatus column name (e.g. "To Do", "In Progress"). 1–100 characters after trimming.
archivedWhether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no archivedAt/archivedById stamp — use the audit log if you need to know who archived it and when.
projectIdProject this status column belongs to. Set once on create — a status cannot be moved to another project.
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.
colorHex color (#RGB or #RRGGBB, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.
orderFractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.
listIdWhen this status column is also rendered as a list, the id of that list. Null otherwise.
The related Actor, present only when you pass ?expand=createdByActor.
The related Project, present only when you pass ?expand=project.
The linked Team Member rows, present only when you pass ?expand=assignees.
The linked Role rows, present only when you pass ?expand=hiddenFor.
The related List, present only when you pass ?expand=list.
The linked Task rows, present only when you pass ?expand=tasks.
The linked Recurring Rule rows, present only when you pass ?expand=recurringRules.
Search Statuses
Full-text ranked search across statuses. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields.
Required scope: statuses:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
projectIdThe project to search within. Required — statuses are project-scoped and search has no workspace-wide mode.
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.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
archived[eq]Filter where archived equals.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId 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.
updatedAt[gt]Filter where updatedAt is greater than.
updatedAt[gte]Filter where updatedAt is greater than or equal to.
updatedAt[lt]Filter where updatedAt is less than.
updatedAt[lte]Filter where updatedAt is less than or equal to.
Search Statuses › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Add assignees to a Status
Link the given ids to this Status as assignees. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete assignees set afterwards.
Required scopes: statuses:write statuses:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Status.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add assignees to a Status › Request Body
idsTeam Members to add or remove, by id.
Add assignees to a Status › Responses
OK
The complete assignees set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove assignees from a Status
Unlink the given ids from this Status's assignees. Removing one that is not linked changes nothing. Returns the complete assignees set afterwards.
Required scopes: statuses:write statuses:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Status.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove assignees from a Status › Request Body
idsTeam Members to add or remove, by id.
Remove assignees from a Status › Responses
OK
The complete assignees set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).
Add hidden for to a Status
Link the given ids to this Status as hiddenFor. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete hiddenFor set afterwards.
Required scopes: statuses:write statuses:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Status.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add hidden for to a Status › Responses
OK
The complete hiddenFor set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove hidden for from a Status
Unlink the given ids from this Status's hiddenFor. Removing one that is not linked changes nothing. Returns the complete hiddenFor set afterwards.
Required scopes: statuses:write statuses:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Status.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove hidden for from a Status › Request Body
idsRoles to add or remove, by id.
Remove hidden for from a Status › Responses
OK
The complete hiddenFor set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).