# List chats

`GET https://stylor.ai/api/v1/chat/list`

- Authentication: private API key, sent as `Authorization: Bearer sgpt-sk-…::…`
- Rate-limit resource: `api.v1.chat.list`
- Demo key: not accepted
- Deprecated: yes
- Web page: https://stylor.ai/guides/rest/v1/list-chats

> **Retired.** This endpoint answers `410 Gone` and no longer works.
> It is documented for reference only; use the v2 agent API's
> [Chat](https://stylor.ai/guides/rest/v2/agent-chat.md) instead.

Page through the organization's chats, newest activity first by
default. Each row is a lightweight summary (id, message count,
timestamps); fetch a single chat with **Retrieve a chat** to read its
messages.

Pagination is offset-based: pass `skip` and `limit`, and stop when
`pagination.hasMore` is `false`.

## Example request

```bash
curl -X GET "https://stylor.ai/api/v1/chat/list" \
  -H "Authorization: Bearer $STYLOR_API_KEY"
```

## Query parameters

- `limit` (integer): Number of chats to return. Values below 1 or non-numeric values fall back to 20; values above 100 are clamped to 100. [default `20`; minimum 1; maximum 100]
- `skip` (integer): Number of chats to skip before the first returned row. Negative or non-numeric values are treated as 0. [default `0`; minimum 0]
- `sortBy` (string): Field to sort on. Any other value silently falls back to `updatedAt`. [default `"updatedAt"`; one of `"updatedAt"`, `"createdAt"`, `"chatId"`]
- `sortOrder` (string): Sort direction. Anything other than `asc` is treated as `desc`. [default `"desc"`; one of `"asc"`, `"desc"`]

## Responses

### 200

One page of chat summaries.

Content type `application/json`:

- `chats` (array<ChatSummary>, required): The page of chat summaries.
  - `chatId` (string (uuid), required): Unique id of the chat. [example `"3f0c2a4e-8b1d-4c6a-9e2f-7a5b1c0d9e88"`]
  - `messagesCount` (integer, required): Number of messages in the thread. [example `4`]
  - `messageCount` (integer, required): Same value as `messagesCount`, kept for compatibility. [example `4`]
  - `createdAt` (string (date-time), required): When the chat was created. [example `"2026-09-12T14:03:11.412Z"`]
  - `updatedAt` (string (date-time), required): When the chat was last written to. [example `"2026-09-12T14:09:48.907Z"`]
- `pagination` (ChatListPagination, required): Offset-based page metadata used by List chats.
  - `total` (integer, required): Total number of chats in the organization. [example `137`]
  - `limit` (integer, required): Page size that was applied after clamping. [example `20`]
  - `skip` (integer, required): Offset that was applied. [example `0`]
  - `hasMore` (boolean, required): Whether `skip + limit` is still below `total`. [example `true`]

Example:

```json
{
  "chats": [
    {
      "chatId": "3f0c2a4e-8b1d-4c6a-9e2f-7a5b1c0d9e88",
      "messagesCount": 4,
      "messageCount": 4,
      "createdAt": "2026-09-12T14:03:11.412Z",
      "updatedAt": "2026-09-12T14:09:48.907Z"
    },
    {
      "chatId": "c2b7e1a9-5d3f-4e8b-a6c0-1f2d3e4a5b6c",
      "messagesCount": 2,
      "messageCount": 2,
      "createdAt": "2026-09-11T09:21:05.118Z",
      "updatedAt": "2026-09-11T09:21:37.552Z"
    }
  ],
  "pagination": {
    "total": 137,
    "limit": 20,
    "skip": 0,
    "hasMore": true
  }
}
```

## Errors

Every error is a JSON object with an `error` string. Match on the status code; the message is written for people.

| Status | Message | When |
| --- | --- | --- |
| 410 | This endpoint has been retired (v1/chat/list). | Always, for API callers. This check runs before authentication and consumes no quota. |

### Shared authentication, quota and rate-limit errors

| Status | Message | When |
| --- | --- | --- |
| 401 | API key missing. | The `Authorization` header is absent, is not `Bearer <key>`, or the key does not have three dash-separated segments. |
| 401 | Authentication failed: public key is invalid or not recognized. | A public-key endpoint was called with a key that does not exist. |
| 401 | Authentication failed: private key provided instead of a public key. | A public-key endpoint was called with an `sgpt-sk-…` key. |
| 401 | Authentication failed: token is not recognized. | A private-key endpoint was called with a key whose lookup segment does not exist. |
| 401 | Authentication failed: private key is invalid. | A private-key endpoint was called with a key whose secret does not match. |
| 401 | Authentication failed: public key provided instead of a private key. | A private-key endpoint was called with an `sgpt-pk-…` key. |
| 401 | Authentication failed: bearer token format is invalid. | A private key was sent without its `::` lookup segment. |
| 401 | Authentication failed: API key could not be read. Regenerate the key. | The key's embedded organization data could not be decrypted or parsed. |
| 403 | Demo mode is not available for private-key routes. Demos are only supported with public API keys. | The demo key was sent to a private-key endpoint. |
| 403 | Demo mode is not supported on this API route. Check the documentation for available demo endpoints. | The demo key was sent to a public-key endpoint that opts out of demo mode. |
| 403 | No active subscription for this organization. | The organization that owns the key has no active subscription. |
| 403 | No quota found for organization "<organizationId>". | The organization has no quota record for the current billing period. |
| 403 | No entitlement for "<resource>". | The plan's quota template has no entry for this endpoint. |
| 403 | Access denied to "<resource>". | The plan's quota template turns this endpoint off. |
| 429 | Monthly quota exceeded for "<resource>" (<quota>/<quota> used). | The billing-period quota for this endpoint is exhausted. `Retry-After` gives the seconds until the period resets. |
| 429 | RPM limit exceeded for "<resource>" (<used>/<limit> used). | More than the allowed requests per minute were sent. `Retry-After` is 60. |
| 500 | Internal server error. | An unexpected failure on the server. The message is always this string; details are logged, never returned. Quota consumed by the request is refunded, as it is for every 5xx response. |