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

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 messages to a bot (the core integration endpoint).
Bots, Tools, Knowledge, Memories, Conversations, Widgets, Voice, LLM, and Calls references are being published next.

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.