> ## 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.

# Introduction

> Authenticate, create a chat, send messages, and stream responses with the homie REST API.

The homie REST API lets you create chats, send messages to an assistant, and receive responses programmatically. Use it when you want to build a custom integration instead of the embeddable widget.

<Note>
  **API access is available on Enterprise plans only.** API keys are created and issued by homie — you cannot generate them yourself. Contact your homie account team to request access.
</Note>

## Authentication

Every request must include your API key in the `x-api-key` header. Keys are issued to your organization by homie — keep them secret and use them only from server-side code.

```bash theme={null}
curl https://api.yourhomie.ai/v1/chats \
  -H "x-api-key: homie_sk_live_8f3a..." \
  -H "Content-Type: application/json"
```

<Warning>
  Keep your API key secret. It grants access to your organization's data, so use it only from server-side code and never expose it in a browser or mobile app.
</Warning>

## The chat flow

A typical integration follows three steps:

<Steps>
  <Step title="Create a chat">
    Call [Create Chat](/en/api-reference/backend/chats/create-chat) with your `chatbotId`. You receive a `chatId` that identifies the conversation.
  </Step>

  <Step title="Add a message">
    Call [Add Message](/en/api-reference/backend/messages/send-message) with the `chatId`, the user's `message`, and the `currentUrl`. The assistant starts generating a response.
  </Step>

  <Step title="Listen to events">
    Open the [Message Events](/en/api-reference/backend/messages/message-events) stream for the `chatId` to receive the assistant's reply and tool activity in real time over Server-Sent Events.
  </Step>
</Steps>

## Error format

Errors return a non-2xx HTTP status and a JSON body with a `message` describing what went wrong:

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

Common status codes:

| Status | Meaning                                 |
| ------ | --------------------------------------- |
| `401`  | Missing or invalid API key.             |
| `404`  | The requested resource does not exist.  |
| `422`  | The request body failed validation.     |
| `429`  | Your plan's message quota is exhausted. |

<Info>
  API usage counts toward your plan's monthly message quota. When the quota is reached, message endpoints return an error until it resets or your plan is upgraded. Monitor consumption under **Usage** on the platform.
</Info>

## Pagination

List endpoints return a paginated envelope. The `items` array holds the results for the current page, and the remaining fields describe the overall set:

```json theme={null}
{
  "items": [],
  "totalItems": 42,
  "size": 20,
  "totalPages": 3,
  "currentPage": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}
```

`prevPage` and `nextPage` are `null` when there is no previous or next page.

## Identifiers

All resource IDs (`chatId`, `chatbotId`, `userId`, `organizationId`) are unique string identifiers, for example `5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f`.

## Endpoints

<CardGroup cols={2}>
  <Card title="Create Chat" icon="plus" href="/en/api-reference/backend/chats/create-chat">
    Start a new conversation for a chatbot.
  </Card>

  <Card title="Get Chat" icon="magnifying-glass" href="/en/api-reference/backend/chats/get-chat">
    Retrieve a chat by its ID.
  </Card>

  <Card title="Add Message" icon="paper-plane" href="/en/api-reference/backend/messages/send-message">
    Send a user message to the assistant.
  </Card>

  <Card title="List Messages" icon="list" href="/en/api-reference/backend/messages/list-messages">
    Page through a chat's message history.
  </Card>

  <Card title="Message Events" icon="bolt" href="/en/api-reference/backend/messages/message-events">
    Stream assistant responses over SSE.
  </Card>

  <Card title="PDP Question Set" icon="circle-question" href="/en/api-reference/backend/pdp-questions/get-pdp-questions">
    Fetch public product questions for a page.
  </Card>
</CardGroup>