API 概览

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


Base URL	`https://api.conare.ai`
身份验证	`Authorization: Bearer $CONARE_API_KEY`
密钥	在控制台中创建；请仅保存在你的服务器上
请求体	JSON，snake_case；未知字段返回 `400`
规范	api.conare.ai/openapi.yaml

curl https://api.conare.ai/namespaces \
  -H "Authorization: Bearer $CONARE_API_KEY"

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

错误

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

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

重试

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

SDK 会自动重试并发送 Idempotency-Key。

速率限制

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

调用	每秒	同时进行
搜索	100	128
写入	100 个文档	64
嵌入	100 条文本	16
重排序	20	16
turbopuffer API 查询	1,000
其他所有调用	100

请求头

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

健康检查

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

Response

{ "status": "ok", "checkedAt": "2026-10-21T21:39:16.729996745Z" }

概览

命名空间

文档

查询

文件

解析

数据源

自定义数据源

模型

用户

事件

组织

健康检查

错误

重试

速率限制

请求头

健康检查

​错误

​重试

​速率限制

​请求头

​健康检查

错误

重试

速率限制

请求头

健康检查