API reference

API overview

The Hania HTTP API lets your backend do everything the dashboard does - create bots, ingest knowledge, manage tools, and send messages to agents. It's a JSON API authenticated with a Bearer API key, designed for server-to-server use.

Base URL

All programmatic requests go to the versioned API on a single host:

https://app.hania.ai/api/v1

Only v1 exists today. There is no separate API host or CDN - app.hania.ai is the one host. (The unversioned /api/* surface is the dashboard's own session-authenticated API and isn't intended for integrators - always use /api/v1.)

Authentication

Authenticate every request with an API key in the Authorization header:

Authorization: Bearer hania_sk_3f9a8c21d4e7b05f6a1c9e2d8b7401fa5c3e9d2b

Create a key in the dashboard under Settings → API keys, granting it only the abilities it needs. Keys are prefixed hania_sk_ and the full secret is shown once at creation - store it in a server-side secret manager.

Never expose a hania_sk_ key in client-side code. It's a full-tenant credential for backends only. The API is server-to-server (no browser CORS). For in-browser chat, use the embeddable widget with a widget key instead.

Example request:

curl https://app.hania.ai/api/v1/bots \
  -H "Authorization: Bearer $HANIA_API_KEY"

Abilities

Each key carries a set of abilities that gate what it can do. Read endpoints require the resource's :read ability; endpoints that create, update, or delete require :write. A missing ability returns 403 with "Missing ability: <name>".

You can also grant wildcards: * (everything), or a category wildcard like bots:* (both bots:read and bots:write).

Ability	Governs
`bots:read` / `bots:write`	List/view bots · create, update, delete bots
`tools:read` / `tools:write`	View tools · create, update, delete, assign, test tools
`knowledge:read` / `knowledge:write`	View knowledge bases · upload, update, delete
`memories:read` / `memories:write`	View memories · update, delete
`widgets:read` / `widgets:write`	View widget keys & customization · generate keys, update customization
`conversations:read` / `conversations:write`	List/view/trace conversations · delete conversations
`voice:read` / `voice:write`	View · create, update, delete voice-number mappings
`chat:send`	Send chat messages to bots on behalf of end users
`calls:write`	Originate outbound AI voice calls
`llm:read`	View supported LLM providers and models
`agents:trigger`	Trigger goal-driven agents to run on demand

Response format

Every response is a JSON envelope. Successful requests return:

{
  "success": true,
  "data": { /* the result - object or array */ },
  "message": "Optional human-readable note"
}

Errors return success: false with an error string, and a machine-readable code on coded errors:

{
  "success": false,
  "error": "Missing ability: bots:write"
}

Errors

Status	Meaning
`401`	Authentication failed (missing/invalid key). Intentionally generic - it won't say which check failed.
`402`	Billing block on metered endpoints (chat, calls). Carries a `code` - see below.
`403`	The key lacks the required ability (`"Missing ability: …"`).
`404`	Resource not found.
`405`	Method not allowed on that path.
`429`	Rate limit exceeded - see Rate limits.
`500`	Server error. Safe to retry with backoff.

On a 402 from a metered endpoint, code is one of:

SERVICE_SUSPENDED - the subscription is past due and service is paused.
PLAN_LIMIT_REACHED - the plan's included allowance for the cycle is used up.
INSUFFICIENT_BALANCE - the prepaid balance is exhausted.

Rate limits

Each key has an hourly request limit (a fixed window) set when you create it. Every authenticated response includes the current state:

Header	Value
`X-RateLimit-Limit`	Requests allowed per hour for this key.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Used`	Requests used in the current window.
`X-RateLimit-Reset`	When the window resets (Unix epoch seconds).

When you exceed the limit you get 429 with a Retry-After header (seconds to wait). Retry after that delay.

Pagination

List endpoints page with limit and offset query parameters. For example, conversations default to limit=100, and limit + offset must not exceed 10000. Page forward by increasing offset by your limit.

curl "https://app.hania.ai/api/v1/conversations?limit=50&offset=100" \
  -H "Authorization: Bearer $HANIA_API_KEY"

Resources

The v1 API is a curated, ability-gated surface. Per-resource references:

Chat - send a message to a bot (the core integration endpoint).
Bots - create, update, and manage bots and post-call hooks.
Conversations - list, retrieve, trace, and delete conversations.
Knowledge - add and manage RAG knowledge sources.
Tools - create, assign, test, and discover tools.
Memories - read, update, and delete long-term memories.
Widgets - widget keys, customization, and embed code.
Voice - the voices catalog and voice-number mappings.
LLM - list supported providers and models.
Calls - originate outbound voice calls.
Agents - trigger goal-driven agents on demand.

No SDKs or webhooks yet. Integrate over plain HTTP (curl, fetch, your language's HTTP client). There are no official client libraries and no outbound event/webhook subscriptions at this time.