• Add x-api-key: <your key> to every
request.
• All identifiers (chatId, chatbotId,
messageId, userId, organizationId) are
UUID‑v4 strings.
Environments
| Environment | Base URL | Use case |
|---|
| Staging | https://staging.api.yourhomie.ai | Build & test integrations |
| Production | https://api.yourhomie.ai | Live traffic |
3‑Step Flow
| Step | Endpoint | Purpose |
|---|
| 1 • Create chat | POST /v1/chats | Start a new conversation; returns its chatId. Pass your chatbotId in the body. |
| 2 • Add message | POST /v1/chats/{chatId}/messages | Send user text, receive Homie’s reply (incl. product objects, flags, etc.). |
| 3 • Listen / fetch | GET /v1/chats/{chatId}/events | (Optional) Stream events in real time or poll. |
1. Create a chat
curl -X POST https://staging.api.yourhomie.ai/v1/chats \
-H "x-api-key: $HOMIE_STAGING_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatbotId": "5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f",
"userId": "1bd2e7c4-8a90-4b17-9f36-6e2b5d8f7a3e"
}'
{
"id": "ab12cd34-ef56-7890-ab12-cd34ef567890",
"chatbotId": "5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f",
"userId": "1bd2e7c4-8a90-4b17-9f36-6e2b5d8f7a3e",
"organizationId": "3210cba9-8fed-7c65-4b32-1a0f9e8d7c6b",
"createdAt": "2025-07-08T16:32:11Z",
}
id — you’ll need it for every follow‑up call.
2. Send the first message
curl -X POST https://staging.api.yourhomie.ai/v1/chats/ab12cd34-ef56-7890-ab12-cd34ef567890/messages \
-H "x-api-key: $HOMIE_STAGING_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Does the blue hoodie come in size L?",
"currentUrl": "https://store.com/products/blue-hoodie"
}'
{
"id": "f1e2d3c4-b5a6-7890-b1c2-d3e4f5a6b7c8",
"chatId": "ab12cd34-ef56-7890-ab12-cd34ef567890",
"type": "answer",
"content": "Yes! Size L is in stock…",
"products": [
{
"gtin": "1234567890123",
"brand": "Homie",
"designation": "Blue Hoodie",
"uri": "https://store.com/products/blue-hoodie",
"image": "https://store.com/images/blue-hoodie.png",
"price": 59.99,
"currency": "EUR",
"availability": { "status": "in_stock", "quantity": 12 },
},
],
"createdAt": "2025-07-08T16:32:15Z",
}
3. Listen for events (optional)
curl https://staging.api.yourhomie.ai/v1/chats/ab12cd34-ef56-7890-ab12-cd34ef567890/events \
-H "x-api-key: $HOMIE_STAGING_KEY"
text/event-stream) with message chunks and typing indicators.
Ready to go live? Swap the base URL for https://api.yourhomie.ai and use your production key.
