REST API

Server-side endpoints for knowledge management, persona reads, and subscription limits. Authenticate with an API key and call these from your backend to integrate PersonAIzer into your own flows.

Authentication

All API requests require an API key. Create and manage keys in the dashboard at Settings → API Keys. The full key is shown only once at creation — store it securely on your server and never expose it in client-side code or version control. Keys can be individually disabled or deleted from the dashboard at any time.

X-Api-Key: pa_AbCdEfGhIjKlMnOpQrStUv

curl https://core.personaizer.com/api/knowledge/docs \
  -H "X-Api-Key: pa_AbCdEfGhIjKlMnOpQrStUv"

Identifiers — always use external_id

Every knowledge document has two identifiers: an internal server-generated UUID and a caller-supplied external_id. Always use external_id — it is stable across re-uploads, survives content updates, and is the only identifier exposed in the public API.

# Your own stable slug — survives re-uploads, human-readable
PUT /api/knowledge/docs
{
  "items": [
    { "external_id": "product-SKU-9821", "content": "..." },
    { "external_id": "article-how-to-reset", "content": "..." }
  ]
}

# ✗ Unstable — row 42 today could mean a different product tomorrow.
#   Timestamp-based IDs create duplicates on every re-upload.
{ "external_id": "42", ... }
{ "external_id": "1747123456789", ... }

Two upload patterns

The API offers two endpoints with different processing semantics. Choose based on volume and whether you want immediate availability or batch control.

# Upload a catalog — docs land as "staged", Tasks ignores them.
PUT /api/knowledge/docs
{
  "items": [
    { "external_id": "sku-001", "content": "Blue running shoes, size 10, $89." },
    { "external_id": "sku-002", "content": "Red trail runners, size 9, $109." }
  ]
}

# Response — docs are staged, not yet embedded:
# { "created": 2, "updated": 0, "no_op": 0, "failed": 0,
#   "results": [
#     { "external_id": "sku-001", "status": "created" },
#     { "external_id": "sku-002", "status": "created" }
#   ] }

# Single upsert — immediately queued for embedding.
PUT /api/knowledge/docs/by-external-id/sku-001
{
  "content": "Blue running shoes, size 10, now $79."
}

# Response: HTTP 200 (existing) or 201 (new)
# { "external_id": "sku-001", "status": "updated", "re_embedded": true }

Persona activation

A knowledge document is only surfaced in a persona's context if it is activated for that persona. Activation is the join between a document and a persona — a document can be active for many personas or none. Only embedded (fully processed) documents participate in retrieval; staging or activating a staged document is valid but it won't appear in conversations until embedding completes.

# Replace the full activation list for a persona.
PUT /api/personas/{persona_id}/knowledge
{
  "external_ids": ["sku-001", "sku-002", "article-how-to-reset"]
}

# Add docs without touching the existing list (additive).
POST /api/personas/{persona_id}/knowledge
{
  "external_ids": ["sku-003", "sku-004"]
}

# Response: { "added": 2, "skipped": 0 }

# Remove a single doc from a persona — idempotent.
DELETE /api/personas/{persona_id}/knowledge/sku-003

Checking your limits

Before large uploads, check your remaining quota. Knowledge Units (Ku) measure embedded content volume; Storage Units (Su) measure raw file storage in MB.

curl https://core.personaizer.com/api/subscription/limits \
  -H "X-Api-Key: pa_AbCdEfGhIjKlMnOpQrStUv"

# { "usage": { "knowledgeUnitsUsed": 12480, "knowledgeUnitsLimit": 100000,
#              "storageUnitsUsed": 4.2, "storageUnitsLimit": 512 } }

Uploading beyond your limit returns 402 knowledge.quota_exceeded. The batch endpoint checks quota upfront — if the batch would exceed your limit the entire request is rejected, nothing is written.