agentic_huge_data_base / wiki
页面 Cognee · 13.3 REST 接口端点·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 13.3

13.3 · REST 接口端点（REST API Endpoints）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节13.3 状态全文译文 模块测试、发布与运维、接口与服务契约、图谱与关系、认证、权限与安全
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节REST API Endpoints 上一章13.2 下一章13.4
源码线索
  • cognee/__init__.py
  • cognee/api/DTO.py
  • cognee/api/client.py
  • cognee/api/v1/add/routers/get_add_router.py
  • cognee/api/v1/cognify/routers/get_cognify_router.py
  • cognee/api/v1/datasets/routers/get_datasets_router.py
  • cognee/api/v1/delete/routers/get_delete_router.py
  • cognee/api/v1/memify/routers/get_memify_router.py
  • cognee/api/v1/permissions/routers/get_permissions_router.py
  • cognee/api/v1/responses/routers/get_responses_router.py
模块标签
  • 测试、发布与运维
  • 接口与服务契约
  • 图谱与关系
  • 认证、权限与安全
  • 界面与交互

章节正文

REST 接口端点

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/13.3-rest-api-endpoints

REST 接口端点

相关源文件

本章引用的主要源码文件：

  • cognee/__init__.py
  • cognee/api/DTO.py
  • cognee/api/client.py
  • cognee/api/v1/add/routers/get_add_router.py
  • cognee/api/v1/cognify/routers/get_cognify_router.py
  • cognee/api/v1/datasets/routers/get_datasets_router.py
  • cognee/api/v1/delete/routers/get_delete_router.py
  • cognee/api/v1/memify/routers/get_memify_router.py
  • cognee/api/v1/permissions/routers/get_permissions_router.py
  • cognee/api/v1/responses/routers/get_responses_router.py
  • cognee/api/v1/search/routers/get_search_router.py
  • cognee/api/v1/settings/routers/get_settings_router.py
  • cognee/api/v1/sync/routers/get_sync_router.py
  • cognee/api/v1/update/routers/get_update_router.py
  • cognee/api/v1/users/routers/get_visualize_router.py
  • cognee/api/v1/visualize/__init__.py
  • cognee/api/v1/visualize/visualize.py
  • cognee/shared/utils.py
  • cognee/tests/test_telemetry.py
  • cognee/tests/unit/processing/utils/utils_test.py

本文档提供了 Cognee 通过 FastAPI 服务器暴露的 REST API 端点的完整参考。该 API 支持通过 HTTP 访问 Cognee 的知识图谱能力，包括数据入库、图谱处理、语义搜索以及多租户访问控制。

有关 Python SDK 接口的信息，请参见 Python API 参考。有关 AI 智能体使用的模型上下文协议（MCP）服务器，请参见 AI 智能体的 MCP 服务器。

概述

REST API 服务器使用 FastAPI 实现，是 Cognee Web 前端和外部集成的主要接口。所有 API 端点都以 /v1/ 为前缀（在客户端配置中通过 /api/v1/ 路由），并且在启用 REQUIRE_AUTHENTICATION 时，同时支持 Bearer 令牌和基于 Cookie 的认证。

来源： cognee/api/client.py:1-51, cognee/api/client.py:115-115

服务器架构

FastAPI 应用程序 app 配置了一个 lifespan 上下文管理器，用于编排系统的启动和关闭。在启动期间，它会运行数据库迁移并初始化默认用户。在关闭期间，它会清除数据库引擎缓存，以确保预写日志（WAL）检查点完成，防止数据损坏。

代码实体空间：API 初始化

下图将 FastAPI 应用程序的设置映射到特定的路由器函数和初始化逻辑。

Cognee · 代码实体空间：API 初始化 · 图 1
Cognee · 代码实体空间：API 初始化 · 图 1

来源： cognee/api/client.py:75-114, cognee/api/client.py:18-50

认证与安全

API 支持两种认证机制：Bearer 令牌和 API 密钥请求头。安全性通过 get_authenticated_user 依赖项强制执行。

OpenAPI 安全方案

服务器在 custom_openapi 函数中配置了两种认证类型的 OpenAPI：

安全方案类型位置名称
BearerAuthHTTP请求头Authorization: Bearer
ApiKeyAuthapiKey请求头X-Api-Key

来源： cognee/api/client.py:140-176, cognee/modules/users/methods/get_authenticated_user.py:51-51

CORS 配置

CORS 通过 CORS_ALLOWED_ORIGINS 环境变量进行配置。如果未设置，则默认为 UI_APP_URL（通常为 http://localhost:3000）。

来源： cognee/api/client.py:119-135

核心 API 端点

数据入库：/v1/add

/add 端点接受文件上传、URL 或 GitHub 仓库 URL。它使用 cognee_add 函数启动入库管线。

参数类型描述
dataList[UploadFile]要入库的文件或二进制数据。
datasetNameOptional[str]目标数据集的名称。
datasetIdOptional[UUID]现有数据集的 UUID。
node_setOptional[List[str]]图谱的分组标识符。
run_in_backgroundbool是否异步运行。

来源： cognee/api/v1/add/routers/get_add_router.py:39-66, cognee/api/v1/add/routers/get_add_router.py:104-113

知识图谱处理：/v1/cognify

/cognify 端点将入库的数据转换为知识图谱。它支持深度分析、实体提取和关系检测。

Cognee · v1 · 图 2
Cognee · v1 · 图 2

来源： cognee/api/v1/cognify/routers/get_cognify_router.py:41-68, cognee/api/v1/cognify/routers/get_cognify_router.py:85-135

搜索：/v1/检索

支持使用各种 SearchType 策略在图谱中进行语义搜索。

POST /v1/search - 执行搜索：

  • search_type：策略（例如 GRAPH_COMPLETION、CHUNKS、RAG_COMPLETION）。
  • query：搜索字符串。
  • top_k：结果数量（默认：10）。
  • only_context：如果为 true，则返回上下文而不包含大语言模型（LLM）的补全结果。

来源： cognee/api/v1/search/routers/get_search_router.py:25-40, cognee/api/v1/search/routers/get_search_router.py:106-135

记忆操作：记住与回忆

这些端点代表了用于持久化上下文增强的 V2 面向记忆的 API。

  • /v1/remember：通过 cognee.remember 将信息存储到持久化记忆中。
  • /v1/recall：根据上下文通过 cognee.recall 检索信息。
  • /v1/improve：通过 cognee.improve 优化现有的图谱结构或摘要。
  • /v1/forget：通过 cognee.forget 移除记忆条目。

来源： cognee/api/client.py:29-32, cognee/__init__.py:48-48

数据集管理
端点方法用途
/v1/datasetsGET通过 get_all_user_permission_datasets 列出数据集。
/v1/datasetsPOST通过 create_authorized_dataset 创建/检索数据集。
/v1/datasets/{dataset_id}DELETE通过 delete_dataset 移除数据集及其数据。

来源： cognee/api/v1/datasets/routers/get_datasets_router.py:86-125, cognee/api/v1/datasets/routers/get_datasets_router.py:126-177, cognee/api/v1/datasets/routers/get_datasets_router.py:193-210

权限与多租户

API 通过主体（用户或角色）提供对数据集访问的细粒度控制。

  • 授予权限：POST /v1/permissions/datasets/{principal_id} 调用 authorized_give_permission_on_datasets。
  • 撤销权限：DELETE /v1/permissions/datasets/{principal_id} 调用 authorized_revoke_permission_on_datasets。
  • 角色管理：POST /v1/permissions/roles 通过 create_role_method 创建角色。

来源： cognee/api/v1/permissions/routers/get_permissions_router.py:36-87, cognee/api/v1/permissions/routers/get_permissions_router.py:89-130, cognee/api/v1/permissions/routers/get_permissions_router.py:132-173

遥测与可观测性

Cognee 通过 send_telemetry 跟踪 API 使用情况。它收集匿名的机器级 ID（persistent_id）和项目级 ID（anonymous_id），以关联活动而不损害隐私。

来源： cognee/shared/utils.py:49-105, cognee/shared/utils.py:176-190

错误处理与状态码

API 使用自定义异常处理器将内部错误映射到 HTTP 状态码。

状态码用途
400校验错误或缺少参数（例如，datasetId 和 datasetName 都缺失）。
403认证失败或权限被拒绝。
409删除或管线运行期间的冲突或操作错误。
500内部服务器错误或管线故障（PipelineRunErrored）。

来源： cognee/api/client.py:179-195, cognee/api/v1/add/routers/get_add_router.py:95-101, cognee/api/v1/add/routers/get_add_router.py:115-123