Knowledge bases

A knowledge base holds reference data that an agent can search during a call, such as your services, locations, or prices. Use it for information that changes more often than your instructions, or that is too large to put in them.

You keep the data in your own system and publish it as a JSON export at an HTTPS URL. Resia reads that export.

Export format

The export must be a JSON object. Every top-level value must be an array of row objects:

{
  "services": [
    {"name": "Eye exam", "duration_minutes": 30, "price_usd": 120},
    {"name": "Contact lens fitting", "duration_minutes": 45, "price_usd": 90}
  ],
  "locations": [
    {"name": "Midtown", "address": "100 W 40th St, New York, NY", "phone": "+12125550100"}
  ]
}

Resia does not support metadata strings or other values beside the arrays.

Create a knowledge base

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/knowledge-bases" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"refresh_url": "https://example.com/exports/resia.json"}'

In the portal, open Knowledge Bases and select Add knowledge base.

Resia imports the export at once. The response field ready tells you whether the first import worked. A knowledge base that is not ready cannot answer calls until a later refresh succeeds.

Use it on a call

Pass the ID as knowledge_base_id when you place a call:

{
  "call_agent_id": "CALL_AGENT_ID",
  "to_phone_number": "+12125550142",
  "inputs": {},
  "knowledge_base_id": "KNOWLEDGE_BASE_ID"
}

How refreshes work

Resia fetches the export again before each call that uses the knowledge base. To decide whether the data changed, it uses, in order:

1. The ETag response header.
2. A valid Last-Modified response header.
3. A SHA-256 digest of the body.

Neither header is required. If you send one, change it whenever the export changes. With an ETag or Last-Modified header, Resia sends a conditional request, and your server can answer 304 Not Modified to skip the download. Without a header, Resia downloads the full export each time.

last_source_version on the knowledge base shows the version that Resia accepted. A failed refresh keeps the previous data.

API reference

Knowledge bases