> ## Documentation Index > Fetch the complete documentation index at: https://docs.blujay.io/llms.txt > Use this file to discover all available pages before exploring further. # List chats > Returns the chats in your workspace, one page at a time. Pass `next_cursor` from the previous page as `cursor` to get the next page. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/chats openapi: 3.1.0 info: title: Blujay API version: 1.0.0 description: >- The Blujay API lets you send and receive iMessage, RCS and SMS messages from your Blujay phone numbers, manage contacts, and receive real-time webhooks. Every response uses the same JSON envelope and carries a `trace_id` you can share with support. Authenticate with your workspace API key. servers: - url: https://api.blujay.io description: Production security: - PublicApiKey: [] tags: - name: Auth description: Check which workspace and credential a request is using. - name: Chats description: >- Direct and group conversations between your Blujay numbers and your contacts. - name: Messages description: Send, read, edit, unsend and retry messages. - name: Phone Numbers description: >- Your Blujay numbers, whether each can send right now, and their live sending limits. - name: Capability description: >- Check whether a phone number can be reached by iMessage, RCS or SMS before you send. - name: Contacts description: Create, find, update, tag, assign and opt out contacts. - name: vCards description: >- Saved contact cards that you can send in a message. Recipients get a native contact card over iMessage, SMS or RCS. - name: Team Members description: People in your workspace you can assign contacts to. - name: Workflows description: Enroll contacts in workflows you start manually. - name: Attachments description: >- Upload files once and reuse them in messages, or download files from messages. - name: Webhooks description: Subscribe to events, inspect delivery attempts and verify signatures. paths: /v1/chats: get: tags: - Chats summary: List chats description: >- Returns the chats in your workspace, one page at a time. Pass `next_cursor` from the previous page as `cursor` to get the next page. operationId: listPublicChats parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of chats. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/PublicChatList' examples: chats: summary: A direct chat and a group chat value: status: success data: data: - chat_id: chat_abc123 type: direct display_name: Ava Chen participants: - type: phone address: '+15555550123' contact_id: contact_abc123 display_name: Ava Chen phone_number_id: phone_abc123 service: iMessage supports_typing_indicators: true created_at: '2026-10-14T17:01:00.000Z' updated_at: '2026-10-14T17:06:12.000Z' - chat_id: chat_def456 type: group display_name: Order 4821 support participants: - type: phone handle: '+15555550123' address: '+15555550123' status: active joined_at: '2026-10-14T15:20:00.000Z' left_at: null contact_id: contact_abc123 display_name: Ava Chen - type: phone handle: '+15555550124' address: '+15555550124' status: active joined_at: '2026-10-14T15:20:00.000Z' left_at: null contact_id: contact_def456 display_name: Jordan Lee supports_typing_indicators: true phone_numbers: - phone_number_id: phone_abc123 display_number: '+15555550100' label: Support status: active is_default: true can_send: true sendability_reasons: [] created_at: '2026-10-14T15:20:00.000Z' updated_at: '2026-10-14T16:42:08.000Z' next_cursor: AbC9xQ2nRk7vT1mZ has_more: true limit: 25 trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T17:10:00.000Z' security: - PublicApiKey: [] components: parameters: Limit: name: limit in: query description: Maximum number of items to return. schema: type: integer minimum: 1 maximum: 100 default: 25 Cursor: name: cursor in: query description: >- The `next_cursor` value from the previous page. Leave it out to get the first page. schema: type: string headers: XTraceID: description: >- Unique ID for this request. It matches `trace_id` in the body. Include it when you contact Blujay support. schema: $ref: '#/components/schemas/TraceId' schemas: SuccessEnvelope: type: object description: Wraps every successful response. The result is in `data`. required: - status - trace_id - timestamp properties: status: type: string enum: - success trace_id: $ref: '#/components/schemas/TraceId' timestamp: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time client_request_id: type: string description: >- Your `X-Request-ID` header value, echoed back when you send one. Not included on the send responses (`POST /v1/chats`, `POST /v1/chats/{chat_id}/messages`, `POST /v1/messages/{message_id}/retry`); keep your own mapping from your request ID to the returned message ID there. PublicChatList: type: object required: - data - has_more - limit properties: data: type: array items: $ref: '#/components/schemas/PublicChat' next_cursor: type: string examples: - AbC9xQ2nRk7vT1mZ has_more: type: boolean limit: type: integer examples: - 25 TraceId: type: string examples: - trc_8f2a1c0e4b7d pattern: ^trc_[A-Za-z0-9_-]+$ PublicChat: type: object required: - chat_id - type - participants - created_at - updated_at properties: chat_id: $ref: '#/components/schemas/ChatId' type: type: string enum: - direct - group display_name: type: string examples: - Ava Chen description: >- The chat's name, when known. For group chats, this is the group name. phone_number_id: allOf: - $ref: '#/components/schemas/PhoneNumberId' description: >- The Blujay number this direct chat uses. Omitted for group chats, which list your numbers in `phone_numbers`. service: type: - string - 'null' enum: - iMessage - RCS - SMS - null description: >- For a direct chat, the confirmed service, or null when it isn't known yet. For a group chat, the service the group runs on (`iMessage` or `SMS`), or null when it isn't known. supports_typing_indicators: type: boolean description: >- Whether a typing indicator can appear for the other person. For a direct chat, true only when the chat is confirmed as iMessage. For a group chat, true only for an active iMessage group that the chat's number is still in. When false, you can still call the typing endpoints; they just show nothing. participants: type: array items: type: object additionalProperties: true phone_numbers: type: array description: >- Your Blujay phone numbers in this group (group chats only), not the participants. The default number comes first. Omitted for direct chats. items: $ref: '#/components/schemas/PublicGroupPhoneNumber' created_at: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time updated_at: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time ChatId: type: string examples: - chat_abc123 pattern: ^chat_[A-Za-z0-9_-]+$ PhoneNumberId: type: string examples: - phone_abc123 pattern: ^phone_[A-Za-z0-9_-]+$ PublicGroupPhoneNumber: type: object additionalProperties: false required: - phone_number_id - display_number - status - is_default - can_send - sendability_reasons properties: phone_number_id: $ref: '#/components/schemas/PhoneNumberId' display_number: type: string examples: - '+15555550100' label: type: string examples: - Support line status: type: string examples: - active description: >- The number's membership status in this group. Only numbers still in the group are listed, so this is `active`. is_default: type: boolean description: Whether Blujay sends from this number in this group by default. can_send: type: boolean description: Whether this number can send in this group right now. sendability_reasons: type: array description: > Codes explaining why `can_send` is false. Empty when the number can send. - `number_inactive`: the phone number isn't active. - `number_setup_incomplete`: the phone number isn't set up for messaging yet. - `group_not_ready`: Blujay can't send to this group from this phone number yet. items: type: string enum: - number_inactive - number_setup_incomplete - group_not_ready securitySchemes: PublicApiKey: type: http scheme: bearer bearerFormat: blu_... description: > Your workspace API key, sent as `Authorization: Bearer blu_...`. Workspace admins can find it in the Blujay app under **API**. An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server. Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get `429 RATE_LIMIT_EXCEEDED` with `Retry-After`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.