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

# 数据源

> 将 HubSpot、Gmail 或 GitHub 等应用连接到命名空间，然后获取、列出、立即同步、更改同步间隔或断开每个数据源。

数据源将一个应用同步到一个命名空间：新增和变更的记录会被写入，已删除的记录会被删除。数据源需要完全访问权限的 [密钥](https://docs.conare.ai/zh/console.md#密钥)；存储桶请参阅 [Google Cloud Storage](https://docs.conare.ai/zh/gcs.md)。

## 连接数据源

`POST /sources`

```bash curl theme={null}
curl https://api.conare.ai/sources \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "hubspot", "namespace": "crm", "redirect_url": "https://yourapp.com/settings"}'
```

```ts TypeScript theme={null}
const { source, connectUrl } = await conare.sources.connect({
  type: "hubspot",
  namespace: "crm",
  redirectUrl: "https://yourapp.com/settings",
});
```

```json Response theme={null}
{
  "source": {
    "id": "src_1cff2c6ea888bbc8343b6e38",
    "type": "hubspot",
    "name": "HubSpot",
    "namespace": "crm",
    "status": "connecting",
    "error": null,
    "documents": 0,
    "last_synced_at": null,
    "created_at": "2026-10-21T21:40:39.704618Z",
    "sync_interval_s": null,
    "sync_interval_auto": true,
    "next_sync_at": null,
    "cost": { "rows_billed": true, "usd_per_million_rows": 100, "options": [ ... ] }
  },
  "connect_url": "https://..."
}
```

将应用的所有者引导至 `connect_url`（7 天内有效）；对方完成连接后即开始首次同步。

| 选项 | 类型 | 作用 |
| - | - | - |
| `type` | string，必填 | 应用，取自 [列表](#列出应用) |
| `namespace` | string，必填 | 要同步到的命名空间 |
| `name` | string | 显示名称，最多 100 个字符 |
| `redirect_url` | string | 用户连接后跳转的地址 |
| `sync_interval_s` | integer | 同步间隔秒数，300 到 2,592,000（30 天）；省略时由 Conare 选择 |
| `config` | object | 用于通过密钥连接的应用（Twenty、Granola、GitHub）：`api_key`，自托管 Twenty 还需 `base_url`；这些应用会立即同步，没有 `connect_url` |

要连接你的用户的应用，请为每个用户分配一个命名空间，例如 `user-42`。完整 schema：[连接数据源](https://docs.conare.ai/zh/api-reference/sources/connect-a-source.md)。

## 同步的文档

| | |
| - | - |
| Id | `<source id>:<schema>:<record key>` |
| 元数据 | `source`、`source_id`、`schema`、`title`，以及记录中存在时的 `url`、`author`、`created_at`、`updated_at` |
| 搜索单个数据源 | 按 `source_id` [过滤](https://docs.conare.ai/zh/filters.md) |

## 获取数据源

`GET /sources/:id`

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

| 字段 | 含义 |
| - | - |
| `id`, `type`, `name`, `namespace` | 与连接时一致 |
| `status` | `connecting`（等待登录）、`syncing`、`ready` 或 `error` |
| `error` | 失败原因，或 `null` |
| `documents` | 已同步的文档数 |
| `progress` | 同步期间，目前的 `records_pulled` |
| `created_at`, `last_synced_at`, `next_sync_at` | 连接时间、上次同步时间和下次同步时间 |
| `sync_interval_s`, `sync_interval_auto` | 同步间隔秒数，以及是否由 Conare 选择 |
| `cost` | 一次同步读取的内容，以及各同步频率每月的费用 |

完整 schema：[获取数据源](https://docs.conare.ai/zh/api-reference/sources/get-a-source.md)。

## 列出数据源

`GET /sources`

返回 `sources`，每项与“获取”返回的格式相同；带有 `kind`（如 `files` 或 `gcs`）的数据源则改为包含 `sync` 对象。

| 选项 | 类型 | 作用 |
| - | - | - |
| `namespace`, `user`, `type` | string | 仅返回该字段等于指定值的数据源，例如 `?namespace=crm&type=hubspot` |

完整 schema：[列出数据源](https://docs.conare.ai/zh/api-reference/sources/list-sources.md)。

## 立即同步

`POST /sources/:id/sync`

在几秒内开始同步并返回数据源；仍处于 `connecting` 的数据源返回 `409 conflict`。

| 选项 | 类型 | 作用 |
| - | - | - |
| `full` | boolean，默认 `false` | 重新读取全部内容，而不只是变更（Gmail、Twenty、Granola、GitHub）；Gmail 的完整同步按首次同步计费，`resync` 会注明这一点 |

完整 schema：[立即同步数据源](https://docs.conare.ai/zh/api-reference/sources/sync-a-source-now.md)。

## 更改同步间隔

`PATCH /sources/:id`

| 选项 | 类型 | 作用 |
| - | - | - |
| `sync_interval_s` | integer 或 null | 300 到 2,592,000 秒；`null` 表示由 Conare 选择 |

返回数据源。完整 schema：[设置数据源的同步频率](https://docs.conare.ai/zh/api-reference/sources/set-how-often-a-source-syncs.md)。

## 断开数据源

`DELETE /sources/:id`

停止同步并返回 `{ "deleted": true }`。

| 选项 | 类型 | 作用 |
| - | - | - |
| `delete_documents` | boolean，默认 `false` | 同时删除其同步的文档 |

完整 schema：[断开数据源](https://docs.conare.ai/zh/api-reference/sources/disconnect-a-source.md)。

## 列出应用

`GET /sources/types`

```json Response theme={null}
{
  "types": [
    { "type": "affinity", "name": "Affinity", "logo_url": "https://..." },
    { "type": "airtable", "name": "Airtable", "logo_url": "https://..." }
  ]
}
```

* 每项包含用于连接的 `type`、其 `name` 和 `logo_url`，通过 `config` 连接的应用还带有 `auth: "api_key"`。
* 当只能列出这些应用时，`partial` 为 `true`：请稍后重试。

完整 schema：[列出数据源类型](https://docs.conare.ai/zh/api-reference/sources/list-source-types.md)。


## Related topics

- [快速入门](https://docs.conare.ai/zh/quickstart.md)
- [Google Cloud Storage](https://docs.conare.ai/zh/gcs.md)
- [命名空间](https://docs.conare.ai/zh/namespaces.md)
- [简介](https://docs.conare.ai/zh/index.md)
- [TypeScript SDK](https://docs.conare.ai/zh/sdk.md)


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