> ## 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.

# API 概览

> Conare API 的 Base URL、身份验证、错误、重试、速率限制和请求头。

Conare API 是基于 HTTPS 的 JSON 接口。每个端点在此标签页中都有对应页面，并附带调试工具。

| | |
| - | - |
| Base URL | `https://api.conare.ai` |
| 身份验证 | `Authorization: Bearer $CONARE_API_KEY` |
| 密钥 | 在 [控制台](https://docs.conare.ai/zh/console.md#密钥) 中创建；请仅保存在你的服务器上 |
| 请求体 | JSON，snake\_case；未知字段返回 `400` |
| 规范 | [api.conare.ai/openapi.yaml](https://api.conare.ai/openapi.yaml) |

```bash theme={null}
curl https://api.conare.ai/namespaces \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

兼容 OpenAI 和 Cohere 的路由（`/v1`、`/v2`）会忽略未知字段。

## 错误

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "documents[0].text is required",
    "request_id": "45ea7c7353368cb646e5cc2303008072"
  }
}
```

| 状态码 | 含义 |
| - | - |
| 400 | 请求无效；`message` 说明原因 |
| 401 | 密钥缺失、错误或已撤销 |
| 403 | 密钥无权访问此命名空间或路由 |
| 404 | 未找到 |
| 409 | 版本冲突，或并发写入已先完成 |
| 413 | 请求体、文档或文件过大 |
| 415 | 不支持该 [文件](https://docs.conare.ai/zh/files.md) 类型 |
| 422 | 无法读取文件，或 `Idempotency-Key` 被用于另一个请求 |
| 429 | 超出 [速率限制](#速率限制) |
| 5xx | 我们这边出现问题 |

## 重试

| 情况 | 处理方式 |
| - | - |
| `429`、`503` | 等待 `Retry-After` 请求头指定的秒数后重试 |
| 其他 5xx | 使用退避策略重试 |
| 写入和删除 | 发送 `Idempotency-Key`（UUID）；24 小时内的重复请求会返回首次的响应并带有 `Idempotent-Replayed: true`，且不做任何更改 |

[SDK](https://docs.conare.ai/zh/sdk.md) 会自动重试并发送 `Idempotency-Key`。

## 速率限制

按组织计算。最多 10 秒用量的突发请求不受影响；超出限制时，API 返回 `429` 及 `Retry-After`。

| 调用 | 每秒 | 同时进行 |
| - | - | - |
| 搜索 | 100 | 128 |
| 写入 | 100 个文档 | 64 |
| 嵌入 | 100 条文本 | 16 |
| 重排序 | 20 | 16 |
| [turbopuffer API](https://docs.conare.ai/zh/turbopuffer.md) 查询 | 1,000 | |
| 其他所有调用 | 100 | |

## 请求头

| 请求头 | 方向 | 含义 |
| - | - | - |
| `Authorization` | 请求 | `Bearer` 加上你的密钥 |
| `Idempotency-Key` | 请求 | 使写入可安全重试 |
| `X-Conare-Org` | 请求 | 使用多组织密钥时要代表的组织（[列出组织](https://docs.conare.ai/zh/api-reference/organizations/list-organizations.md)） |
| `Content-Encoding: gzip` | 请求 | 压缩的请求体；大小上限按解压后计算 |
| `X-Request-Id` | 响应 | 每个响应都带有；联系支持时请提供 |
| `Retry-After` | 响应 | 需等待的秒数，用于 `429` 和 `503` |
| `Conare-Degraded` | 响应 | 请求成功但缺少部分处理，例如重排序（[取值](https://docs.conare.ai/zh/query.md#降级结果)） |
| `Idempotent-Replayed` | 响应 | 重试获得首次响应时为 `true` |

## 健康检查

`GET /health/deep` 无需密钥：`status` 为 `ok`、`degraded`（均为 HTTP 200）或 `down`（HTTP 503）。

```json Response theme={null}
{ "status": "ok", "checkedAt": "2026-10-21T21:39:16.729996745Z" }
```


## Related topics

- [turbopuffer API](https://docs.conare.ai/zh/turbopuffer.md)
- [Embed texts (OpenAI-compatible)](https://docs.conare.ai/zh/api-reference/models/embed-texts-openai-compatible.md)
- [Rerank documents (Cohere- and vLLM-compatible)](https://docs.conare.ai/zh/api-reference/models/rerank-documents-cohere-and-vllm-compatible.md)
- [Rerank documents (Cohere v2-compatible)](https://docs.conare.ai/zh/api-reference/models/rerank-documents-cohere-v2-compatible.md)
- [Connect a source](https://docs.conare.ai/zh/api-reference/sources/connect-a-source.md)


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