> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourhomie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Messages

> Page through the message history of a chat.

Retrieve the messages of a chat as a paginated list, ordered as a conversation history.

## Authentication

This request requires your API key in the `x-api-key` header.

## Request

<ParamField path="chatId" type="string" required>
  ID of the chat whose messages you want to list.
</ParamField>

## Response

<ResponseField name="items" type="object[]" required>
  The messages on the current page.

  <Expandable title="MessageDto">
    <ResponseField name="id" type="string" required>
      ID of the message.
    </ResponseField>

    <ResponseField name="chatId" type="string" required>
      ID of the chat the message belongs to.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The message type.
    </ResponseField>

    <ResponseField name="content" type="string" required>
      The message text content.
    </ResponseField>

    <ResponseField name="suggestions" type="string[]">
      Optional list of suggested follow-up questions.
    </ResponseField>

    <ResponseField name="products" type="object[]">
      Optional list of recommended products. See [Add Message](/en/api-reference/backend/messages/send-message) for the full product shape.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of when the message was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalItems" type="number" required>
  Total number of messages across all pages.
</ResponseField>

<ResponseField name="size" type="number" required>
  Number of items per page.
</ResponseField>

<ResponseField name="totalPages" type="number" required>
  Total number of pages.
</ResponseField>

<ResponseField name="currentPage" type="number" required>
  The current page number.
</ResponseField>

<ResponseField name="hasPrevPage" type="boolean" required>
  Whether a previous page exists.
</ResponseField>

<ResponseField name="hasNextPage" type="boolean" required>
  Whether a next page exists.
</ResponseField>

<ResponseField name="prevPage" type="number">
  The previous page number, or `null` if there is none.
</ResponseField>

<ResponseField name="nextPage" type="number">
  The next page number, or `null` if there is none.
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.yourhomie.ai/v1/chats/ab12cd34-ef56-7890-ab12-cd34ef567890/messages \
    -H "x-api-key: homie_sk_live_8f3a..."
  ```

  ```javascript JavaScript (fetch) theme={null}
  const chatId = "ab12cd34-ef56-7890-ab12-cd34ef567890";

  const res = await fetch(
    `https://api.yourhomie.ai/v1/chats/${chatId}/messages`,
    {
      headers: {
        "x-api-key": "homie_sk_live_8f3a...",
      },
    },
  );

  const page = await res.json();
  ```
</CodeGroup>

### Success response

```json theme={null}
{
  "items": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "chatId": "ab12cd34-ef56-7890-ab12-cd34ef567890",
      "type": "user",
      "content": "Do you have a waterproof jacket in blue?",
      "createdAt": "2025-10-16T11:45:01.001Z"
    },
    {
      "id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f2a3b4c5d",
      "chatId": "ab12cd34-ef56-7890-ab12-cd34ef567890",
      "type": "assistant",
      "content": "Yes, here is a waterproof jacket available in blue.",
      "createdAt": "2025-10-16T11:45:02.512Z"
    }
  ],
  "totalItems": 2,
  "size": 20,
  "totalPages": 1,
  "currentPage": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}
```

### Error response

```json theme={null}
{
  "message": "Chat not found"
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /v1/chats/{chatId}/messages
openapi: 3.0.0
info:
  title: homie AI API
  description: The homie AI API description
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.yourhomie.ai
    description: Production server
security: []
tags:
  - name: Chat
    description: ''
  - name: Knowledge
    description: Public, CORS-enabled endpoints for PDP question sets
paths:
  /v1/chats/{chatId}/messages:
    get:
      tags:
        - Chat
      summary: List all Chat Messages
      operationId: ChatController_getChatMessages
      parameters:
        - name: chatId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/MessageDto'
                      totalItems:
                        type: number
                      size:
                        type: number
                      totalPages:
                        type: number
                      currentPage:
                        type: number
                      hasPrevPage:
                        type: boolean
                      hasNextPage:
                        type: boolean
                      prevPage:
                        type: number
                        nullable: true
                      nextPage:
                        type: number
                        nullable: true
                    required:
                      - items
                      - totalItems
                      - size
                      - totalPages
                      - currentPage
                      - hasPrevPage
                      - hasNextPage
      security:
        - bearer: []
components:
  schemas:
    MessageDto:
      type: object
      properties:
        id:
          type: string
        chatId:
          type: string
        type:
          type: string
        content:
          type: string
        suggestions:
          type: array
          items:
            type: string
        products:
          type: array
          items:
            $ref: '#/components/schemas/MessageProductDto'
        createdAt:
          type: string
      required:
        - id
        - chatId
        - type
        - content
        - createdAt
    MessageProductDto:
      type: object
      properties:
        gtin:
          type: string
        brand:
          type: string
        designation:
          type: string
        url:
          type: string
          format: uri
        image:
          type: string
          format: uri
        price:
          type: number
        priceInfo:
          type: string
        currency:
          type: string
        location:
          type: array
          items:
            $ref: '#/components/schemas/MessageProductLocationDto'
        availability:
          $ref: '#/components/schemas/MessageAvailabilityDto'
        category:
          type: string
        query:
          type: string
        description:
          type: string
        recommendationText:
          type: string
        flags:
          type: array
          items:
            $ref: '#/components/schemas/ProductFlags'
      required:
        - gtin
        - brand
        - designation
        - url
        - image
        - price
        - currency
    MessageProductLocationDto:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
    MessageAvailabilityDto:
      type: object
      properties:
        status:
          type: string
        quantity:
          type: number
      required:
        - status
        - quantity
    ProductFlags:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        text:
          type: string
      required:
        - type
        - title
        - text
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````