---
title: "Search the knowledge base"
description: "The passages that best answer a question, found the way the AI finds them."
url: "https://openemail.uk/docs/api/knowledge/search"
area: "API"
category: "Mailbox"
---

# Search the knowledge base

The passages that best answer a question, found the way the AI finds them.

`POST /knowledge/search`

## POST /knowledge/search

The passages that best answer a question, found the way the AI finds them.

## Example

Needs `knowledge:read`. `query` is up to 500 characters. With `address`, it searches the levels the AI uses for that address, the most specific ranked a little higher. With `scope`, it searches that one level. With neither, every level you can see. `limit` goes up to 25 and defaults to 8.

**curl**

```
curl -X POST "$OE/knowledge/search" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "query": "How long do refunds take?", "address": "support@acme.com" }'
```

**Response**

```
{
  "object": "knowledge_search",
  "query": "How long do refunds take?",
  "hits": [
    {
      "sourceId": "kb_8c1f4a2b9d7e3f60a5c7b21d",
      "title": "Refunds",
      "kind": "note",
      "scope": "@acme.com",
      "level": "domain",
      "url": null,
      "heading": "",
      "text": "Refunds are paid within 14 days of the return reaching our warehouse.",
      "score": 0.83
    }
  ]
}
```

> It changes nothing, so it is safe to send again. At most three passages come from one item, and `score` only orders the hits of one answer.

> An item is searched once its text has been read. While a changed item is read again, its previous text is searched.

## Reference

- [`POST /knowledge/search`](https://openemail.uk/docs/api/reference/knowledge#post-knowledge-search): full reference