API Overview

Base URLs, authentication, common headers, and a quick-start example for the Hadiq.io API.

The Hadiq.io API gives you programmatic access to chat sessions, search, connectors, agents, and document ingestion. All endpoints accept and return JSON unless noted otherwise.

Base URLs

Hadiq.io Cloud

https://cloud.Hadiq.io

Self-hosted

https://<your-Hadiq.io-domain>

Replace <your-Hadiq.io-domain> with the domain where you deployed Onyx (for example, Hadiq.io.example.com).

API prefix

Every endpoint is served under the /api path prefix. For example, the chat session endpoint is:

POST https://cloud.Hadiq.io/api/chat/create-chat-session

Authentication

All requests must include an Authorization header with a Bearer token:

Authorization: Bearer <your-api-key>

See Authentication for instructions on creating API keys.

Common headers

Header	Required	Description
Authorization	Yes	Bearer <api-key>
Content-Type	Yes (for request bodies)	application/json

Rate limiting

Rate limits depend on your deployment. On Hadiq.io Cloud, limits are enforced per API key. When a limit is exceeded the server returns 429 Too Many Requests. Hadiq.io also enforces token-based rate limits — if the LLM token budget for a user or group is exhausted, the API returns 429.

Self-hosted deployments inherit whatever limits you configure in your environment.

Versioning

The Hadiq.io API does not currently use a versioning prefix in the URL. Breaking changes are announced in the changelog.

Quick-start example

The following example creates a chat session and sends a message, then reads back the response.

curl

# 1. Create a chat session
curl -s -X POST https://cloud.hadiq.io/api/chat/create-chat-session \
  -H "Authorization: Bearer hadiqk-..." \
  -H "Content-Type: application/json" \
  -d '{"persona_id": 0}' \
  | jq .

# 2. Send a message (non-streaming)
curl -s -X POST https://cloud.hadiq.io/api/chat/send-chat-message \
  -H "Authorization: Bearer hadiqk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "chat_session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "message": "What is our vacation policy?",
    "stream": false
  }' \
  | jq .

Error responses

All errors use a standard JSON shape:

{
  "error_code": "NOT_FOUND",
  "detail": "Chat session not found"
}

Status	Meaning
400	Bad request — invalid input
401	Unauthenticated — missing or invalid API key
403	Forbidden — insufficient permissions
404	Resource not found
422	Validation error — malformed request body
429	Rate limited
500	Internal server error

Next steps

Authentication

Create an API key and learn how to use it in requests.

Chat

Send messages, manage sessions, and stream responses.

Search

Run semantic search across your connected knowledge base.

Document ingestion

Push documents directly into the index without a connector.