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

# Knowledge & search

> Manage an agent's knowledge from your code and search it without generating an answer.

Everything you can add in the console's **Knowledge** tab is also available through the API, so you can keep an agent in sync with your help center, CMS or repository automatically.

## Source types

| Type | Endpoint | What it is |
| - | - | - |
| `text` | `POST /agents/{agentId}/sources/text` | A titled piece of text (title 4–55 characters, content up to 1,500) |
| `qa` | `POST /agents/{agentId}/sources/qa` | A question and its exact answer (answer up to 800 characters) |
| `file` | `POST /agents/{agentId}/sources/files` | A PDF, DOC, DOCX or TXT file, up to the agent's remaining storage |
| `website` | `POST /agents/{agentId}/sources/website` | Pages crawled from a URL, on the same domain |

Every source counts toward your plan's storage (characters of text plus bytes of files), and crawled pages toward its page limit. When a limit is reached the API returns `403` with `PLAN_LIMIT_REACHED`. `GET /agents/{agentId}` shows the current `storage.used` and `storage.limit`.

## Add knowledge

<CodeGroup>
  ```bash Text theme={"system"}
  curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/sources/text \
    -H "Authorization: Bearer $REYGRID_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"title": "Refund policy", "content": "Orders can be refunded within 30 days of delivery..."}'
  ```

  ```bash Q&A theme={"system"}
  curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/sources/qa \
    -H "Authorization: Bearer $REYGRID_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"question": "Do you ship abroad?", "answer": "Yes, to 40 countries. Delivery takes 5 to 10 days."}'
  ```

  ```bash File theme={"system"}
  curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/sources/files \
    -H "Authorization: Bearer $REYGRID_API_KEY" \
    -F "file=@handbook.pdf"
  ```

  ```bash Website theme={"system"}
  curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/sources/website \
    -H "Authorization: Bearer $REYGRID_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://docs.example.com"}'
  ```
</CodeGroup>

Files and websites are indexed before the response returns, so a large file or site can take a while. Use a generous client timeout for these requests.

<Info>
  Crawling skips pages the agent already has, so you can call it again later to pick up new pages. To refresh a page that changed, delete it and crawl again.
</Info>

## Keep knowledge in sync

A typical sync job lists what the agent has, removes what's gone, and adds what's new:

```javascript theme={"system"}
const api = (path, init = {}) =>
  fetch(`https://reygrid.com/api/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.REYGRID_API_KEY}`, "Content-Type": "application/json", ...init.headers },
  }).then((res) => res.json());

const AGENT = "{AgentId}";

// 1. Everything the agent has today (text entries here; paginate for more).
const { sources } = await api(`/agents/${AGENT}/sources?type=text&size=100`);
const current = new Map(sources.map((s) => [s.title, s]));

// 2. Your articles, from your CMS.
for (const article of await loadArticles()) {
  const existing = current.get(article.title);
  if (existing?.content === article.body) {
    current.delete(article.title);
    continue;
  }
  if (existing) await api(`/agents/${AGENT}/sources/${existing.id}`, { method: "DELETE" });
  await api(`/agents/${AGENT}/sources/text`, {
    method: "POST",
    body: JSON.stringify({ title: article.title, content: article.body }),
  });
  current.delete(article.title);
}

// 3. Remove entries whose article no longer exists.
for (const stale of current.values()) {
  await api(`/agents/${AGENT}/sources/${stale.id}`, { method: "DELETE" });
}
```

Subscribe to the `source.added` and `source.deleted` [webhooks](/rest-api/webhooks/events#knowledge) to react to changes made by teammates in the console.

## Search without generating

`POST /agents/{agentId}/search` returns the passages closest to a query, **without** calling a model. It's fast, costs a flat **0.2 credits** per search, and gives you the raw material to build your own retrieval flow, a "related articles" box or a search page.

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/search \
    -H "Authorization: Bearer $REYGRID_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "How do I get a refund?", "limit": 3}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "success": true,
    "results": [
      {
        "score": 0.812,
        "content": "Orders can be refunded within 30 days of delivery...",
        "source": { "id": "2f6c…", "type": "text", "title": "Refund policy" }
      }
    ]
  }
  ```
</ResponseExample>

* Results are sorted by `score` (0 to 1, higher is closer). Passages under 0.3 aren't returned.
* `limit` is 1–20 (default 5). Several passages from one file or website can be returned, each pointing to its `source`.
* An empty `results` array means nothing in the agent's knowledge is close to the query.

## Rate answers

Collect end-user feedback on replies with `POST /agents/{agentId}/conversations/{conversationRef}/messages/{messageId}/feedback`:

```bash theme={"system"}
curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/conversations/CONVERSATION_ID/messages/MESSAGE_ID/feedback \
  -H "Authorization: Bearer $REYGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": "down", "comment": "The shipping times are out of date"}'
```

`rating` is `up` or `down`. Sending feedback again for the same message replaces it. The feedback is returned with the message by the [messages endpoint](/rest-api/conversations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.