> ## 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 keys (pk_live_)

> REST API reference for pk_live_ widget keys — public identifiers embedded in HTML widget bootstrap.

`pk_live_` keys are public identifiers in HTML — they're not credentials, domain allowlists keep them safe. Wrapped by the [Python SDK](/sdks/python/widget-keys) and [Node SDK](/sdks/node/widget-keys).

## Endpoints at a glance

| Method   | Path                                                        | Summary                                                 |
| -------- | ----------------------------------------------------------- | ------------------------------------------------------- |
| `GET`    | [`/api/v1/widget-keys`](#get-api-v1-widget-keys)            | List widget keys                                        |
| `POST`   | [`/api/v1/widget-keys`](#post-api-v1-widget-keys)           | Create a widget key (returns plaintext pk\_live\_ ONCE) |
| `PATCH`  | [`/api/v1/widget-keys/{id}`](#patch-api-v1-widget-keys-id)  | Update or revoke a widget key                           |
| `DELETE` | [`/api/v1/widget-keys/{id}`](#delete-api-v1-widget-keys-id) | Delete or soft-disable a widget key                     |

## Reference

### `GET /api/v1/widget-keys`

List widget keys

Returns metadata for every pk\_live\_ widget key in this account. The plaintext key value is never returned by this endpoint — only the last 8 characters and the row id. To recover a lost key, create a new one.

**Responses**

| Code  | Description                     | Body                    |
| ----- | ------------------------------- | ----------------------- |
| `200` | OK                              | `array<data.WidgetKey>` |
| `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-keys \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.widget_keys.list()
  ```

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

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

### `POST /api/v1/widget-keys`

Create a widget key (returns plaintext pk\_live\_ ONCE)

Mints a new pk\_live\_ public identifier scoped to the caller's account. The plaintext value is returned in the response body and never again — paste it into the customer's HTML `<script data-client-key="...">` attribute.

**Request body** (`application/json`)

Schema: `handlers.CreateWidgetKeyRequest`. 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`             |
| `domain_allowlist` | `array<string>` | e.g. `['https://acme.com', 'https://www.acme.com']` |
| `name`             | `string`        | e.g. `acme.com production`                          |

**Responses**

| Code  | Description                     | Body                                |
| ----- | ------------------------------- | ----------------------------------- |
| `201` | Created                         | [`data.CreatedWidgetKey`](#schemas) |
| `400` | Invalid body or name required   | `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-keys \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    "domain_allowlist": [
      "https://acme.com",
      "https://www.acme.com"
    ],
    "name": "acme.com production"
  }'
  ```

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.widget_keys.create(
      agent_id="agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
      domain_allowlist=["https://acme.com", "https://www.acme.com"],
      name="acme.com production",
  )
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.widgetKeys.create({
    agent_id: "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    domain_allowlist: ["https://acme.com", "https://www.acme.com"],
    name: "acme.com production",
  });
  ```
</CodeGroup>

### `PATCH /api/v1/widget-keys/{id}`

Update or revoke a widget key

Renames the key, replaces the domain allowlist, repins the agent, or revokes (disabled=true sets disabled\_at=now() — idempotent).

**Parameters**

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

**Request body** (`application/json`)

Schema: `handlers.UpdateWidgetKeyRequest`. 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`                                     |
| `disabled`         | `boolean`       | e.g. `False`                                                                |
| `domain_allowlist` | `array<string>` | e.g. `['https://acme.com', 'https://www.acme.com', 'https://app.acme.com']` |
| `name`             | `string`        | e.g. `acme.com production (renamed)`                                        |

**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-keys/agent_01HZ2N... \
    -X PATCH \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    "disabled": false,
    "domain_allowlist": [
      "https://acme.com",
      "https://www.acme.com",
      "https://app.acme.com"
    ],
    "name": "acme.com production (renamed)"
  }'
  ```

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.widget_keys.update(id="agent_01HZ2N...",
      agent_id="agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
      disabled=False,
      domain_allowlist=["https://acme.com", "https://www.acme.com", "https://app.acme.com"],
      name="acme.com production (renamed)"
  )
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.widgetKeys.update("agent_01HZ2N...", {
    agent_id: "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    disabled: false,
    domain_allowlist: ["https://acme.com", "https://www.acme.com", "https://app.acme.com"],
    name: "acme.com production (renamed)",
  });
  ```
</CodeGroup>

### `DELETE /api/v1/widget-keys/{id}`

Delete or soft-disable a widget key

Hard-deletes the row if the key was never used; otherwise sets disabled\_at=now() to preserve the audit trail.

**Parameters**

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

**Responses**

| Code  | Description                     | Body     |
| ----- | ------------------------------- | -------- |
| `204` | Deleted                         | —        |
| `401` | Missing or invalid bearer token | `string` |
| `500` | Database error                  | `string` |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.widget_keys.delete(id="agent_01HZ2N...")
  ```

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

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