Skip to main content
Widget branding (account-level) and per-agent widget policy (auth requirements, custom intro). Wrapped by the Python SDK and Node SDK.

​
Endpoints at a glance

MethodPathSummary
GET/api/v1/agents/{id}/widget-settingsGet per-agent widget policy
PATCH/api/v1/agents/{id}/widget-settingsUpdate per-agent widget policy
GET/api/v1/widget-settingsGet account-level widget branding
PATCH/api/v1/widget-settingsUpdate account-level widget branding

​
Reference

​
GET /api/v1/agents/{id}/widget-settings

Get per-agent widget policy Returns the widget policy for one agent (auth requirements, custom intro copy, agent-specific overrides). Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id (uuid)
Responses
CodeDescriptionBody
200OKdata.AgentWidgetSettings
400Missing X-Account-ID or agent idstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../widget-settings \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
PATCH /api/v1/agents/{id}/widget-settings

Update per-agent widget policy Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id (uuid)
Request body (application/json) Schema: data.AgentWidgetSettings. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
agent_idstringe.g. agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
auth_modestringe.g. both
widget_enabledbooleane.g. True
Responses
CodeDescriptionBody
200OKdata.AgentWidgetSettings
400Invalid body or missing agent idstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../widget-settings \
  -X PATCH \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
  "auth_mode": "both",
  "widget_enabled": true
}'

​
GET /api/v1/widget-settings

Get account-level widget branding Returns the widget appearance config (colors, logo, copy) shared by every embedded widget in this account. Responses
CodeDescriptionBody
200OKdata.WidgetSettings
400Missing X-Account-ID headerstring
401Missing or invalid bearer tokenstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/widget-settings \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
PATCH /api/v1/widget-settings

Update account-level widget branding Request body (application/json) Schema: data.WidgetSettings. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
accent_colorstringe.g. #1e40af
launcher_labelstringe.g. Talk to us
launcher_positionstringe.g. br
logo_urlstringe.g. https://acme.com/logo.svg
primary_colorstringe.g. #2563eb
privacy_noticestringe.g. Calls may be recorded for quality.
Responses
CodeDescriptionBody
204Updated—
400Invalid bodystring
401Missing or invalid bearer tokenstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/widget-settings \
  -X PATCH \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accent_color": "#1e40af",
  "launcher_label": "Talk to us",
  "launcher_position": "br",
  "logo_url": "https://acme.com/logo.svg",
  "primary_color": "#2563eb",
  "privacy_notice": "Calls may be recorded for quality."
}'