API reference

Widgets

Manage the embeddable chat widget for a bot — its public keys, its look and copy, and the embed snippet. Read endpoints need widgets:read; creating keys and saving customization need widgets:write. Everything is scoped by bot_id.

A "widget" isn't a single object — it's a bot's API keys + customization + embed code. There's no "list widgets" endpoint; you work per bot.

Endpoints

Method & path	Ability	Notes
`GET /api/v1/widgets/keys?bot_id=`	`widgets:read`	List a bot's widget keys
`POST /api/v1/widgets/keys`	`widgets:write`	Create a key
`DELETE /api/v1/widgets/keys/{id}`	`widgets:write`	Revoke a key
`GET /api/v1/widgets/customization?bot_id=`	`widgets:read`	Current look & copy
`PUT /api/v1/widgets/customization`	`widgets:write`	Save → returns updated object
`GET /api/v1/widgets/embed-code?bot_id=&api_key_id=`	`widgets:read`	`{ embed_code, api_key }`

Widget keys

Create a key with POST /api/v1/widgets/keys:

{
  "bot_id": "b1f2c3d4-…",
  "name": "Marketing site",
  "allowed_domains": ["example.com"],
  "rate_limit_per_hour": 1000
}

The key object: id, bot_id, api_key, name, allowed_domains[], rate_limit_per_hour (default 1000), is_active, created_at, optional last_used_at.

The widget api_key (prefix hania_) is returned in full by the list/create/embed endpoints — that's intentional. It's a public, domain-restricted key meant to be embedded in the browser, and it's a different key from your account hania_sk_ key. Never confuse the two: hania_sk_ is a full-tenant secret and must stay on your server; the widget key is safe in client-side HTML.

Customization

PUT /api/v1/widgets/customization saves and returns the widget's appearance. Body / object fields: bot_id, theme_color, position, greeting_text, optional welcome_message, optional avatar_url, show_branding, optional widget_title, placeholder_text (plus read-only id, created_at, updated_at). Changes apply to the live widget.

Embed code

GET /api/v1/widgets/embed-code?bot_id=&api_key_id= returns the ready-to-paste embed_code snippet (and the api_key it uses) for the given bot and widget key. Drop the snippet into your site's HTML.