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

# MITHUNAI HTTP API: base URL and rules

> The base URL, the versioning policy, the request and response conventions and the content types of the MITHUNAI HTTP API, and what every endpoint has in common.

The MITHUNAI API gives your software everything the console can do: conversations and streaming answers, assistants, knowledge, widget embeds, analytics and branding.

## The resources

| Resource               | What it holds                                                        | Start at                                                                                                                                                                            |
| ---------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conversations**      | Questions, grounded answers and the citations behind them            | [Start a conversation](/api-reference/conversations/create-conversation), then [send a message](/api-reference/conversations/send-message)                                          |
| **Assistants**         | What answers, and the knowledge, model and guidance it uses          | [Create an assistant](/api-reference/assistants/create-assistant), [list assistants](/api-reference/assistants/list-assistants)                                                     |
| **Models**             | The models and providers this deployment can reach                   | [List models](/api-reference/models/list-models), [list providers](/api-reference/models/list-providers)                                                                            |
| **Knowledge**          | Collections, the sources that fill them, and the resulting documents | [Create a collection](/api-reference/knowledge/create-collection), [create a source](/api-reference/knowledge/create-source), [list sources](/api-reference/knowledge/list-sources) |
| **Ingestion jobs**     | The background runs that read a source into a collection             | [List jobs](/api-reference/knowledge/list-jobs), [get a job](/api-reference/knowledge/get-job)                                                                                      |
| **Widget deployments** | Embeds that put an assistant on your own site                        | [Create a widget deployment](/api-reference/widget-deployments/create-widget-deployment)                                                                                            |
| **Widget (public)**    | What the embedded widget itself calls, from the browser              | [Bootstrap the widget](/api-reference/widget/bootstrap), [start a thread](/api-reference/widget/start-thread)                                                                       |
| **MCP**                | One JSON-RPC endpoint and three read-only tools                      | [MCP endpoint](/api-reference/mcp/mcp)                                                                                                                                              |
| **API keys**           | The credentials your integrations authenticate with                  | [Create an API key](/api-reference/api-keys/create-api-key), [revoke one](/api-reference/api-keys/revoke-api-key)                                                                   |
| **Analytics**          | Usage counts and the questions that were declined                    | [Get usage](/api-reference/analytics/get-usage), [list unanswered](/api-reference/analytics/list-unanswered)                                                                        |
| **Branding**           | Your organisation's brand overrides                                  | [Get branding](/api-reference/branding/get-branding), [replace it](/api-reference/branding/replace-branding)                                                                        |
| **Support access**     | Whether MITHUNAI support may look, and what it looked at             | [Read support access](/api-reference/support-access/get-support-access), [allow or withdraw it](/api-reference/support-access/set-support-access)                                   |
| **Operations**         | Probes for a load balancer and an orchestrator                       | [Health](/api-reference/operations/health), [readiness](/api-reference/operations/ready)                                                                                            |

## Base URL

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://app.mithunai.com/arukz/api/v1
```

If your organisation uses a different MITHUNAI host, use that host with the same `/arukz/api/v1` path. Examples in this reference use two environment variables:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export MITHUNAI_URL="https://app.mithunai.com"
export MITHUNAI_API_KEY="arukz_sk_..."
```

## Conventions

| Topic          | Convention                                                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Format         | JSON requests and responses. The one exception is [file upload](/api-reference/knowledge/upload-files), which takes `multipart/form-data` |
| Authentication | `Authorization: Bearer arukz_sk_…`. See [Authentication](/api-reference/authentication)                                                   |
| Identifiers    | UUIDs, such as `3f2a1c9e-8b4d-4e6f-9a1b-2c3d4e5f6a7b`                                                                                     |
| Timestamps     | ISO 8601. A timestamp without a UTC offset is in UTC                                                                                      |
| Request size   | At most 256 KiB per JSON request body                                                                                                     |
| Errors         | `{"code": "...", "message": "..."}` with a stable `code`. See [Errors](/api-reference/errors)                                             |
| Lists          | Paged. See [Pagination](/api-reference/pagination)                                                                                        |
| Streaming      | Server-sent events. See [Streaming](/api-reference/streaming)                                                                             |

## Where to call it from

Call the API from your servers. Apart from the [widget endpoints](/api-reference/widget/bootstrap), it does not accept cross-origin requests from browsers, and API keys must never be exposed to a browser.

## Versioning and stability

The API is versioned in its path. Within `v1`:

* Endpoints are not removed and do not change meaning.
* Error `code` values are not renamed.
* Streaming event names are not renamed, and no new terminal event is added.
* New optional fields and new non-terminal event types may be added.

Your client must **ignore fields and event types it does not recognise**.

## Try it

Every endpoint page has an interactive playground. Enter your MITHUNAI API key as the bearer token to send real requests to `app.mithunai.com` from the page.

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Your first cited answer, end to end.
  </Card>

  <Card title="Ask a question" icon="message-circle" href="/api-reference/conversations/send-message">
    The core endpoint.
  </Card>
</Columns>