Guides

Knowledge base

Policies, FAQs and documents the AI answers from, and how to see exactly what it would retrieve for a question.

Knowledge documents hold everything a business knows that is not a product: the returns policy, shipping times, opening hours, care instructions, FAQs. The AI answers from these and from your products. If a fact is in neither, the AI cannot use it.

Add a document

curl -X POST https://api.getengageai.app/knowledge/documents \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "POLICY",
    "sourceRef": "returns-policy",
    "title": "Returns policy",
    "content": "Unworn items can be returned within 30 days of delivery for a full refund. Worn footwear cannot be returned unless faulty. Refunds reach the original payment method within 5 working days.",
    "locale": "en-GB",
    "priority": 10
  }'

Field	Notes
`title`	Required.
`content`	Required. Plain text. It is split into chunks on natural boundaries and indexed automatically.
`sourceType`	`FAQ`, `POLICY`, `DOCUMENT`, `WEBPAGE` or `MANUAL` (default). Products use `PRODUCT` and are written through `/products` instead.
`sourceRef`	Your stable identifier for the document. Send the same `sourceRef` again and the document is updated instead of duplicated. Use it for anything synced from another system.
`priority`	Breaks ties in retrieval. Give official policy a higher priority than an older FAQ that says something similar.
`channelScope`	Provider keys this document applies to, such as `["whatsapp_cloud"]`. Empty or omitted means every channel.
`locale`, `tags`	Optional.

The response comes back straight away with status: "PENDING". Indexing happens in the background:

`status`	Meaning
`PENDING`	Saved, waiting to be indexed. Exact-word search already finds it.
`INDEXING`	Being split and embedded.
`INDEXED`	Fully searchable, by meaning and by exact words. `indexedAt` says when.
`FAILED`	Indexing failed. Save it again to retry.
`STALE`	The content changed since it was last indexed; it will be re-indexed.

Saving identical content again does nothing, so replaying a sync is cheap.

Writing documents the AI can use

One topic per document. "Returns policy" and "Shipping to Ireland" retrieve better as two documents than as one long page.
State facts plainly. "Delivery to Ireland takes 3 to 5 working days and costs £6.95" answers a question. "We ship worldwide with our trusted partners" does not.
Use the words customers use. If people say "send it back", include that phrase alongside "returns".
Keep one current version. Two documents that disagree will both be retrieved. Delete the old one or give the current one a higher priority.

Preview what the AI would read

POST /knowledge/preview runs exactly the retrieval the reply engine runs, without generating a reply. Use it whenever a reply is wrong or missing, to tell whether the knowledge is missing or retrieval is not finding it.

curl -X POST https://api.getengageai.app/knowledge/preview \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "can I return boots I have worn?", "topK": 5 }'

{
  "query": "can I return boots I have worn?",
  "results": [
    {
      "chunkId": "…",
      "documentId": "…",
      "title": "Returns policy",
      "relevance": 0.81,
      "rank": 0.0325,
      "source": "HYBRID",
      "excerpt": "Unworn items can be returned within 30 days of delivery for a full refund. Worn footwear cannot be returned unless faulty."
    }
  ]
}

Field	Meaning
`relevance`	How similar the chunk is to the question, from 0 to 1. This is the number to read when judging a match.
`rank`	The combined score used for ordering. It is very small by design; use it to sort, not to judge.
`source`	Which search found it: `SEMANTIC` (meaning), `LEXICAL` (exact words), `HYBRID` (both) or `PINNED`.
`excerpt`	The text the model would see.

topK sets how many results come back. It defaults to 8.

Reading a preview:

The right document is missing → the knowledge is not there. Add it.
It is there but low down, below unrelated chunks → reword it with the customer's vocabulary, split a long document, or raise its priority.
It is there and first → retrieval is fine. If the reply is still wrong, look at the guardrails or the agent profile.

List and delete

curl "https://api.getengageai.app/knowledge/documents?limit=50" -H "Authorization: Bearer $ENGAGE_API_KEY"

curl -X DELETE https://api.getengageai.app/knowledge/documents/$DOCUMENT_ID -H "Authorization: Bearer $ENGAGE_API_KEY"

A deleted document stops being retrieved immediately. Conversations that already used it stay readable.

Semantic search and the fallback

Search by meaning needs an embeddings provider. If a deployment runs without one, retrieval falls back to exact-word search only. That still finds product names and SKUs well, but handles reworded questions poorly. Preview shows LEXICAL on every result when this is the case.