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

The bot object

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

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. Creation is plan-capped: it returns 402 if the workspace's bot limit is reached, and 502 if the voice provider (Cartesia) sync fails. Common body fields:

Response quality

Three optional booleans switch on per-bot quality checks. They sit alongside model and temperature in the bot body, and come back inside the bot's settings object on GET (an absent key means off). All three are off by default and opt-in per bot.

Completion check

For an Autonomous Agent (bot_type="agent"), two settings control the completion check on its runs. They go in the bot body on create and update, and come back inside settings on GET.

Hania Code

These fields give an agent Hania Code and control it. Like the quality flags, they go in the bot body on create and update, and come back inside the bot's settings object on GET. What each one does, and how rules and hooks match, is explained in Hania Code settings.

• Saves replace the whole set of settings, so with Hania Code on, send code_enabled and code_permission_mode on every save, along with the safety-check model, rules and hooks you want kept. A save that leaves them out switches Hania Code off, or clears that setting.
• When code_enabled is false or missing, the others are dropped on save.
• code_auto_approve was removed on 2026-09-20. An agent that had it on now has code_permission_mode set to auto. Sending the old field does nothing.
• An empty code_permissions or code_hooks isn't stored, which is the same as leaving it out. Don't send an event with an empty list, such as {"PreToolUse": []}; that is stored as written and does nothing. Send {} or leave the key out.
• While Hania Code is on, an invalid mode, rule, or hook is refused with 400, code VALIDATION_FAILED, and field set to code_permission_mode, code_permissions, or code_hooks. The error names the rule or hook and what's wrong with it.

When confidence scoring or response validation is on, each graded turn's outcome (the score, whether the answer was refused, the validation verdict, and any unsupported claims) is available to operators in the console's per-bot Quality tab. It's an operator-only review view, scoped to your workspace; see Reviewing graded turns. Scores and verdicts are never shown to end customers.

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. It returns 503 if no LLM is configured, or 502 on an upstream LLM failure.

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.

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).