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

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Пошук

> Знаходьте фрагменти, що відповідають на запитання, за змістом і ключовими словами, з переранжуванням.

`POST /namespaces/:namespace/query`

Шукайте в просторі імен за змістом і ключовими словами; Conare переранжовує найкращі збіги й повертає для кожного документа фрагменти, що відповідають.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "top_k": 5, "filter": {"team": "support"}}'
```

```ts TypeScript theme={null}
const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});
```

```json Response theme={null}
{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3192,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 62
}
```

## Параметри

| Параметр | Тип | Що робить |
| - | - | - |
| `query` | string, обов’язковий | Запитання, до 8 000 символів |
| `top_k` | integer, за замовчуванням 10 | Кількість результатів, 1-500 |
| `filter` | object | [Фільтр метаданих](https://docs.conare.ai/uk/filters.md) |
| `user` | string | Лише документи цього [користувача](https://docs.conare.ai/uk/write.md#користувачі) |
| `user_prefix` | string | Лише користувачі, що починаються з цього, як-от `tenant-7:` |
| `answer` | boolean, за замовчуванням `false` | Також [сформувати відповідь](#відповіді) |
| `rerank` | boolean, за замовчуванням `true` | Переранжувати найкращі збіги; `false` працює швидше |
| `rerank_depth` | integer, за замовчуванням 20 | Скільки верхніх фрагментів переранжувати, 1-1 000 |
| `hops` | integer, за замовчуванням 1 | `2` шукає повторно від найкращих результатів ([два кроки](#два-кроки)) |
| `retrievers` | array, за замовчуванням `["vector", "keyword"]` | 1 або 2 з `vector` (зміст) і `keyword` |
| `exclude_ids` | array | До 10 000 id документів, які слід виключити |
| `max_results` | integer | [Посторінковий перегляд](#сторінки) до 1 000 результатів або 5 000 із власною моделлю |
| `cursor` | string | `next_cursor` попередньої сторінки |

Повна схема: [Query a namespace](https://docs.conare.ai/uk/api-reference/query/query-a-namespace.md).

## Відповідь

| Поле | Значення |
| - | - |
| `results` | Спершу найкращі, по одному на документ |
| `results[].id`, `metadata`, `user` | Відповідні поля документа |
| `results[].text` | Його фрагменти, що відповідають, найкращий першим: найкращий і до двох інших, майже так само релевантних, кожен приблизно до 3 000 байтів, з рядком лише з `…` між фрагментами, що не йдуть один за одним; [отримайте документ](https://docs.conare.ai/uk/documents.md), щоб побачити його повністю |
| `results[].score` | Що вище, то краще; порівнюйте лише в межах одного запиту |
| `results[].reranked` | Чи оцінив його переранжувальник; результати без переранжування йдуть останніми |
| `answer` | Відповідь, якщо `answer: true` |
| `next_cursor` | Із `max_results` — `cursor` наступної сторінки; відсутній на останній сторінці |
| `took_ms` | Час пошуку в мілісекундах |

## Відповіді

`"answer": true` додає відповідь, сформовану з найкращих фрагментів, приблизно за 2 секунди більше.

```json Response theme={null}
{
  "answer": "Refunds are available for 30 days (source dated 2026-10-21). No further details on the refund process, conditions, or method were found in this search.",
  "results": [ ... ],
  "took_ms": 1546
}
```

* Її пише мовна модель на основі знайдених фрагментів; див. [політику конфіденційності](https://conare.ai/privacy).
* Якщо ця модель недоступна, ви отримаєте результати без `answer`.

## Два кроки

`"hops": 2` шукає повторно від найкращих результатів — для запитань, відповідь на які потребує фактів із двох документів.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/films/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where was the director of The Long Harbor born?", "hops": 2}'
```

* Це додає близько 0,3 секунди: використовуйте для запитань, що поєднують факти.
* Повертає `400 invalid_request` із `rerank: false`, із `max_results` і в просторах імен власної моделі.

## Сторінки

| Крок | Надішліть |
| - | - |
| Перша сторінка | `query`, `max_results` (скільки ранжувати за один раз) і `top_k` (розмір сторінки) |
| Наступні сторінки | Лише `cursor` (останній `next_cursor`) і `top_k` |
| Остання сторінка | Не має `next_cursor` |

Курсор діє 15 хвилин. `queryPages()` у SDK читає всі сторінки.

## Пошук в усіх просторах імен

`POST /query`

Той самий запит у до 100 просторах імен із спільним переранжуванням; `prefix` обмежує пошук просторами імен, назви яких із нього починаються.

```bash curl theme={null}
curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'
```

```json Response theme={null}
{
  "namespaces": ["acme-docs"],
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3471,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "skipped_namespaces": [],
  "took_ms": 64
}
```

| Параметр або поле | Тут |
| - | - |
| `prefix` | Лише простори імен, назви яких починаються з цього |
| `rerank_depth` | За замовчуванням 60, 1-1 000 |
| `exclude_ids` | Записуються як `namespace/id` |
| `results[].namespace` | Простір імен результату |
| `namespaces`, `skipped_namespaces` | Ті, де виконано пошук, і ті, що після перших 100 |

`hops` тут також працює. Повна схема: [Query every namespace](https://docs.conare.ai/uk/api-reference/query/query-every-namespace.md).

## Неповні результати

Якщо частина пошуку не вдається, запит усе одно виконується, а заголовок `Conare-Degraded` повідомляє, що було пропущено.

| Значення | Що означає |
| - | - |
| `rerank`, `rerank-partial` | Деякі або всі результати не переранжовано (`reranked: false`) |
| `embed` | Пошук лише за ключовими словами |
| `keyword`, `keyword-terms` | Запит задовгий, щоб пошук за ключовими словами прочитав його повністю |
| `embed-next` | Частину простору імен не вдалося обшукати |
| `cursor` | Немає `next_cursor`; виконайте пошук ще раз, щоб отримати більше сторінок |
| `embed-busy`, `embed-fallback` | Повільніше, ніж зазвичай; на результати не впливає |
| `answer` | Без відповіді, лише результати |

Якщо пошук не вдалося виконати взагалі, запит повертає `503`.


## Related topics

- [Query a namespace](https://docs.conare.ai/uk/api-reference/query/query-a-namespace.md)
- [Query every namespace](https://docs.conare.ai/uk/api-reference/query/query-every-namespace.md)
- [Фільтри](https://docs.conare.ai/uk/filters.md)
- [Файли](https://docs.conare.ai/uk/files.md)
- [TypeScript SDK](https://docs.conare.ai/uk/sdk.md)


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