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

# TypeScript SDK

> 适用于 TypeScript 和 JavaScript 的 conare 包：命名空间、搜索、文件、模型和数据源。

`conare` 为 Node 18 及以上版本和 Bun 封装了 API，没有任何依赖。

```bash theme={null}
npm install conare
```

```ts theme={null}
import { Conare } from "conare";

const conare = new Conare(); // reads CONARE_API_KEY
const docs = conare.namespace("docs");

await docs.add({ text: "Refunds are available for 30 days." });
const results = await docs.query("how do refunds work?");
```

```json Result theme={null}
[
  {
    "id": "doc_HmsFWqbQQc2mY03FhVZE",
    "text": "Refunds are available for 30 days.",
    "score": 0.3192,
    "reranked": true,
    "metadata": {}
  }
]
```

响应字段采用 camelCase，时间戳为 `Date`。

## 选项

```ts theme={null}
new Conare({
  apiKey: "sk-conare-...",           // default: CONARE_API_KEY
  baseURL: "https://api.conare.ai",  // default: CONARE_BASE_URL
  timeout: 60_000,                   // ms per attempt
  maxRetries: 2,
  organization: "org_...",           // for a multi-organization key
});
```

每个方法的最后一个参数还可传入 `{ signal, timeout, idempotencyKey }`。

## 方法

| 方法 | 返回值 |
| - | - |
| `conare.namespace(name)` | 命名空间句柄；调用方法前不会发送任何请求 |
| `conare.namespaces({ prefix })` | `[{ name, documents, embeddingModel, rerankModel }]` |
| `ns.add(docs)` | id 列表 |
| `ns.write(docs)` | `[{ id, version, result, chunks, chunksEmbedded }]` |
| `ns.query(query, { topK, filter, rerank, rerankDepth, retrievers, user, userPrefix, excludeIds, hops })` | `[{ id, text, score, reranked, metadata }]` |
| `ns.queryPages(query, { maxResults, ... })` | 分页的异步迭代器 |
| `ns.get(id)` | 文档，或 `null` |
| `ns.list({ limit })` | 遍历所有文档的异步迭代器 |
| `ns.delete(id)` | 无 |
| `ns.deleteMany(ids)`, `ns.deleteWhere(filter)` | 删除的数量 |
| `ns.create({ embeddingModel })` | `{ embeddingModel }` |
| `ns.drop({ force })` | `{ sourcesDeleted }` |
| `ns.uploadFile(file, name, { id, type, user, metadata, pages, password, layout, wait })` | [上传](https://docs.conare.ai/zh/files.md#上传文件)记录，以及 `ready` 后的 Markdown |
| `ns.getFile(fileId, { user })` | 该文件最新的 [上传](https://docs.conare.ai/zh/files.md#查看文件)记录 |
| `conare.parse(file or { url }, { name, type, pages, password, layout, wait })` | 文件的 [Markdown](https://docs.conare.ai/zh/files.md#解析文件)，不存储任何内容 |
| `conare.getParse(id)` | 返回 `parsing` 的解析任务 |
| `conare.embed(texts, { type, outputDtype })` | 向量；使用 `int8` 时为 `{ values, scales }`（`dequantize` 可将其还原） |
| `conare.rerank(query, documents, { topK })` | `[{ index, score, document }]`，附带 `unscored` |
| `conare.sources` | `connect`、`create`、`list`、`get`、`sync`、`update`、`delete`、`types` |
| `conare.organizations()` | 该密钥代表的组织 |
| `conare.users.delete(user)`, `deletePrefix(prefix)` | 删除用户数据的任务 |
| `conare.events.list({ cursor, types })` | 按顺序列出的变更 |

* `add` 和 `write` 接受单个文档或任意大小的数组，每次发送 100 个。
* 搜索所有命名空间（`POST /query`）和 `answer` 暂无对应方法：请通过 HTTP 调用。

## 错误

所有失败都会抛出 `ConareError`，包含 `status`、`code`、`message` 和 `requestId`。

```ts theme={null}
import { ConareError } from "conare";

try {
  await docs.add({ text: "" });
} catch (err) {
  if (err instanceof ConareError) console.log(err.status, err.code); // 400 "invalid_request"
}
```

| 情况 | 行为 |
| - | - |
| 无响应 | `status` 为 `0`，`code` 为 `timeout` 或 `connection_error` |
| `429`、`5xx`、网络错误 | 在 `Retry-After` 或退避之后重试，最多 `maxRetries` 次 |
| 写入 | 携带 [`Idempotency-Key`](https://docs.conare.ai/zh/api#重试)，因此重试绝不会重复写入 |


## Related topics

- [快速入门](https://docs.conare.ai/zh/quickstart.md)
- [简介](https://docs.conare.ai/zh/index.md)
- [嵌入与重排序](https://docs.conare.ai/zh/embed-rerank.md)
- [turbopuffer API](https://docs.conare.ai/zh/turbopuffer.md)
- [搜索](https://docs.conare.ai/zh/query.md)


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