> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kataven Hub API — widget settings

> REST API reference for widget branding (account-level) and per-agent widget policy.

Widget branding (account-level) and per-agent widget policy (auth requirements, custom intro). Wrapped by the [Python SDK](/sdks/python/widget-settings) and [Node SDK](/sdks/node/widget-settings).

## Endpoints at a glance

| Method  | Path                                                                             | Summary                              |
| ------- | -------------------------------------------------------------------------------- | ------------------------------------ |
| `GET`   | [`/api/v1/agents/{id}/widget-settings`](#get-api-v1-agents-id-widget-settings)   | Get per-agent widget policy          |
| `PATCH` | [`/api/v1/agents/{id}/widget-settings`](#patch-api-v1-agents-id-widget-settings) | Update per-agent widget policy       |
| `GET`   | [`/api/v1/widget-settings`](#get-api-v1-widget-settings)                         | Get account-level widget branding    |
| `PATCH` | [`/api/v1/widget-settings`](#patch-api-v1-widget-settings)                       | Update 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**

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

**Responses**

| Code  | Description                      | Body                                   |
| ----- | -------------------------------- | -------------------------------------- |
| `200` | OK                               | [`data.AgentWidgetSettings`](#schemas) |
| `400` | Missing X-Account-ID or agent id | `string`                               |
| `500` | Database error                   | `string`                               |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../widget-settings \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```

  ```python Python SDK theme={null}
  from kataven import KatavenClient

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

  ```typescript Node SDK theme={null}
  import { Kataven } from "@kataven/server";

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

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

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`](#schemas) |
| `400` | Invalid body or missing agent id | `string`                               |
| `500` | Database error                   | `string`                               |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  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
  }'
  ```

  ```python Python SDK theme={null}
  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
  )
  ```

  ```typescript Node SDK theme={null}
  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,
  });
  ```
</CodeGroup>

### `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**

| Code  | Description                     | Body                              |
| ----- | ------------------------------- | --------------------------------- |
| `200` | OK                              | [`data.WidgetSettings`](#schemas) |
| `400` | Missing X-Account-ID header     | `string`                          |
| `401` | Missing or invalid bearer token | `string`                          |
| `500` | Database error                  | `string`                          |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/widget-settings \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```

  ```python Python SDK theme={null}
  from kataven import KatavenClient

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

  ```typescript Node SDK theme={null}
  import { Kataven } from "@kataven/server";

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.widgetSettings.get();
  ```
</CodeGroup>

### `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.

| 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**

<CodeGroup>
  ```bash curl theme={null}
  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."
  }'
  ```

  ```python Python SDK theme={null}
  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.",
  )
  ```

  ```typescript Node SDK theme={null}
  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.",
  });
  ```
</CodeGroup>