> ## 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/zh/filters.md) |
| `user` | string | 仅限该[用户](https://docs.conare.ai/zh/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"]` | `vector`（语义）和 `keyword` 中的 1 个或 2 个 |
| `exclude_ids` | array | 最多 10,000 个要排除的文档 id |
| `max_results` | integer | [分页](#分页)浏览最多 1,000 个结果，使用自定义模型时最多 5,000 个 |
| `cursor` | string | 上一页的 `next_cursor` |

完整 schema：[查询命名空间](https://docs.conare.ai/zh/api-reference/query/query-a-namespace.md)。

## 响应

| 字段 | 含义 |
| - | - |
| `results` | 最佳结果在前，每个文档一个 |
| `results[].id`、`metadata`、`user` | 文档自身的值 |
| `results[].text` | 其能回答问题的段落，最佳的排在最前：最佳段落及最多两个匹配度相近的段落，每个最多约 3,000 字节，不连续的段落之间以仅含 `…` 的一行分隔；完整内容请[获取文档](https://docs.conare.ai/zh/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 秒：请用于需要串联事实的问题。
* 与 `rerank: false` 或 `max_results` 同用，或用于自定义模型的命名空间时，返回 `400 invalid_request`。

## 分页

| 步骤 | 发送 |
| - | - |
| 第一页 | `query`、`max_results`（一次排序的数量）和 `top_k`（每页大小） |
| 后续页 | 仅 `cursor`（上一个 `next_cursor`）和 `top_k` |
| 最后一页 | 没有 `next_cursor` |

游标有效期为 15 分钟。SDK 的 `queryPages()` 会读取所有页。

## 搜索所有命名空间

`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` 在此同样适用。完整 schema：[查询所有命名空间](https://docs.conare.ai/zh/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

- [快速入门](https://docs.conare.ai/zh/quickstart.md)
- [控制台](https://docs.conare.ai/zh/console.md)
- [MCP](https://docs.conare.ai/zh/mcp-server.md)
- [写入文档](https://docs.conare.ai/zh/write.md)
- [文件](https://docs.conare.ai/zh/files.md)


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