API reference

Calls

Originate an outbound AI voice call — Hania dials the number and runs the bot as the agent. Needs calls:write. This endpoint is write-only: it kicks off the call, and the outcome shows up as a conversation.

Originate a call

Method & path	Ability
`POST /api/v1/calls`	`calls:write`

Request body:

Field	Type	Notes
`bot_id`	string (uuid)	Required. The bot that runs the call.
`to_number`	string	Required. The number to dial.

Caller ID and account routing are resolved server-side from the bot's outbound voice-number configuration — they aren't client-supplied. There are no greeting, voice, or variable overrides in the v1 body.

curl https://app.hania.ai/api/v1/calls \
  -H "Authorization: Bearer $HANIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bot_id": "b1f2c3d4-…", "to_number": "+15551234567" }'

Success returns the call id:

{ "success": true, "data": { "call_id": "…" }, "message": "Outbound call initiated" }

Errors: 503 if voice transport is disabled; 400 for an invalid bot_id or a placement failure.

Reading the outcome

This is fire-and-initiate — there is no GET /api/v1/calls/{id}. The call's status and transcript surface as a conversation with channel=voice; read it with conversations:read (filter the list by channel=voice).

Billing differs from Chat. Calls do not return the synchronous 402 codes that chat does. Voice is metered, but the billing check runs when the call is accepted (with a mid-call balance watchdog): an unaffordable call simply won't connect or is ended, and that outcome appears on the conversation. Don't expect a 402 on the originate request.