Kataven Hub API — widget settings

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

Method	Path	Summary
`GET`	`/api/v1/agents/{id}/widget-settings`	Get per-agent widget policy
`PATCH`	`/api/v1/agents/{id}/widget-settings`	Update per-agent widget policy
`GET`	`/api/v1/widget-settings`	Get account-level widget branding
`PATCH`	`/api/v1/widget-settings`	Update account-level widget branding

Reference

Get per-agent widget policy Returns the widget policy for one agent (auth requirements, custom intro copy, agent-specific overrides). Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent id (uuid)

Responses

Code	Description	Body
`200`	OK	`data.AgentWidgetSettings`
`400`	Missing X-Account-ID or agent id	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../widget-settings \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

client = KatavenClient()  # reads KATAVEN_API_KEY
client.widget_settings.get_agent(id="agent_01HZ2N...")

import { Kataven } from "@kataven/server";

const client = new Kataven();   // reads KATAVEN_API_KEY
await client.widgetSettings.getAgent("agent_01HZ2N...");

Update per-agent widget policy Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent 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.

Field	Type	Description
`agent_id`	`string`	e.g. `agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`
`auth_mode`	`string`	e.g. `both`
`widget_enabled`	`boolean`	e.g. `True`

Responses

Code	Description	Body
`200`	OK	`data.AgentWidgetSettings`
`400`	Invalid body or missing agent id	`string`
`500`	Database error	`string`

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
}'

from kataven import KatavenClient

client = KatavenClient()  # reads KATAVEN_API_KEY
client.widget_settings.update_agent(id="agent_01HZ2N...",
    agent_id="agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    auth_mode="both",
    widget_enabled=True
)

import { Kataven } from "@kataven/server";

const client = new Kataven();   // reads KATAVEN_API_KEY
await client.widgetSettings.updateAgent("agent_01HZ2N...", {
  agent_id: "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
  auth_mode: "both",
  widget_enabled: true,
});

Get account-level widget branding Returns the widget appearance config (colors, logo, copy) shared by every embedded widget in this account. Responses

Code	Description	Body
`200`	OK	`data.WidgetSettings`
`400`	Missing X-Account-ID header	`string`
`401`	Missing or invalid bearer token	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/widget-settings \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

client = KatavenClient()  # reads KATAVEN_API_KEY
client.widget_settings.get()

import { Kataven } from "@kataven/server";

const client = new Kataven();   // reads KATAVEN_API_KEY
await client.widgetSettings.get();

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.

Field	Type	Description
`accent_color`	`string`	e.g. `#1e40af`
`launcher_label`	`string`	e.g. `Talk to us`
`launcher_position`	`string`	e.g. `br`
`logo_url`	`string`	e.g. `https://acme.com/logo.svg`
`primary_color`	`string`	e.g. `#2563eb`
`privacy_notice`	`string`	e.g. `Calls may be recorded for quality.`

Responses

Code	Description	Body
`204`	Updated	—
`400`	Invalid body	`string`
`401`	Missing or invalid bearer token	`string`
`500`	Database error	`string`

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."
}'

from kataven import KatavenClient

client = KatavenClient()  # reads KATAVEN_API_KEY
client.widget_settings.update(
    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.",
)

import { Kataven } from "@kataven/server";

const client = new Kataven();   // reads KATAVEN_API_KEY
await client.widgetSettings.update({
  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.",
});

Get started

Resources

Kataven Hub API — widget settings

Endpoints at a glance

Reference

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

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

`GET /api/v1/widget-settings`

`PATCH /api/v1/widget-settings`

​Endpoints at a glance

​Reference

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

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

​GET /api/v1/widget-settings

​PATCH /api/v1/widget-settings

Endpoints at a glance

Reference

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

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

`GET /api/v1/widget-settings`

`PATCH /api/v1/widget-settings`