AI Agent Knowledge

Find the agent id

Open the agent under AI Agents. Its id is the last part of the page address: /ai-agents/<agent_id>.

Request

curl -X POST https://api.whatbot.in/public/v1/agents/9b3d.../knowledge \
  -H "X-API-Key: wa_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "faq",
    "title": "Tower B — pricing and possession",
    "raw_text": "Q: When is possession?\nA: December 2027.\n\nQ: Is there a floor-rise charge?\nA: Yes, from the 5th floor.",
    "external_ref": "kb:tower-b"
  }'

Field	Type	Required	Description
source_type	string		`faq` (text you send) or `url` (a page we fetch). Defaults to `faq`.
title	string	Yes	A name for the source, shown on the agent’s knowledge list. 1–200 characters.
raw_text	string	For `faq`	The text. Separate topics with blank lines — chunks are cut on paragraph boundaries.
url	string	For `url`	The page to read. Fetched when the source is indexed; `https://` is assumed if you leave the scheme off.
external_ref	string		Your stable key for this source, up to 200 characters. Send the same `external_ref` again to replace the source’s content instead of adding a second copy.

{ "id": "e71a...", "external_ref": "kb:tower-b", "action": "created" }

action is created or updated. Without an external_ref, every call creates a new source.

Indexing

Indexing runs after the response, so the agent can’t use new text for a few moments. Re-sending a source re-indexes it, and a successful re-index replaces its old chunks — nothing stale is left behind. If the re-index fails because the page can’t be fetched or has no readable text, the old chunks stay in use until a later send succeeds. Text is split into chunks of about 800 characters, and each source is read up to 200,000 characters.

The agent’s page under AI Agents shows each source’s status — embedded once indexed, failed if indexing failed — and its chunk count. A url source that can’t be fetched, or a source with no readable text, shows as failed there — the API call itself has already returned 200.

Errors

Status	Cause
`401`	Missing/invalid API key
`404`	No agent with that id in your workspace
`422`	`raw_text` missing for `faq`, `url` missing for `url`, an unknown `source_type`, or `title` missing or too long