Introduction - homie Documentation

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.

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.

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.

curl https://api.yourhomie.ai/v1/chats \
  -H "x-api-key: homie_sk_live_8f3a..." \
  -H "Content-Type: application/json"

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.

The chat flow

A typical integration follows three steps:

Create a chat

Call Create Chat with your chatbotId. You receive a chatId that identifies the conversation.

Add a message

Call Add Message with the chatId, the user’s message, and the currentUrl. The assistant starts generating a response.

Listen to events

Open the Message Events stream for the chatId to receive the assistant’s reply and tool activity in real time over Server-Sent Events.

Error format

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

{
  "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.

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.

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:

{
  "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

Create Chat

Start a new conversation for a chatbot.

Get Chat

Retrieve a chat by its ID.

Add Message

Send a user message to the assistant.

List Messages

Page through a chat’s message history.

Message Events

Stream assistant responses over SSE.

PDP Question Set

Fetch public product questions for a page.

​Authentication

​The chat flow

​Error format

​Pagination

​Identifiers

​Endpoints

Create Chat

Get Chat

Add Message

List Messages

Message Events

PDP Question Set

Authentication

The chat flow

Error format

Pagination

Identifiers

Endpoints