---
title: "Knowledge"
description: "The documents Raíz agents consult before they answer. Add text, files and websites, follow their indexing, search them, and give them to agents."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

| `kind` | What it is | Send |
| --- | --- | --- |
| `text` | Plain text or Markdown, written inline. | `text`, up to 1,000,000 characters. |
| `file` | A PDF, Word, Excel, HTML, CSV, plain-text or Markdown file. | `file`: its `name`, its `mediaType`, which must match its content, and its bytes in base64 as `data`, up to 8 MiB decoded. |
| `website` | A snapshot of web pages. | `sourceUrl`, an HTTPS page to start from, and optional `crawl` bounds. |

## Add a document

[`raiz.knowledge.create`](/api/raiz/knowledge/create/) takes a `title`, the `kind` and its content, and optionally a `description`:

```bash
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`:

```bash
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](/en/developers/raiz/data/#tasks).

## Indexing

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

| `indexStatus` | Meaning |
| --- | --- |
| `pending` | Waiting to be crawled or indexed. |
| `indexing` | In progress. |
| `ready` | Searchable. |
| `failed` | `indexErrorCode` says why. Failed documents are retried automatically. |

[`raiz.knowledge.get`](/api/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`](/api/raiz/knowledge/list/) lists documents, newest first, by `kind`, `status`, `indexStatus` and `q` (titles and file names).

## Search

[`raiz.knowledge.search`](/api/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:

```bash
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`](/api/raiz/agents/create/) or [`raiz.agents.update`](/api/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`.

> **Knowledge or a bulletin?**
>
> Long reference material belongs in Knowledge. For one situation that lasts a while, such as a closed day or a service that isn't available, post a [bulletin](/en/developers/raiz/campaigns/#bulletins).

## Change or pause a document

[`raiz.knowledge.update`](/api/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.

Source: https://docs.getarbol.com/en/developers/raiz/knowledge/index.mdx