--- title: "Chats" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://openemail.uk/docs/api/reference/chats" area: "API" category: "Reference" --- # Chats Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations The conversations held with the assistant in the app, as the Chats page lists them. Only the workspace owner reaches the chats: an API key, or an app the owner connected with every address. An access token acting for a member is a 403 `owner_only`, and a key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. ### `GET /chats` List the assistant chats The chats of the workspace, newest first, a page at a time, each with its title, how many messages it holds and when it last changed. `q` searches the titles and `sort` orders them. Only the workspace owner reaches the chats: an API key, or an app the owner connected with every address. An access token acting for a member is a 403 `owner_only`, and a key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:read` scope. - Scopes: `threads:read`. **Query parameters** - `q` (`string`, up to 200 characters): Search the titles. - `sort` (`string`, one of `"newest"`, `"oldest"`, `"title"`, default `"newest"`): `newest` and `oldest` order by the last change, and `title` alphabetically. - `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100. - `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`. **Returns** - `200` `ChatList`: A page of chats. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`chats.list()`](https://openemail.uk/docs/sdk/reference/chats#list), [`chats.listAll()`](https://openemail.uk/docs/sdk/reference/chats#listAll), [`chats.iterate()`](https://openemail.uk/docs/sdk/reference/chats#iterate); CLI [`openemail chats list`](https://openemail.uk/docs/cli/reference/chats#chats-list); MCP [`listChats`](https://openemail.uk/docs/mcp/tools/chats#listChats). ### `GET /chats/{id}` Retrieve a chat One chat by id. Only the workspace owner reaches the chats: an API key, or an app the owner connected with every address. An access token acting for a member is a 403 `owner_only`, and a key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): The chat id from `GET /chats`. **Returns** - `200` `Chat`: The chat. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`chats.get()`](https://openemail.uk/docs/sdk/reference/chats#get); CLI [`openemail chats get`](https://openemail.uk/docs/cli/reference/chats#chats-get); MCP [`getChat`](https://openemail.uk/docs/mcp/tools/chats#getChat). ### `PATCH /chats/{id}` Rename a chat Gives the chat a new title. Only the workspace owner reaches the chats: an API key, or an app the owner connected with every address. An access token acting for a member is a 403 `owner_only`, and a key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The chat id from `GET /chats`. **Request body** - `title` (`string`, required, 1 to 120 characters) **Returns** - `200` `Chat`: The chat with its new title. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`chats.rename()`](https://openemail.uk/docs/sdk/reference/chats#rename); CLI [`openemail chats rename`](https://openemail.uk/docs/cli/reference/chats#chats-rename); MCP [`renameChat`](https://openemail.uk/docs/mcp/tools/chats#renameChat). ### `DELETE /chats/{id}` Delete a chat Deletes the chat and every message in it, for good. Nothing it did in the mailbox is undone. Only the workspace owner reaches the chats: an API key, or an app the owner connected with every address. An access token acting for a member is a 403 `owner_only`, and a key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The chat id from `GET /chats`. **Returns** - `200` `DeletedChat`: Deleted. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`chats.delete()`](https://openemail.uk/docs/sdk/reference/chats#delete); CLI [`openemail chats delete`](https://openemail.uk/docs/cli/reference/chats#chats-delete); MCP [`deleteChat`](https://openemail.uk/docs/mcp/tools/chats#deleteChat). ### Objects #### `Chat` `object` - `object` (`string`, required, one of `"chat"`) - `id` (`string`, required) - `title` (`string`, required) - `kind` (`string`, required, one of `"chat"`) - `messageCount` (`integer`, required, at least 0) - `updatedAt` (`string`, required, format `date-time`): When a message last arrived in it. #### `ChatList` `object` - `object` (`string`, one of `"list"`) - `data` (`Chat[]`) - `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it. - `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged. #### `DeletedChat` `object` - `object` (`string`, one of `"chat"`) - `id` (`string`) - `deleted` (`boolean`, one of `true`)