Skip to main content

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.

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

MethodPathSummary
GET/api/v1/widget-keysList widget keys
POST/api/v1/widget-keysCreate 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

​
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
CodeDescriptionBody
200OKarray<data.WidgetKey>
400Missing X-Account-ID headerstring
401Missing or invalid bearer tokenstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/widget-keys \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
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.
FieldTypeDescription
agent_idstringe.g. agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
domain_allowlistarray<string>e.g. ['https://acme.com', 'https://www.acme.com']
namestringe.g. acme.com production
Responses
CodeDescriptionBody
201Createddata.CreatedWidgetKey
400Invalid body or name requiredstring
401Missing or invalid bearer tokenstring
500Database errorstring
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"
}'

​
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
NameInTypeRequiredDescription
idpathstringYesWidget 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.
FieldTypeDescription
agent_idstringe.g. agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
disabledbooleane.g. False
domain_allowlistarray<string>e.g. ['https://acme.com', 'https://www.acme.com', 'https://app.acme.com']
namestringe.g. acme.com production (renamed)
Responses
CodeDescriptionBody
204Updated—
400Invalid bodystring
401Missing or invalid bearer tokenstring
500Database errorstring
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)"
}'

​
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
NameInTypeRequiredDescription
idpathstringYesWidget key id (uuid)
Responses
CodeDescriptionBody
204Deleted—
401Missing or invalid bearer tokenstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/widget-keys/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"