API reference

Bots

Create and manage your agents — their prompt, model, voice settings, and call controls — over the HTTP API. Read endpoints need bots:read; create/update/delete need bots:write.

Endpoints

Method & path	Ability	Notes
`GET /api/v1/bots`	`bots:read`	List bots (no pagination; `?metadata.<key>=<value>` filters)
`POST /api/v1/bots`	`bots:write`	Create → returns `{ id }`
`GET /api/v1/bots/{id}`	`bots:read`	Full bot object
`PUT /api/v1/bots/{id}`	`bots:write`	Partial update → message only
`DELETE /api/v1/bots/{id}`	`bots:write`	Soft-delete (status → `inactive`)
`POST /api/v1/bots/discover`	`bots:write`	AI draft (SSE; JSON with `Accept: application/json`) — does not persist
`PATCH /api/v1/bots/{id}/metadata`	`bots:write`	Raw metadata object (string values, ≤ 8 KB)

The bot object

Fields returned by GET /api/v1/bots/{id}:

Field	Type	Notes
`id`, `tenant_id`	uuid
`name`, `description`	string
`system_prompt`	string	The assembled instructions.
`prompt_builder`, `settings`	string	JSON-encoded strings (parse client-side).
`status`	string	`active` \| `inactive`
`bot_type`	string	`chatbot` \| `agent`
`schedule`, `next_run_at`, `last_run_at`	string	Agent scheduling.
`agent_goal`, `output_config`, `max_iterations`, `timeout_seconds`	mixed	Agent-mode controls.
`metadata`	object	Your own key/value data.
`created_at`, `updated_at`	string	RFC 3339.

The console's conversation_count / tool_count are dashboard-computed and are not part of the v1 bot object.

List bots

GET /api/v1/bots returns all your bots. There's no pagination; narrow the set with metadata filters, e.g. ?metadata.team=support.

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

Create a bot

POST /api/v1/bots creates a bot and returns { "id": "…" }. Provide a name and either a system_prompt or a prompt_builder to assemble one from. Common body fields:

Field	Notes
`name`	Required.
`system_prompt`	Required unless assembled from `prompt_builder`.
`model`, `temperature`	LLM model id and sampling.
`chat_greeting`	Opener for chat conversations.
`tts_provider`, `tts_voice`, `voice_greeting`	Voice output (`tts_provider` ∈ `cartesia` \| `deepgram`).
`end_call_enabled`, `call_transfer_enabled`, `call_transfer_number`	In-call controls.
`outbound_calls_enabled`, `max_call_seconds`	Outbound voice controls.
`bot_type`, `status`, `metadata`	Type, state, and your own data.

On update (PUT), nullable fields follow an "omit to leave unchanged" rule — send only what you want to change.

Draft a bot with AI

POST /api/v1/bots/discover generates a draft bot configuration from a short description (and optional sources). It streams as Server-Sent Events by default, or returns JSON if you send Accept: application/json. The draft is returned, not saved — review it, then create the bot with POST /api/v1/bots.

Metadata

PATCH /api/v1/bots/{id}/metadata sets the bot's metadata object. Values are strings; the object must be ≤ 8 KB. Use it to attach your own identifiers, then filter lists with ?metadata.<key>=<value>.

Post-call hooks

Hooks run a configured tool after a call ends. They're gated by the same bots:read / bots:write abilities.

Method & path	Ability
`GET /api/v1/bots/{botID}/post-call-hooks`	`bots:read`
`POST /api/v1/bots/{botID}/post-call-hooks`	`bots:write` → `{ id }`
`PUT /api/v1/bots/{botID}/post-call-hooks/{hookID}`	`bots:write`
`DELETE /api/v1/bots/{botID}/post-call-hooks/{hookID}`	`bots:write`

Hook object: id, bot_id, tool_configuration_id, tool_type, tool_name, run_order, enabled, params_template (object), created_at, updated_at. To create one, send tool_configuration_id (required), plus optional run_order, enabled (default true), and params_template. A hook is unique per (bot, tool configuration).