Add Knowledge Source

POST/api/v1/knowledge

Add a text snippet or a URL to the bot's knowledge base. Both are fetched/indexed synchronously — the source is fully searchable by the time this call returns.

Required scope: write

Request body

typestringbodyrequired

"text" to add raw text, or "url" to crawl and index a web page.

namestringbodyrequired

A display name for the source. For URL sources this doesn't need to match the URL itself.

contentstringbody

Required when type is "text" — the text content to add (max 100,000 characters / ~100 KB). Ignored for type: "url".

urlstringbody

Required when type is "url" — the fully-qualified page URL to crawl. Ignored for type: "text".

Response

successboolean

Always true on a 200 response.

charsinteger

URL sources only — the number of characters extracted from the page.

sourceobject

The created source row (same shape as objects returned by List Knowledge Sources): id, type, name, status, char_count, crawl_schedule, next_crawl_at, last_crawled_at, created_at.

Errors

Status	When
`400`	`type` isn't `text`/`url`, `name` is missing, or `content`/`url` is missing or empty for the given type, or text `content` exceeds 100,000 characters.
`401`	Missing or invalid API key.
`403`	Missing `write` scope.
`422`	For `type: "url"` — the page was fetched but returned no usable text content.
`502`	For `type: "url"` — the page couldn't be fetched at all.

Examples

Add text snippet

curl -X POST \
  "https://api.chatty.personaliai.com/api/v1/knowledge" \
  -H "Authorization: Bearer chatty_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "name": "Return Policy",
    "content": "We offer a 30-day money-back guarantee on all purchases. To request a refund, email support@acme.com with your order number."
  }'

Add URL

curl -X POST \
  "https://api.chatty.personaliai.com/api/v1/knowledge" \
  -H "Authorization: Bearer chatty_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "url", "name": "FAQ page", "url": "https://acme.com/docs/faq" }'

200 OK (text):

{
  "success": true,
  "source": {
    "id": "ks-uuid-003",
    "type": "text",
    "name": "Return Policy",
    "status": "trained",
    "char_count": 142,
    "crawl_schedule": null,
    "next_crawl_at": null,
    "last_crawled_at": null,
    "created_at": "2026-07-07T12:00:00Z"
  }
}

200 OK (url) — note the extra chars field:

{
  "success": true,
  "chars": 3184,
  "source": {
    "id": "ks-uuid-004",
    "type": "url",
    "name": "FAQ page",
    "status": "trained",
    "char_count": 3184,
    "crawl_schedule": null,
    "next_crawl_at": null,
    "last_crawled_at": null,
    "created_at": "2026-07-07T12:00:05Z"
  }
}

To keep a URL source fresh automatically, set its crawl_schedule afterward from the dashboard (not available via this endpoint yet).

List Knowledge

Delete Knowledge