# 知识库 API

知识库是 AI 读取信息的内容来源。它包含两个部分，本页面将涵盖这两部分：

- **知识源** (`/kb-sources`) — 您提供给平台的网页和上传的文档。每一项都会被读取、拆分为多个部分，并转化为 AI 可以回答的常见问题 (FAQ)。
- **知识组** (`/kb-groups`) — 常见问题的命名集合，您可以在一次调用中将其应用于代理 (Agent) 或营销活动，以便您可以将已经整理好的知识库重复用于您创建的下一个代理。

知识源生成的常见问题会进入与您手动编写的常见问题相同的库中，因此一旦导入完成，您就可以使用 [FAQs API](faqs.md) 来阅读、编辑和链接它们。

以下所有端点均相对于基础 URL `https://api.youraiconnector.com/v1`。每个请求都必须经过身份验证——请参阅 [API 访问](../integrations/api-access.md) 和 [身份验证](authentication.md)。API 访问是一项付费功能；如果没有该权限，请求将被 `403` 拒绝。


> **导入会消耗积分。** 读取页面或文档并从中生成常见问题会消耗积分，消耗量大致与内容量成正比。在进行大规模抓取之前，请使用 [估算导入成本](#estimate-what-an-import-will-cost)。

---

## 导入的工作原理

导入是一个后台任务，不会立即完成。每个导入端点都会立即返回一个 `source_id`，您需要轮询该源直到其完成：

1. **开始导入** — `POST /kb-sources/url`（单个页面）、`POST /kb-sources/file`（上传的文档）或 `POST /kb-sources/bulk-import`（最多 100 个页面）。您将获得一个源 ID 和 `status: "queued"`。
2. **轮询** — `GET /kb-sources/{sourceId}` 直到 `status` 不再是 `queued` 或 `processing`。
3. **阅读常见问题** — 当状态为 `ready` 时，它生成的条目就在您的常见问题库中：`GET /faqs`。

每个源都会报告以下状态之一：

| 状态 | 含义 |
|---|---|
| `queued` | 等待读取。尚未扣费。 |
| `processing` | 正在读取并转化为常见问题。 |
| `ready` | 已完成。其常见问题已存入您的库中。 |
| `failed` | 无法导入。`error_message` 说明了原因。 |
| `cancelled` | 在读取前已停止（请参阅 [停止导入](#stop-an-import)）。 |
| `paused` | 因您的 AI 密钥在导入过程中失效而停止（请参阅 [恢复已暂停的导入](#resume-a-paused-import)）。 |
| `deleting` | 批量删除操作正在处理中。 |
| `unknown` | 该记录没有状态。请将其视为未就绪。 |

> **导入时附加。** 在任何导入端点上传递 `autoLinkToAgentId`，该源及其生成的每个常见问题都会在同一次调用中添加到该代理的知识库中，无需后续的链接步骤。`autoLinkToCampaignId` 对经典营销活动执行相同的操作。链接是尽力而为的：如果 ID 不存在或属于另一个账户，它会被静默跳过，导入仍会运行，因此请通过读取代理信息来确认链接情况。

---

## 导入网页

`POST /kb-sources/url`

将一个网页添加到您的知识库。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `url` | 是 | 页面的完整 `http` 或 `https` 地址。 |
| `autoLinkToAgentId` | 否 | 要将导入的源附加到的 AI Agent 的 ID。 |
| `autoLinkToCampaignId` | 否 | 旧版。要将导入的源附加到的营销活动的 ID。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")
```

**响应** — `202 Accepted`

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}
```

使用 [检查源](#check-a-source) 轮询 `source_id`，直到状态为 `ready` 或 `failed`。

如果同一个页面已存在于您的知识库中，则不会排队任何新内容，您将收到一个 `200` — 如果您请求了自动链接，现有的源仍会为您链接：

```json
{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}
```

缺少 `url`，或者不是有效的 `http`/`https` 地址，将返回 `400`。

---

## 导入已上传的文档

`POST /kb-sources/file`

将**已在您账户文件存储中**的文档添加为知识源。支持的类型：PDF、DOCX、TXT、MD、CSV 和 XLSX。

> **此端点不携带文件。** 没有多部分上传、没有 base64 正文，也没有从 URL 下载：您发送的是已存在文件的存储位置，并且它必须位于您自己的上传文件夹下（`storage_path` 必须以 `users/{your user id}/uploads/` 开头），否则请求将被拒绝并返回 `403`。当您将文件拖入仪表板时，仪表板会将文件放置在那里。如果您无法将文件放置在那里，请改用 [导入网页](#import-a-web-page)。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `storage_path` | 是 | 已上传文件的存储位置。必须以 `users/{your user id}/uploads/` 开头。 |
| `filename` | 是 | 原始文件名（包括扩展名）——这是检测文件类型的方式。 |
| `mime_type` | 是 | 文件的 MIME 类型，例如 `application/pdf`。 |
| `autoLinkToAgentId` | 否 | 要将文档附加到的 AI Agent 的 ID。 |
| `autoLinkToCampaignId` | 否 | 旧版。要将文档附加到的营销活动的 ID。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'
```

**响应** — `202 Accepted`

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}
```

| 状态 | 何时 |
|---|---|
| `400` | 缺少必填字段，或者文件类型无法读取。 |
| `403` | `storage_path` 不在您自己的上传文件夹内。 |

---

## 检查源

`GET /kb-sources/{sourceId}`

每次导入和刷新后进行的轮询。重复此操作，直到状态为 `ready` 或 `failed`。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()
```

**响应**

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}
```

| 字段 | 类型 | 描述 |
|---|---|---|
| `status` | string | 源在流水线中的位置（请参阅[状态表](#how-an-import-works)）。 |
| `faq_count` | integer | 到目前为止由此源生成的常见问题解答（FAQ）数量。 |
| `section_count` | integer | 该源被拆分成的内容部分数量。 |
| `error_message` | string \| null | 当状态为 `failed` 时，导入失败的原因。否则为 `null`。 |

---

## 删除源

`DELETE /kb-sources/{sourceId}`

移除一个知识源。**默认情况下，它生成的常见问题解答（FAQ）会被保留** —— 添加 `delete_faqs=true` 可同时将其一并删除。

**查询参数**

| 参数 | 必需 | 描述 |
|---|---|---|
| `delete_faqs` | 否 | 设置为 `true` 以同时删除该源生成的所有常见问题解答。默认为 `false`。 |

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"
```

**响应**

```json
{
  "success": true,
  "faqs_deleted": 24
}
```

`faqs_deleted` 为 `0`，除非您要求 `delete_faqs=true`。

---

## 一次性导入多个页面

`POST /kb-sources/bulk-import`

单次调用最多可添加 100 个网页 —— 这是[发现网站页面](#discover-pages-on-a-website)或[查找网站新页面](#find-new-pages-on-a-website)后的常用后续操作。知识库中已有的页面会被跳过，而不会重复添加（如果您有相关要求，它们仍会链接到智能体）。

**请求字段**

| 字段 | 必需 | 描述 |
|---|---|---|
| `urls` | 是 | 要导入的地址。每次调用至少 1 个，最多 100 个。 |
| `autoLinkToAgentId` | 否 | 要将每个导入页面关联到的 AI 智能体 ID。 |
| `autoLinkToCampaignId` | 否 | 旧版字段。要将每个导入页面关联到的营销活动 ID。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]
```

**响应** — `202 Accepted`

```json
{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}
```

使用[检查源](#check-a-source)轮询 `queued_source_ids` 中的每个 ID。发送空的 `urls` 数组、非字符串条目或超过 100 个条目将返回 `400`。

---

## 一次性删除多个源

`POST /kb-sources/bulk-delete`

单次调用最多可移除 2,000 个知识源。移除操作在后台运行，完成后您会收到一封电子邮件。

> **批量删除也会同时移除常见问题解答 (FAQs)。** 与 [删除数据源](#delete-a-source) 不同（后者除非您另有要求，否则会保留常见问题解答），此端点会删除每个数据源及其生成的常见问题解答。没有保留它们的选项。

**请求字段**

| 字段 | 必填 | 说明 |
|---|---|---|
| `sourceIds` | 是 | 要移除的数据源 ID。每次调用至少 1 个，最多 2,000 个。 |
| `domainLabel` | 否 | 此清理任务的友好名称。仅用于完成通知邮件中。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'
```

**响应** — `202 Accepted`

```json
{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}
```

---

## 发现网站页面

`POST /kb-sources/discover-pages`

从一个起始地址探索网站，并列出在同一域名下找到的页面，同时对每个页面是否值得导入给出建议。**不会导入任何内容，也不会为您进行任何选择** —— 这是您在决定发送给 [批量导入多个页面](#import-many-pages-at-once) 之前执行的“网站内容概览”步骤。

**请求字段**

| 字段 | 必填 | 说明 |
|---|---|---|
| `url` | 是 | 开始探索的地址，通常是网站的主页。 |
| `maxPages` | 否 | 返回页面的数量上限。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'
```

**响应**

```json
{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `source_type` | string | 发现页面的方式 — `sitemap`（网站自身的站点地图）或 `link_discovery`（通过跟踪链接）。 |
| `url` | string | 页面的完整地址。 |
| `title` | string \| null | 页面标题（如果可以读取的话）。 |
| `depth` | integer | 该页面距离起始页面有多少个链接层级。 |
| `score` | integer | 该页面作为知识库的有用程度，从 `0` 到 `100`。 |
| `recommendation` | string | `add`（显然值得导入，评分 90 或以上）、`maybe`（处于临界值）或 `skip`（很少对助手有帮助的内容 — 更新日志、法律页面、重复的翻译）。 |
| `reason_key` | string | 推荐背后的稳定、机器可读的原因，例如 `core_page`、`changelog_history`、`legal_page` 或 `locale_duplicate`。 |

> **探索是尽力而为的。** 如果无法读取网站，响应仍为 `200`，包含 `success: false`、空的 `pages` 列表和 `error` 消息。在读取 `pages` 之前，请检查 `success`。

缺少 `url` 会返回 `400`。

---

## 估算导入成本

`POST /kb-sources/estimate-cost`

在您提交导入之前，计算拟议的导入将消耗多少积分。系统会抓取页面并读取文档以衡量其大小，但不会导入任何内容，且估算本身不会消耗积分。

**请求字段**

| 字段 | 必填 | 说明 |
|---|---|---|
| `urls` | 否 | 您考虑导入的页面地址。 |
| `files` | 否 | 您考虑使用的已上传文件。每个条目都需要 `storage_path`、`filename` 和 `mime_type`。 |
| `tier` | 否 | 导入将运行的 AI 质量层级，以便估算结果与您实际将被收取的费用相匹配。如果不填，则按标准费率计算。 |

发送 `urls`、`files` 或两者皆有。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'
```

**响应**

```json
{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7
}
```

每一行都会回显 `ref` 中的 URL 或存储路径，以便您将其与输入进行匹配。无法读取的页面或文件仍会占据一行，计为一个数据块，并带有 `error` 标记。

---

## 停止导入

`POST /kb-sources/cancel-import`

停止仍在导入队列中等待的页面——这是针对超出预期规模的爬取任务的“停止导入”按钮。取消等待中的页面不会产生任何费用，因为它尚未被读取。

已经处于处理中的页面**不会**被停止：它们的工作正在进行中，无论如何都会计费，因此它们会继续完成。响应会报告此类页面的数量。

**请求字段**

| 字段 | 必填 | 说明 |
|---|---|---|
| `host` | 否 | 仅停止此网站上等待中的页面（例如 `docs.example.com`）。留空则停止账户中所有等待中的导入任务。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'
```

**响应**

```json
{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}
```

---

## 恢复已暂停的导入

`POST /kb-sources/resume-import`

重启因您自己的 AI 密钥失效而暂停的导入任务。

> 调用此接口即表示您同意使用当前有效的密钥完成导入——如果您的密钥仍不可用，这可能意味着需要消耗平台额度。

**请求字段**

| 字段 | 必填 | 说明 |
|---|---|---|
| `host` | 否 | 仅恢复此网站上已暂停的页面。留空则恢复所有已暂停的任务。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**响应**

```json
{
  "success": true,
  "resumed": 58
}
```

---

## 查找网站上的新页面

`POST /kb-sources/refresh-domain`

探索您已经导入过的网站，并仅报告那些**尚未**进入您知识库的页面，每个页面都会提供与页面发现相同的建议。此操作不会导入任何内容，也不会进行任何更改。

这两个后续操作是刻意分开调用的，因此即使不执行此操作也不会产生任何费用：

- 使用 [一次导入多个页面](#import-many-pages-at-once) 导入您想要的新页面；
- 使用 [刷新网站上的每个页面](#refresh-every-page-on-a-website) 重新读取您已有的页面。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `baseUrl` | 是 | 网站上的任何地址，或仅主机名。 |
| `maxPages` | 否 | 探索页面的上限。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'
```

**响应**

```json
{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}
```

| 字段 | 类型 | 描述 |
|---|---|---|
| `discovered` | integer | 网站上总共找到的页面数量。 |
| `new_pages` | array | 尚未进入您知识库的页面。不会为您排队任何内容 — 请导入您想要的页面。 |
| `new_urls_queued` | integer | 始终为 `0`。保留此项是为了向后兼容；此端点从不排队任何内容。 |
| `existing_refresh_queued` | integer | 从该网站已导入并准备好重新读取的页面数量。此调用不会排队任何内容。 |
| `batch_id` | string | 仅在创建批处理时出现。 |

与发现功能一样，此功能采用软失败机制：无法读取的网站仍会返回 `200`，其中 `success: false` 为空，`new_pages` 为空，且 `error` 为空。缺少或空的 `baseUrl` 会返回 `400`。

---

## 刷新网站上的每个页面

`POST /kb-sources/trigger-domain-refresh`

重新读取您已从网站导入的每个页面，以便其常见问题解答（FAQ）遵循网站的当前内容：已更改的部分会更新，新增的部分会添加，已删除的部分会被移除。

此操作会排队任务并立即返回。随后可使用 [跟踪网站刷新](#track-a-website-refresh) 进行跟踪，并使用 [停止网站刷新](#stop-a-website-refresh) 停止任务。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `baseUrl` | 是 | 网站上的任何地址，或仅主机名。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'
```

**响应**

```json
{
  "success": true,
  "queued": 249
}
```

---

## 跟踪网站刷新

`GET /kb-sources/domain-refresh-status`

网站刷新的进度，以便您可以显示类似“221 / 249”的进度信息。

**查询参数**

| 参数 | 必填 | 描述 |
|---|---|---|
| `baseUrl` | 是 | 网站上的任何地址，或仅主机名。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"
```

**响应**

```json
{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}
```

当该网站没有正在进行的刷新时，`job` 为 `null`。目前已完成的页面数为 `total` 减去 `pending`。任务 `status` 的状态为 `refreshing`（仍在处理页面）、`deduplicating`（最后的清理阶段），或者最终的 `completed`、`failed` 和 `cancelled`。请保留 `domainBatchId` — 这是您传递给取消端点的值。

缺少或空的 `baseUrl` 会返回 `400`。

---

## 停止网站刷新

`POST /kb-sources/refresh-domain/cancel`

停止仍在处理页面的网站刷新。已完成的页面将保留其更新后的内容；未开始的页面将被丢弃，而正在重新读取的页面将恢复到之前的状态。

**请求字段**

| 字段 | 必填 | 说明 |
|---|---|---|
| `jobId` | 是 | 由 [跟踪网站刷新](#track-a-website-refresh) 返回的 `domainBatchId`。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'
```

**响应**

```json
{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `status` | string | 此调用后的刷新状态：`cancelled`、`deduplicating`、`completed` 或 `failed`。 |
| `cancelled_units` | integer | 取消时仍未完成的工作量。重复取消时返回 `0`。 |
| `sources_reset` | integer | 从处理中撤回并返回 `ready` 的页面数。 |
| `sources_cancelled` | integer | 此刷新中仍处于队列中且现已被取消的全新页面数。 |

取消两次是无害的——第二次调用会报告相同的最终状态。一旦刷新进入清理阶段，它就无法再被停止，响应将返回 `success: false` 和 `reason: "already_finalizing"`。缺失 `jobId` 将返回 `400`，而不在您账户中的作业将返回 `404`。

---

## 刷新单个来源

`POST /kb-sources/{sourceId}/refresh`

重新读取您已导入的一个网页，并使其常见问题解答（FAQ）与该页面的当前内容保持一致：更新已更改的部分，添加新的部分，并删除已移除的部分。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"
```

**响应** — `202 Accepted`

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}
```

轮询该来源，直到其状态离开 `queued` 和 `processing`。不在您账户中的来源 ID 将返回 `404`。

---

## 选择最相关的页面

`POST /kb-sources/select-relevant-pages`

要求 AI 从候选列表中选出最能描述业务的五个页面——用于从网站生成营销活动手册时。此操作会消耗积分。

**请求字段**

| 字段 | 必填 | 说明 |
|---|---|---|
| `urls` | 是 | 供选择的候选页面地址，通常来自页面发现。 |
| `homeUrl` | 是 | 网站主页，用作选择的上下文。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'
```

**响应**

```json
{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}
```

这是一个辅助工具，而非资源：在失败时它仍会响应 `200`，包含 `success: false`、一个空的 `pages` 列表以及一条 `error` 消息。

---

## 知识组

**知识组**是一个已命名的常见问题解答（FAQ）集合——例如“配送与退货”、“入职引导”——您可以在一次调用中将其应用于智能体或营销活动。该组持有的是引用而非副本：FAQ 本身保留在您的单一库中，因此使用 [FAQs API](faqs.md) 编辑其中一个 FAQ 时，它在所有使用该 FAQ 的地方都会同步更新。

应用一个组只会**添加**缺失的内容，因此重复应用同一个组不会产生负面影响，第二次调用时 `added_count` 会返回 `0`。

---

## 创建知识组

`POST /kb-groups`

创建一个组。它初始为空——请使用 [将 FAQ 添加到组](#add-a-faq-to-a-group) 向其中添加 FAQ。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `name` | 是 | 组的名称。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]
```

**响应** — `201 Created`

```json
{
  "success": true,
  "group_id": "kbg_abc123"
}
```

---

## 重命名知识组

`PUT /kb-groups/{groupId}`

更改组的名称。其中的 FAQ 不受影响。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `name` | 是 | 组的新名称。 |

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'
```

**响应**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}
```

---

## 删除知识组

`DELETE /kb-groups/{groupId}`

删除该组。仅移除该集合——其中的 FAQ 会保留在您的库中，且该组之前已应用到的任何对象仍会保留这些 FAQ。

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"
```

**响应**

```json
{
  "success": true
}
```

---

## 将常见问题解答 (FAQ) 添加到组

`POST /kb-groups/{groupId}/faqs`

将现有的 FAQ 放入组中。这只会更改捆绑包，而不会自行将 FAQ 附加到任何智能体 (Agent)；请为此应用该组。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `faq_id` | 是 | 要添加的 FAQ 的 ID。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'
```

**响应**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}
```

---

## 从组中移除 FAQ

`DELETE /kb-groups/{groupId}/faqs/{faqId}`

将 FAQ 从组中移除。FAQ 本身不会被删除，且已经应用了该组的智能体将保留它。

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"
```

**响应**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}
```

---

## 将组应用到智能体

`POST /kb-groups/{groupId}/apply-to-agent`

通过一次调用将组中的每个 FAQ 添加到 AI 智能体的知识库中——这是为新智能体提供您已整理好的知识库的快捷方式。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `agent_id` | 是 | 要应用该组的 AI 智能体的 ID。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]
```

**响应**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}
```

`added_count` 是实际添加的 FAQ 数量——当组为空或已应用时为 `0`。

---

## 将组应用到营销活动

`POST /kb-groups/{groupId}/apply-to-campaign`

上述调用的经典营销活动版本。在基于智能体的账户上，请改用 [将组应用到智能体](#apply-a-group-to-an-agent)。

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `campaign_id` | 是 | 要应用该组的营销活动 ID。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'
```

**响应**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}
```

---

## 知识库 API 错误

这些端点返回标准的错误封装：

```json
{
  "success": false,
  "error": "Knowledge base source not found."
}
```

| 状态 | 在知识库端点上发生时 |
|---|---|
| `400` | 缺少必填字段或字段无效 — 例如 `url` 为空、缺少 `baseUrl` 或 `jobId`、批量导入中超过 100 个 URL、批量删除中超过 2,000 个 ID，或文件类型无法读取。 |
| `402` | 积分不足，无法运行导入。请充值后再试。 |
| `403` | `storage_path` 超出了您自己的上传文件夹范围 — 或者您的套餐不包含 API 访问权限。 |
| `404` | 未找到源、组、常见问题解答 (FAQ)、智能体 (Agent)、营销活动或刷新任务 — 它可能不存在，或者属于其他账户。 |

> **软失败不是错误。** 当无法读取网站时，发现功能（`discover-pages`、`refresh-domain`）和页面选择助手会以 `200` 响应，并附带 `success: false` 和 `error` 消息，而不是使请求失败。在读取数据之前，请务必检查 `success`。

每个端点都可能返回的共享代码 — `401`, `403`（您的套餐不包含 API 访问权限）, `429`（速率限制）和 `500` — 及其重试指南列在 [错误与分页](errors-and-pagination.md) 中。

---

## 相关内容

- [FAQs API](faqs.md) — 读取、编辑和链接您的源生成的常见问题解答。
- [管理常见问题解答](../ai-automation/faq-management.md) — 仪表板中的相同知识库。
- [AI 智能体](../ai-agents/ai-agents.md) — 您附加源和组的智能体。
- [API 访问](../integrations/api-access.md) — 生成您的 API 密钥。
- [身份验证](authentication.md) — 传递密钥的所有方式。