A team-scoped conversation: a group chat, a direct message between two people, or a project's general discussion. Only group chats can be created here — a direct message is created for you when you post a message with recipientMemberId, and a project discussion is provisioned with its project. Members are set when the chat is created (memberIds) and cannot be changed afterwards. Messages live on the separate message resource — list them with GET /messages?chatId=....
List Chats
List chats. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by lastMessageAt unless you pass sort.
Required scope: chats: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: lastMessageAt.
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.
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
lastMessageAt[gt]Filter where lastMessageAt is greater than.
lastMessageAt[gte]Filter where lastMessageAt is greater than or equal to.
lastMessageAt[lt]Filter where lastMessageAt is less than.
lastMessageAt[lte]Filter where lastMessageAt is less than or equal to.
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.
recipientMemberId[eq]Filter where recipientMemberId equals.
List Chats › 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 Chat
Create a Chat. Server-assigned fields are ignored if sent.
Required scope: chats: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 Chat › Request Body
nameChat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.
descriptionOptional free-text description.
typeChat type. Create accepts ONLY a group chat: pass 'group' (the same value reads emit). Direct and project chats are readable but are not created here — post a message with recipientMemberId for a direct message; a project's discussion is provisioned with its project.
memberIdsTeam members to add to the chat, by id — you are always included as its owner. Members are set here, when the chat is created, and cannot be changed afterwards, so send the full roster now. Write-only; read the resulting membership back with ?expand=members.
Create Chat › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
typeChat type: 'group', 'direct' (a 1:1 direct message), or 'project' (a project's general discussion). Create accepts ONLY 'group'.
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.
nameChat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.
descriptionOptional free-text description.
teamIdThe workspace (team) this chat belongs to. Server-set from the caller identity — never client-writable.
projectIdSet only on a project's general-discussion chat; null on group and direct chats. Those chats are not returned by list/get today, so in practice this is always null.
pinnedMessageIdThe message currently pinned in this chat, if any. Read-only.
lastMessageAtTimestamp of the latest message (server-bumped by the message-create afterCommit hook). NULL until the first message. List default-sorts on it.
Who is in this chat. Each entry carries the member id plus whether they own the chat, whether they muted it, and when they joined. Populated only when you ask for it with ?expand=members.
The related Project, present only when you pass ?expand=project.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Get Chat
Retrieve a single Chat by id.
Required scope: chats:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Chat.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Chat › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
typeChat type: 'group', 'direct' (a 1:1 direct message), or 'project' (a project's general discussion). Create accepts ONLY 'group'.
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.
nameChat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.
descriptionOptional free-text description.
teamIdThe workspace (team) this chat belongs to. Server-set from the caller identity — never client-writable.
projectIdSet only on a project's general-discussion chat; null on group and direct chats. Those chats are not returned by list/get today, so in practice this is always null.
pinnedMessageIdThe message currently pinned in this chat, if any. Read-only.
lastMessageAtTimestamp of the latest message (server-bumped by the message-create afterCommit hook). NULL until the first message. List default-sorts on it.
Who is in this chat. Each entry carries the member id plus whether they own the chat, whether they muted it, and when they joined. Populated only when you ask for it with ?expand=members.
The related Project, present only when you pass ?expand=project.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Delete Chat
Permanently delete this Chat. This cannot be undone. Every message in the chat is deleted with it.
Required scope: chats:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Chat.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Chat › Responses
No Content
Update Chat
Partially update a Chat. Only the fields you send are changed.
Required scope: chats:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Chat.
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 Chat › Request Body
nameChat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.
descriptionOptional free-text description.
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 Chat › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
typeChat type: 'group', 'direct' (a 1:1 direct message), or 'project' (a project's general discussion). Create accepts ONLY 'group'.
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.
nameChat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.
descriptionOptional free-text description.
teamIdThe workspace (team) this chat belongs to. Server-set from the caller identity — never client-writable.
projectIdSet only on a project's general-discussion chat; null on group and direct chats. Those chats are not returned by list/get today, so in practice this is always null.
pinnedMessageIdThe message currently pinned in this chat, if any. Read-only.
lastMessageAtTimestamp of the latest message (server-bumped by the message-create afterCommit hook). NULL until the first message. List default-sorts on it.
Who is in this chat. Each entry carries the member id plus whether they own the chat, whether they muted it, and when they joined. Populated only when you ask for it with ?expand=members.
The related Project, present only when you pass ?expand=project.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Search Chats
Full-text ranked search across chats. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields.
Required scope: chats: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.
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
lastMessageAt[gt]Filter where lastMessageAt is greater than.
lastMessageAt[gte]Filter where lastMessageAt is greater than or equal to.
lastMessageAt[lt]Filter where lastMessageAt is less than.
lastMessageAt[lte]Filter where lastMessageAt is less than or equal to.
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.
recipientMemberId[eq]Filter where recipientMemberId equals.
Search Chats › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.