> ## Documentation Index
> Fetch the complete documentation index at: https://hadiqio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="Hadiq.io Cloud">
    ```
    https://cloud.Hadiq.io
    ```
  </Tab>

  <Tab title="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`).
  </Tab>
</Tabs>

## 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](/api-reference/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](https://github.com/Hadiq.io/releases).

## Quick-start example

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

<CodeGroup>
  ```bash curl theme={null}
  # 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 .
  ```

  ```python Python theme={null}
  import requests

  BASE_URL = "https://cloud.hadiq.io"
  HEADERS = {
      "Authorization": "Bearer hadiqk-...",
      "Content-Type": "application/json",
  }

  # 1. Create a chat session
  session_resp = requests.post(
      f"{BASE_URL}/api/chat/create-chat-session",
      headers=HEADERS,
      json={"persona_id": 0},
  )
  session_id = session_resp.json()["chat_session_id"]

  # 2. Send a message (non-streaming)
  msg_resp = requests.post(
      f"{BASE_URL}/api/chat/send-chat-message",
      headers=HEADERS,
      json={
          "chat_session_id": session_id,
          "message": "What is our vacation policy?",
          "stream": False,
      },
  )
  print(msg_resp.json())
  ```
</CodeGroup>

## Error responses

All errors use a standard JSON shape:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Create an API key and learn how to use it in requests.
  </Card>

  <Card title="Chat" icon="message" href="/api-reference/chat">
    Send messages, manage sessions, and stream responses.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/api-reference/search">
    Run semantic search across your connected knowledge base.
  </Card>

  <Card title="Document ingestion" icon="file-arrow-up" href="/api-reference/ingestion">
    Push documents directly into the index without a connector.
  </Card>
</CardGroup>