> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # 获取数据源列表 > 按数据源 ID 升序列出知识库的数据源。每个数据源附带其定时同步设置、最近一次完成的同步或导入，以及当前运行；没有正在进行的运行时，改为附带最近一次同步。 数据源的删除请求一经受理，该数据源就不再出现在此列表中。 如何启动和跟踪同步，详见 [同步数据源与定时同步](/zh/api-reference/guides/knowledge-base#sync-and-schedule-sources)。 ## OpenAPI ````yaml /zh/api-reference/openapi_service.json get /knowledge-fs/spaces/{knowledge_base_id}/sources openapi: 3.0.1 info: description: 用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。 title: Dify 服务 API version: 1.0.0 servers: - description: Dify 服务 API 的基础 URL。自部署时，替换为你的 API 基础 URL。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API 基础 URL 的主机与路径，不含 `https://` 前缀。 security: - ApiKeyAuth: [] tags: - description: 与聊天消息和交互相关的操作。 name: 对话消息 - description: 文件上传和预览操作。 name: 文件操作 - description: 终端用户信息相关操作。 name: 终端用户 - description: 用户反馈操作。 name: 消息反馈 - description: 与管理会话相关的操作。 name: 会话管理 - description: 文字转语音和语音转文字操作。 name: 语音与文字转换 - description: 获取应用设置和信息的操作。 name: 应用配置 - description: 与管理标注直接回复相关的操作。 name: 标注管理 - description: 暂停等待人工输入的工作流恢复操作。 name: 人工介入 - description: 用于执行和管理工作流的操作。 name: 工作流运行 - description: 文本生成相关操作。 name: 文本生成消息 - description: 用于管理知识库的操作，包括创建、配置和检索。 name: 知识库 - description: 用于在知识库中创建、更新和管理文档的操作。 name: 文档 - description: 用于管理分段和子分段的操作。 name: 分段 - description: 用于管理知识库元数据字段和文档元数据值的操作。 name: 元数据 - description: 用于管理知识库标签和标签绑定的操作。 name: 标签 - description: 用于获取可用模型的操作。 name: 模型 - description: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。 name: 知识流水线 - description: 向知识库提问，并流式返回回答。 name: 查询 - description: 查看一次查询检索到了什么，以及原因。 name: 查询记录 - description: 在后台运行研究问题，并获取其结果。 name: 研究任务 - description: 读取知识库中的文档及其文件、修订版本和分段，并用元数据标注文档。 name: 文档与分段 - description: 跟踪、取消或重试索引，并列出知识库的后台任务。 name: 索引任务 - description: 跟踪文档文件、一批文件或数据源的删除，直到完成。 name: 删除作业 - description: 管理为知识库提供内容的数据源，以及它们的定时同步设置和连接。 name: 数据源 - description: 立即同步数据源，导入网站页面或提供商条目，并跟踪、取消或重试运行。 name: 数据源同步与导入 - description: 读取和更改知识库的模型与检索设置，并跟踪更改触发的迁移。 name: 设置 paths: /knowledge-fs/spaces/{knowledge_base_id}/sources: get: tags: - Sources summary: 获取数据源列表 description: >- 按数据源 ID 升序列出知识库的数据源。每个数据源附带其定时同步设置、最近一次完成的同步或导入，以及当前运行；没有正在进行的运行时，改为附带最近一次同步。 数据源的删除请求一经受理，该数据源就不再出现在此列表中。 如何启动和跟踪同步，详见 [同步数据源与定时同步](/zh/api-reference/guides/knowledge-base#sync-and-schedule-sources)。 operationId: listSources parameters: - description: >- 知识库 ID：即知识库 **API 访问** 对话框中所示服务 API 端点的最后一段（`…/knowledge-fs/spaces/`），也是地址栏中 `/datasets/new/` 之后的那一段。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: 游标，取自上一页的 `next_cursor`。 in: query name: cursor required: false schema: maxLength: 1000 minLength: 1 type: string - description: 每页数据源数。 in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: success: summary: 响应示例 value: data: - connection_id: c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f created_at: '2026-09-01T08:00:00Z' credential_configured: null id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90 knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d last_synced_at: '2026-09-05T10:12:00Z' metadata: client_request_id: source-20260907-0001 providerKind: website tenantId: 2f1e0d9c-8b7a-4695-8473-2a1b0c9d8e7f name: Docs site permission_scope: [] status: active sync_policy: created_at: '2026-09-01T08:05:00Z' custom_interval_seconds: null enabled: true expected_source_version: 7 id: 8e7d6c5b-4a39-4f28-9e17-0d1c2b3a4f5e knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d mode: interval next_run_at: '2026-09-06T10:00:00Z' revision: 2 source_id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90 updated_at: '2026-09-05T10:00:00Z' sync_workflow: canceled_at: null checkpoint: source-committed completed_at: '2026-09-05T10:12:00Z' created_at: '2026-09-05T10:00:00Z' cursor: >- ss1:eyJmaW5nZXJwcmludCI6IjgxZDk5OWY4YjI4ZDZhMGFlMTVmNjQxYzE2NjE3ZWNlMTBjYTcxMzE3OWU1MmVhMTYwODYyMzExMDcyYmQ4YmUiLCJraW5kIjoid2Vic2l0ZSIsIm9mZnNldCI6MCwicGhhc2UiOiJlb2YiLCJwcm9ncmVzc0NvbXBsZXRlZCI6NDUsInByb2dyZXNzVG90YWwiOjQ1fQ execution_attempts: 1 failure: null id: d4c3b2a1-6f5e-4d7c-8b9a-0f1e2d3c4b5a kind: sync knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d last_error_code: null max_execution_attempts: 5 progress_completed: 45 progress_failed: 0 progress_skipped: 0 progress_total: 45 source_id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90 state: completed updated_at: '2026-09-05T10:12:00Z' type: web updated_at: '2026-09-03T09:20:00Z' uri: https://docs.example.com version: 7 next_cursor: null schema: properties: data: description: 本页的数据源。 items: $ref: '#/components/schemas/KnowledgeBaseSource' type: array next_cursor: description: 下一页的游标，最后一页时为 `null`。将其作为 `cursor` 传回。 nullable: true type: string type: object description: 一页数据源。 '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - limit type: less_than_equal description: >- - `knowledge_fs_invalid_request`：`cursor` 为空或超过 1,000 个字符、`limit` 不在 1～100 范围内，或查询字符串含有不支持的参数。`violations` 列出每个出错的字段。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：缺少 `Authorization` 请求头，或密钥无法识别、不是知识库 API 密钥。 - `knowledge_fs_invalid_credential`：密钥有效，但其所属工作空间中没有此 ID 的知识库，或该密钥未关联任何工作空间。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`：该密钥的访问范围限定为其他知识库、此知识库已关闭 **API 访问**，或知识库未处于活动状态。 - `knowledge_fs_access_denied`：该密钥无权访问此知识库的内容。 - `forbidden`：在 Dify Cloud 上，工作空间已达到其订阅套餐的知识库请求频率限制。所有调用都计入，读取操作也不例外。 '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: |- - `knowledge_fs_resource_not_found`：无法识别该知识库 ID。 - `not_found`：当前部署已关闭 Agent 知识库功能。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: '- `knowledge_fs_upstream_unavailable`：未能及时收到响应，或无法读取响应。稍候重试。' '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`：此工作空间尚未配置 Agent 知识库功能、当前部署不提供此操作，或在请求鉴权期间该密钥对此知识库的访问权限发生了变化。 - `knowledge_fs_operation_unavailable`：暂时无法处理该请求。按 `failure.retryPolicy` 处理。 - `knowledge_fs_operation_unavailable`：该请求未能凑满一页此密钥可读取的数据源。 components: schemas: KnowledgeBaseSource: properties: connection_id: description: 数据源获取凭据所用的连接。将其他数据源绑定到同一连接时，将此值作为 `connectionId` 传入。未绑定时为 `null`。 nullable: true type: string created_at: description: 创建时间，ISO 8601 格式。 type: string credential_configured: description: 数据源持有自己的凭据引用时为 `true`。未持有时为 `null`，例如绑定到连接的数据源。 nullable: true type: boolean id: description: 数据源 ID。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string last_synced_at: description: >- 最近一次已完成的同步（`completed` 或 `zero_results`）或已完成导入的完成时间。仅 [获取数据源列表](/zh/api-reference/sources/list-sources) 设置此字段。其他操作中以及数据源从未同步时为 `null`。 nullable: true type: string metadata: description: >- 提供商设置，以及由服务端管理的同步或页面选择数据。可能包含提供商标识和 `parameters`；由连接管理的设置不一定出现在此处。凭据类的键已移除。创建其他数据源时，不要复制整个对象。 type: object name: description: 显示名称。 type: string permission_scope: description: 读取此数据源所需的内容访问范围。列表为空表示在知识库内不额外限制内容，但知识库本身的授权仍然适用。 items: type: string type: array status: description: >- `active`、`syncing`、`error` 或 `disabled`。大多数操作返回存储的值。[获取数据源列表](/zh/api-reference/sources/list-sources) 根据最近一次同步运行推导该值： - 运行为 `failed` 或 `canceled`：`error` - 运行为 `completed` 或 `zero_results`：`active` - 有进行中的运行：`syncing` `disabled` 永远不会被覆盖。 type: string sync_policy: allOf: - $ref: '#/components/schemas/KnowledgeBaseSyncPolicy' description: >- 数据源的定时同步设置。仅 [获取数据源列表](/zh/api-reference/sources/list-sources) 设置此字段。其他操作中以及没有定时同步时为 `null`。可通过 [获取同步策略](/zh/api-reference/sources/get-sync-policy) 单独读取，通过 [更新同步策略](/zh/api-reference/sources/update-sync-policy) 修改。 nullable: true sync_workflow: allOf: - $ref: '#/components/schemas/KnowledgeBaseSourceRun' description: >- 数据源当前进行中的同步或导入运行（`crawl-import`、`online-document-import` 或 `online-drive-import`），没有则为最近一次同步运行。[获取数据源列表](/zh/api-reference/sources/list-sources) 在有运行正在进行或运行晚于数据源记录时设置此字段。[更新数据源](/zh/api-reference/sources/update-source) 在该调用启动了同步时设置此字段。其他情况下为 `null`。抓取预览以及从抓取预览发起的导入不会出现在此处。 要跟踪某次运行，用其 `id` 调用 [获取数据源运行](/zh/api-reference/source-syncs-and-imports/get-source-run)。 nullable: true type: description: >- `web`（网站抓取）、`connector`（在线文档或在线云盘）、`upload` 或 `object-storage`。 `connector` 数据源的 `metadata.providerKind` 为 `online-document` 或 `online-drive`，`web` 数据源则为 `website`。 `upload` 和 `object-storage` 数据源由 Dify 填充。 type: string updated_at: description: 最后变更时间，ISO 8601 格式。 type: string uri: description: '`web` 数据源为抓取的根 URL。Dify 创建的连接器数据源为 `connector://`。' type: string version: description: >- 数据源版本，每次写入都会递增。调用 [更新数据源](/zh/api-reference/sources/update-source) 时将其作为 `expectedVersion` 传入，调用 [删除数据源](/zh/api-reference/sources/delete-source) 时作为 `expectedRevision` 传入，调用 [更新同步策略](/zh/api-reference/sources/update-sync-policy) 时作为 `expectedSourceVersion` 传入。 type: integer type: object KnowledgeBaseSyncPolicy: properties: created_at: description: 创建时间，ISO 8601 格式。 type: string custom_interval_seconds: description: '`mode: custom` 时的同步间隔，单位为秒。其他模式为 `null`。' nullable: true type: integer enabled: description: '是否运行定时同步。`mode: manual` 时始终为 `false`。' type: boolean expected_source_version: description: 定时同步绑定的数据源 `version`。 type: integer id: description: 同步策略 ID，更新后保持不变。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string mode: description: >- `manual`（不安排定时同步）、`interval`（每 24 小时）或 `custom`（按 `custom_interval_seconds` 的间隔）。 type: string next_run_at: description: 下次定时同步的时间，ISO 8601 格式。没有安排时为 `null`。 nullable: true type: string revision: description: >- 定时同步的修订版本。调用 [更新同步策略](/zh/api-reference/sources/update-sync-policy) 时将其作为 `expectedRevision` 传入。每次更新以及每次定时同步开始时都会递增。 type: integer source_id: description: 定时同步所属的数据源。 type: string updated_at: description: 最后变更时间，ISO 8601 格式。定时同步开始时也会更新。 type: string type: object KnowledgeBaseSourceRun: properties: canceled_at: description: 取消运行的时间。仅当 `state` 为 `canceled` 时有值，否则为 `null`。 nullable: true type: string checkpoint: description: >- 运行已到达的最后一步：`queued`、`provider-read`、`preview-staged`、`selection-frozen`、`materialized`、`cleanup-staging` 或 `source-committed`。无论运行停在哪个检查点，[重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run) 都会从头开始运行。 type: string completed_at: description: >- 运行结束（`completed`、`zero_results`、`failed` 或 `canceled`）的时间，ISO 8601 格式。运行期间为 `null`。 nullable: true type: string created_at: description: 创建时间，ISO 8601 格式。 type: string cursor: description: 运行恢复时所用的提供商游标。运行尚未翻页时为 `null`。 nullable: true type: string execution_attempts: description: >- 工作进程领取该运行的次数，包括 [重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run) 之后的领取，重试不会重置该值。 type: integer failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: >- `state` 为 `failed` 时的错误详情。其中 `stage` 为失败时运行的 `checkpoint`，`traceId` 为运行 ID。其他情况下为 `null`。 nullable: true id: description: >- 运行 ID，可传给 [获取数据源运行](/zh/api-reference/source-syncs-and-imports/get-source-run)、[取消数据源运行](/zh/api-reference/source-syncs-and-imports/cancel-source-run) 或 [重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run)。 type: string kind: description: >- 运行的类型： - `sync`：由 [同步数据源](/zh/api-reference/source-syncs-and-imports/sync-source)、[更新数据源](/zh/api-reference/sources/update-source)、定时同步或 Dify 发起。 - `crawl-preview`：由 [预览网站抓取](/zh/api-reference/source-syncs-and-imports/preview-website-crawl) 发起。[导入所选页面](/zh/api-reference/source-syncs-and-imports/import-selected-pages) 从该预览导入时，类型保持不变。 - `crawl-import`：由 [导入网站页面](/zh/api-reference/source-syncs-and-imports/import-website-pages) 发起。 - `online-document-import`、`online-drive-import`：由 [导入数据源条目](/zh/api-reference/source-syncs-and-imports/import-source-items) 发起。 在 Dify 中添加或编辑数据源时，Dify 也会发起预览和导入。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string last_error_code: description: '`state` 为 `failed` 时为 `failure.code` 的值，否则为 `null`。' nullable: true type: string max_execution_attempts: description: >- `execution_attempts` 的上限。达到上限后，[重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run) 返回 `409`。 type: integer progress_completed: description: 已处理完的项数，包括同步时检查过但未变化的项。 type: integer progress_failed: description: 数据源运行始终为 `0`：任一项失败都会导致整个运行失败。 type: integer progress_skipped: description: 数据源运行始终为 `0`。 type: integer progress_total: description: >- 运行预计处理的项数：导入请求的页面或条目数、抓取预览目前已暂存的页面数，或同步列出数据源条目后的条目数。确定之前为 `null`。 [导入网站页面](/zh/api-reference/source-syncs-and-imports/import-website-pages) 的运行抓取 URL 期间，`progress_completed` 和 `progress_total` 都统计目前已抓取的页面数。所有 URL 抓取完成后，进度从 `0` 重新开始计，总数变为 URL 的数量。 nullable: true type: integer source_id: description: 运行所属的数据源。 nullable: true type: string state: description: >- 运行的进度。 进行中的状态： - `queued`：等待工作进程处理 - `crawling`：抓取预览正在获取页面 - `preview_ready`：抓取预览正在等待 [导入所选页面](/zh/api-reference/source-syncs-and-imports/import-selected-pages) 或 [取消数据源运行](/zh/api-reference/source-syncs-and-imports/cancel-source-run) - `importing`：正在导入并索引条目 - `syncing`：正在刷新数据源的文档 终态： - `completed`：所有条目均已导入或刷新、完成索引并生效 - `zero_results`：抓取预览未找到任何页面 - `failed`：详见 `failure` - `canceled` `failed` 或 `canceled` 之后，[重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run) 会再次执行该运行，[同步数据源](/zh/api-reference/source-syncs-and-imports/sync-source) 则会发起新的同步。 type: string updated_at: description: 最后变更时间，ISO 8601 格式。 type: string type: object KnowledgeBaseErrorDetails: properties: action: description: >- 建议的下一步操作（如有）：`configure_model`、`configure_parser`、`configure_source`、`contact_admin`、`reupload` 或 `retry`。不适用时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: string category: description: >- 失败类别：`authorization`、`canceled`、`configuration`、`conflict`、`dependency`、`internal`、`not_found`、`rate_limit`、`timeout` 或 `validation`。 type: string code: description: >- 稳定的错误码，采用大写蛇形命名，例如 `KNOWLEDGE_FS_CONFLICT` 或 `SOURCE_CREDENTIAL_TEST_FAILED`。 type: string message: description: 错误码或失败类别对应的公开消息。不会暴露提供商的错误详情。 type: string parameters: additionalProperties: true description: >- 描述失败细节的值，最多 8 个，键取自 `attempt`、`currentRowVersion`、`documentCount`、`expectedRowVersion`、`fileSizeBytes`、`limit`、`maxFileSizeBytes`、`maxItems`、`modelType`、`providerKind`、`retryAfterSeconds` 和 `status`。没有时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: object retryPolicy: description: >- 重试是否有用：`automatic`（服务会自动重试）、`manual`（需自行重试）、`after_configuration`（先在 Dify 中修正知识库配置）或 `never`（需修改请求）。 type: string stage: description: >- 失败所在的阶段，例如 `query_generation` 或 `credential-test`。不适用时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: string traceId: description: 联系管理员时需提供的参考编号。在包含失败详情的成功响应中可能为 `null`，在 HTTP 错误响应体中可能不出现。 nullable: true type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.