Kataven Hub API — widget keys (pk_live_)

pk_live_ keys are public identifiers in HTML — they’re not credentials, domain allowlists keep them safe. Wrapped by the Python SDK and Node SDK.

Endpoints at a glance

Method	Path	Summary
`GET`	`/api/v1/widget-keys`	List widget keys
`POST`	`/api/v1/widget-keys`	Create a widget key (returns plaintext pk_live_ ONCE)
`PATCH`	`/api/v1/widget-keys/{id}`	Update or revoke a widget key
`DELETE`	`/api/v1/widget-keys/{id}`	Delete or soft-disable a widget key

Reference

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

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

from kataven import KatavenClient

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

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

const client = new Kataven();   // reads KATAVEN_API_KEY
await client.widgetKeys.list();

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`
`400`	Invalid body or name required	`string`
`401`	Missing or invalid bearer token	`string`
`500`	Database error	`string`

Example

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

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",
)

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",
});

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

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

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)"
)

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)",
});

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

curl https://api.kataven.ai/v1/widget-keys/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

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

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

Get started

Resources

Kataven Hub API — widget keys (pk_live_)

Endpoints at a glance

Reference

`GET /api/v1/widget-keys`

`POST /api/v1/widget-keys`

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

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

​Endpoints at a glance

​Reference

​GET /api/v1/widget-keys

​POST /api/v1/widget-keys

​PATCH /api/v1/widget-keys/{id}

​DELETE /api/v1/widget-keys/{id}

Endpoints at a glance

Reference

`GET /api/v1/widget-keys`

`POST /api/v1/widget-keys`

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

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