Knowledge

Knowledge is what your agents read to answer: your services and prices, your sites’ addresses and opening hours, how to prepare for a procedure, your policies. You add each source once as a document, Raíz indexes it, and every agent you give it to can look up the right passage when it answers. When the source changes, you update the document and Raíz indexes it again.

Kinds of document

Add a document

raiz.knowledge.create takes a title, the kind and its content, and optionally a description:

curl https://api.getarbol.com/v1/raiz/knowledge \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "kind": "text",
    "title": "Opening hours",
    "text": "Example Clinic is open Monday to Friday from 7:00 to 18:00, and on Saturday from 8:00 to 12:00."
  }'

For a file, encode it in base64 and build the body with jq:

jq -n --rawfile data <(base64 < prices-2026.pdf | tr -d '\n') \
  '{kind: "file", title: "Prices 2026", file: {name: "Prices 2026.pdf", mediaType: "application/pdf", data: $data}}' \
| curl https://api.getarbol.com/v1/raiz/knowledge \
    --request POST \
    --header "Authorization: Bearer $ARBOL_API_KEY" \
    --header "Content-Type: application/json" \
    --data @-

A file that isn’t valid base64, is too large or doesn’t match its mediaType answers 422 KNOWLEDGE_FILE_INVALID.

For a website, crawl sets maxPages (1 to 50) and maxDepth (0 to 5, where 0 imports only that page); by default, 20 pages at depth 2. Only pages of the same origin under the source URL’s path are followed, and robots.txt is respected. The site’s origin must be approved for crawling, or the call answers 422 WEBSITE_NOT_APPROVED. The crawl runs as a knowledge_crawl task.

Indexing

A new or changed document is indexed on its own, and its indexStatus says where it stands:

raiz.knowledge.get reads a document and its indexing state; expand=content adds its text as indexed, in Markdown, up to 200,000 characters (truncated says whether there was more). Use it to see what a document actually says. raiz.knowledge.list lists documents, newest first, by kind, status, indexStatus and q (titles and file names).

Search

raiz.knowledge.search finds the passages that best answer a query of 2 to 500 characters, best first. Each result has the passage’s text, its document’s title and knowledgeDocumentId, and a score: higher is closer. agentId searches exactly what that agent can find, and knowledgeDocumentIds limits the search to those documents. Paused and not-yet-indexed documents are never searched.

Search reads but is sent with POST, so limit (8 by default, up to 20) and cursor go in the body:

curl https://api.getarbol.com/v1/raiz/knowledge/search \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "query": "Saturday opening hours", "agentId": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b" }'

Use it in agents

An agent consults the documents in its knowledgeDocumentIds, up to 100, set with raiz.agents.create or raiz.agents.update; an update sends the complete new list. An id that doesn’t exist in your organization answers 422 KNOWLEDGE_DOCUMENT_UNAVAILABLE. A text agent searches its documents when it needs them; with settings.automaticKnowledge on, it also looks up relevant passages before answering a substantive message. To see which agents use a document, read each agent’s knowledgeDocumentIds.

Change or pause a document

raiz.knowledge.update changes a document; fields you leave out stay. New text or a new file replaces the content and indexes it again, and a new sourceUrl or crawl takes a new snapshot of the website. A change that doesn’t fit the document’s kind answers 422 KNOWLEDGE_KIND_MISMATCH. "status": "paused" hides the document from every agent without deleting it, and keeps its index. Send the version you read as expectedVersion to avoid overwriting someone else’s change.