Developer docs

API reference for connecting the bot to your product.

Quick start

Call the bot in 3 steps.

1Create an API key
2Send a POST request
3Show the answer

curl -X POST https://api.example.com/api/v1/public/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How many days does delivery to London take?",
    "user_id": "customer-42"
  }'

Start free

Docs

Endpoint

POSThttps://api.example.com/api/v1/public/v1/chat

Authentication

Send the key in the Authorization or X-API-Key header.

Authorization: Bearer hy_live_xxxxxxxx
# or
X-API-Key: hy_live_xxxxxxxx

Request body

message	User message text
conversation_id	Continue a conversation (optional)
user_id	User ID in your system (optional)
stream	Enable streaming (optional)

{
  "message": "How many days does delivery to London take?",
  "conversation_id": "optional",
  "user_id": "customer-42",
  "stream": false
}

Response

{
  "conversation_id": "c_8f2a...",
  "message": {
    "id": "m_41d9...",
    "role": "assistant",
    "content": "Delivery to London takes 2 to 3 working days ...",
    "citations": [
      { "document_id": "d_17", "title": "Shipping policy", "url": "https://...", "snippet": "...", "score": 0.82 }
    ],
    "feedback": null,
    "created_at": "2026-01-01T10:00:00Z"
  }
}

Streaming

With stream=true the response is returned as SSE.

Rate limit

60 requests per minute per key. Check the X-RateLimit-* headers.

Error codes

401	unauthorized
403	forbidden
404	not_found
412	precondition_failed
422	validation_error
429	rate_limited