Presence Status
A reusable status a member can switch on — "In a meeting", "Focus time", "Out of office". Templates are shared across the workspace.
Nifty seeds a starter set the first time someone opens the status picker in the app, so a workspace where nobody has done that returns an empty list even though the app will show six.
List Presence Statuses
List presenceStatuses. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by createdAt unless you pass sort.
Required scope: presence-statuses: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.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
isDefault[eq]Filter where isDefault equals.
appearsOnline[eq]Filter where appearsOnline equals.
List Presence 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 Presence Status
Create a Presence Status. Server-assigned fields are ignored if sent.
Required scope: presence-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 Presence Status › Request Body
nameName of the status, shown to the team.
appearsOnlineWhether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.
emojiA single emoji shown beside the status.
muteNotificationsWhether the member's notifications are silenced while this status is active.
defaultDurationMsHow long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.
Create Presence Status › Responses
Created
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameName of the status, shown to the team.
appearsOnlineWhether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.
muteNotificationsWhether the member's notifications are silenced while this status is active.
isDefaultTrue for the templates Nifty seeds into every workspace. Server-managed: you cannot promote or demote a template through the API.
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.
emojiA single emoji shown beside the status.
defaultDurationMsHow long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.
The related Actor, present only when you pass ?expand=createdByActor.
Get Presence Status
Retrieve a single Presence Status by id.
Required scope: presence-statuses:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Presence Status.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Presence Status › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameName of the status, shown to the team.
appearsOnlineWhether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.
muteNotificationsWhether the member's notifications are silenced while this status is active.
isDefaultTrue for the templates Nifty seeds into every workspace. Server-managed: you cannot promote or demote a template through the API.
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.
emojiA single emoji shown beside the status.
defaultDurationMsHow long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.
The related Actor, present only when you pass ?expand=createdByActor.
Delete Presence Status
Permanently delete this Presence Status. This cannot be undone.
Required scope: presence-statuses:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Presence Status.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Presence Status › Responses
No Content
Update Presence Status
Partially update a Presence Status. Only the fields you send are changed.
Required scope: presence-statuses:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Presence 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 Presence Status › Request Body
nameName of the status, shown to the team.
appearsOnlineWhether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.
emojiA single emoji shown beside the status.
muteNotificationsWhether the member's notifications are silenced while this status is active.
defaultDurationMsHow long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.
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 Presence Status › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameName of the status, shown to the team.
appearsOnlineWhether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.
muteNotificationsWhether the member's notifications are silenced while this status is active.
isDefaultTrue for the templates Nifty seeds into every workspace. Server-managed: you cannot promote or demote a template through the API.
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.
emojiA single emoji shown beside the status.
defaultDurationMsHow long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.
The related Actor, present only when you pass ?expand=createdByActor.
Search Presence Statuses
Full-text ranked search across presenceStatuses. Ranked by relevance; pages are capped at 200 results. Filterable by 3 fields.
Required scope: presence-statuses: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.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
isDefault[eq]Filter where isDefault equals.
appearsOnline[eq]Filter where appearsOnline equals.
Search Presence 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.