MITHUNAI HTTP API: base URL and rules

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

Base URL

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:

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, which takes `multipart/form-data`
Authentication	`Authorization: Bearer arukz_sk_…`. See 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
Lists	Paged. See Pagination
Streaming	Server-sent events. See Streaming

Where to call it from

Call the API from your servers. Apart from the widget endpoints, 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.

Quickstart

Your first cited answer, end to end.

Ask a question

The core endpoint.

Get started

Conversations

Assistants

Models

Knowledge

Widget deployments

Widget (public)

MCP

API keys

Members

Analytics

Support access

Branding

Operations

MITHUNAI HTTP API: base URL and rules

The resources

Base URL

Conventions

Where to call it from

Versioning and stability

Try it

Quickstart

Ask a question

​The resources

​Base URL

​Conventions

​Where to call it from

​Versioning and stability

​Try it

Quickstart

Ask a question

The resources

Base URL

Conventions

Where to call it from

Versioning and stability

Try it