Docs
文档目录

项目 API 通用约定(认证与访问)

运行示例前,将 <APPBASE_ENDPOINT_WITH_V1> 替换为目标环境的 API 地址,并核对项目及凭据属于同一环境。

本文定义 Agentbase 项目级全部功能 REST API 的公共通信协议与治理约定:涵盖服务与资源边界、完整请求头矩阵、API Key Scopes 权限矩阵、服务端/客户端认证流(API Key / Session / JWT / Gateway Key)、请求与响应格式、分页查询文法、限流与幂等机制、统一错误信封及可直接运行的 cURL 调用示例。

服务与资源边界

Agentbase REST API 按职责面划分为「项目功能面(Project API)」、「智能体与网关数据面(AI Gateway / LLM Gateway / Agent Runtime)」以及「控制台管理面(Console API)」。本目录(apis/)聚焦于项目下全部业务功能的访问接口,其核心边界如下:

资源与基础路径

认证与权限

完整请求头矩阵

请求头名称必填性适用场景示例值语义说明
X-Appwrite-Project必填全部项目级 APIenterprise-ai-hub-210标识当前请求归属的 Agentbase 项目 ID
X-Appwrite-Key服务端必填服务端 API / 后台任务<APPBASE_API_KEY>项目级 API Key(在控制台「项目设置 -> API Keys」中签发)
X-Appwrite-JWT客户端可选代理用户身份访问eyJhbGciOiJIUzI1NiIs...短时用户 JWT 令牌,服务端或 BFF 代最终用户发起受 $permissions 约束的请求时使用
X-Appwrite-Session客户端可选无 Cookie 环境会话66a9d9b804d8e...显式传递用户登录 Session Secret(等价于 a_session_<projectId> Cookie)
Authorization网关可选AI Gateway / LLM GatewayBearer <GATEWAY_KEY>Bearer 令牌;按接口分别使用模型网关或 AI 网关工具凭证
X-Appwrite-Locale可选国际化与错误提示zh-CN指定本地化返回语言(遵循 ISO 639-1 / BCP-47,见 Locale API)
X-Appwrite-Response-Format可选跨版本格式兼容1.6.0指定响应体的向下兼容序列化格式版本
If-Match / If-None-Match可选乐观并发控制(CAS)"v3" 或 "1"用于知识库、记忆系统或配置的并发条件更新校验
Idempotency-Key可选异步写入与任务提交req_20261022_001幂等键(最长 128 字符),防止网络超时重发导致重复扣费或重复入库

API Key Scopes 权限矩阵

创建项目 API Key 时须遵循最小权限原则勾选所需的 Scope。各功能模块所需的核心 Scope 映射如下:

业务模块只读 Scope (*.read)写入/管理 Scope (*.write / 专项)兼容别名与特殊说明
用户与团队 (Users / Teams)users.read, teams.readusers.write, teams.write, sessions.writeusers.write 可签发 Custom Token(/users/{userId}/tokens)
数据库 (Databases)databases.read, tables.read, columns.read, indexes.read, rows.readdatabases.write, tables.write, columns.write, indexes.write, rows.write兼容旧版文档模型别名:collections.read/write、attributes.read/write、documents.read/write
存储与文件令牌 (Storage / Tokens)buckets.read, files.read, tokens.readbuckets.write, files.write, tokens.write文件下载/预览在 fileSecurity=true 时支持 ?token=<secret> 免 Header 访问
知识库与词库 (Knowledge Base)knowledgebases.read, lexicons.readknowledgebases.write, lexicons.write词库(Lexicons)独立受 lexicons.read / lexicons.write 控制
记忆系统 (Memory)memories.readmemories.write, memories.delete, memories.export, memories.share覆盖长期记忆、用户画像、上下文做梦(Dreaming)与经验技能蒸馏(Distillation)
模型与 AI 网关 (LLM Gateway / AI Gateway)llm-gateway.providers.read, llm-gateway.keys.read, aiGateway.readllm-gateway.providers.write, llm-gateway.keys.write, aiGateway.write模型推理使用 llm-gateway.execute;AI 网关工具使用对应网关凭据
智能体运行时 (Agent Runtime)agent-runtime.read, projects.readagent-runtime.write, agent-runtime.project项目级智能体工作台(/v1/agent-runtime/project/*)使用 agent-runtime.project;普通项目 Key 不提供 projects.write
函数与站点 (Functions / Sites)functions.read, execution.read, sites.readfunctions.write, execution.write, sites.write公开函数执行与已发布预览/生产域名访问无需服务端 API Key
消息与审核 (Messaging / Moderation)providers.read, topics.read, subscribers.read, messages.read, moderation.config.read, moderation.log.readproviders.write, topics.write, subscribers.write, messages.write, moderation.config.write覆盖邮件/短信/推送通道及文本/图片内容安全审核
观测与辅助域 (Observability / Misc)observability.traces.read, observability.metrics.read, webhooks.read, locale.read, avatars.read, health.readobservability.ingest.write, webhooks.writeOTLP Trace 上报需 observability.ingest.write;observability.write 是其兼容别名,其他读写权限按具体功能选择

Session / JWT / OAuth2 与 API Key 认证流对比

  1. 服务端直连流(API Key):后端服务在每次请求中附带 X-Appwrite-Project 与 X-Appwrite-Key。若 Key 缺失、伪造或与项目不匹配,返回 401(general_access_forbidden);若 Key 有效但缺少当前端点声明的 Scope,返回 401(general_unauthorized_scope)。

  2. 服务端签发 Custom Token 交由客户端登录流:后端调用 POST /v1/users/{userId}/tokens(详见 Users API)生成一次性短时 secret,下发给浏览器或 App;客户端凭 (userId, secret) 建立用户 Session,后续直接访问受 $permissions 保护的表行或存储文件。

  3. BFF 代调用流(JWT):前端通过 Client SDK 获取有效期 15 分钟的用户 JWT,经业务请求传给后端 BFF;BFF 使用 X-Appwrite-Project + X-Appwrite-JWT 访问 Agentbase,此时平台以该终端用户的角色(user:<id>、team:<id>、label:<name>)执行资源级权限校验。

端点总览

本目录下的 24 个功能模块端点按路径前缀统一挂载在 /v1 之下:

功能分类路径前缀对应文档核心职责
项目管理/v1/project/*overview/overview.md项目环境变量管理、OceanBase 表模式在线转换(如切换至 Shared V2)
身份与团队/v1/users/*, /v1/teams/*auth/users.md, auth/teams.md用户生命周期、标签(Labels)、Mfa、Token 签发、团队与成员角色管理
结构化与文档数据库/v1/tablesdb/*, /v1/documentsdb/*, /v1/databases/*databases/overview.md, databases/permissions.md库/表/列/索引管理、行级 CRUD、跨表分布式事务、Schema 多版本与回滚
文件存储与短链令牌/v1/storage/*, /v1/tokens/*storage.md, file-tokens.md存储桶与文件分块上传、图片缩放预览、文件短时访问 Token 签发
知识库与词库/v1/knowledgebases/*, /v1/lexicons/*knowledge-base/overview.md, knowledge-base/wiki.md, knowledge-base/versions.md多源文档解析切分、混合检索、词库(同义词/扩展词/停用词)、GraphRAG、RAPTOR、Wiki 与版本封存
记忆系统/v1/memory/*memory/overview.md长期事实记忆、对话推理入库、用户画像抽取、Dreaming 与经验技能蒸馏
模型与 AI 网关/v1/llm-gateway/*, /v1/ai-gateway/*models-ai-gateway/llm-gateway.md, models-ai-gateway/ai-gateway.md模型供应商托管、策略、MCP 与 A2A
智能体运行时/v1/agent-runtime/*agent-runtime.md项目级智能体工作台配置、词库绑定、Preview/Published 会话(Threads)与运行(Runs)流式事件
可观测性与内容安全/v1/traces, /v1/observability/*, /v1/moderation/*observability/overview.md, moderation.mdOpenTelemetry 链路追踪上报、GenAI 指标聚合、在线评估(Evaluations)与图文内容审核
计算、站点与通知/v1/functions/*, /v1/sites/*, /v1/messaging/*functions.md, sites.md, messaging.mdServerless 函数部署与同步/异步执行、Web 站点托管、多通道消息触达
平台辅助工具/v1/webhooks/*, /v1/graphql*, /v1/avatars/*, /v1/locale/*, /v1/health/*misc/webhooks.md, misc/graphql.md, misc/avatars.md, misc/locale.md, misc/health.md事件回调订阅、GraphQL 查询、二维码/首字母头像/网页截图、国际化字典与实例健康检查

端点清单

本页为全局通用协议规范,不单独声明专有业务端点;各业务模块的全量「HTTP 方法 + 路径」清单请直接查阅上表对应的功能文档。

端点详解

请求与响应生命周期

  1. 协议与编码:全线强制使用 HTTPS(TLS 1.2+),请求与响应字符集统一为 UTF-8。

  2. 时间戳规范:所有日期时间字段(如 $createdAt、$updatedAt、expire、scheduledAt)均采用标准 ISO 8601 UTC 格式(例如 2026-10-22T08:30:00.000+00:00);仅 /v1/health/time 與 OTLP 纳秒时间戳使用 Unix 时间戳。

  3. 异步任务模式(202 Accepted):对于耗时的后台计算(如知识库文档解析构建、大批量记忆抽取、异步函数执行、Agent Run 创建、表模式转换任务),创建端点立即返回 202 Accepted 及任务对象(含 status: "pending" / "processing" 与任务 ID),调用方可通过轮询详情端点、订阅 SSE 事件流或注册 Webhook 获取最终执行结果。

请求与响应格式

Memory 的业务删除请求使用 JSON 正文,列表主要使用 limit/cursor,与下述通用过滤约定不同;具体以 Memory API 为准。

请求与响应

标准列表响应与单资源响应对比

单资源响应结构(以包含系统元数据的典型资源为例):

元数据字段类型说明
$idstring资源唯一标识
$createdAtstring创建时间(ISO 8601)
$updatedAtstring最近一次更新时间(ISO 8601)
$permissionsstring[]资源级权限字符串数组(如 ["read(\"any\")", "update(\"team:dev/owner\")"])

列表资源响应结构:

字段类型说明
totalinteger满足过滤条件的记录总数;当查询参数传入 total=false 时恒为 0
<resources>[]array当前分页窗口内的资源对象数组(字段名随模块变化,如 users、rows、documents、buckets)

统一错误模型

非 2xx 响应统一为如下 JSON 信封结构:

{
  "message": "Not found",
  "code": 404,
  "type": "not_found",
  "version": "2.10.0",
  "requestId": "req_9f8e7d6c5b4a3210"
}

错误与边界

HTTP 状态码典型 type 错误码触发原因是否可重试处理建议
400 Bad Requestgeneral_argument_invalid / general_query_invalid请求体字段类型不符、枚举值越界或 queries[] 语法错误否校验请求参数格式与字段约束后修正重试
401 Unauthorizedgeneral_access_forbiddenX-Appwrite-Key 缺失、无效或与 X-Appwrite-Project 不匹配否检查环境变量中的项目 ID 与 API Key
401 Unauthorizedgeneral_unauthorized_scopeAPI Key 有效,但未授予当前端点所需的 Scope否在控制台 API Keys 页面补充勾选对应 Scope
403 Forbiddengeneral_resource_blocked / project_database_read_only资源被封禁,或项目正处于表模式转换(Cutover)只读冻结窗口视情况若为表模式切换冻结窗口,等待 Cutover 完成后重试
404 Not Found*_not_found目标资源 ID 不存在,或客户端身份无读取权限(防枚举隐蔽返回 404)否核对路径中的资源 ID 及资源级 $permissions
409 Conflictgeneral_conflict / *_already_exists自定义资源 ID 重复、词库仍被引用时尝试删除、或乐观锁版本冲突否先查询现有资源状态或刷新最新版本号后再提交
429 Too Many Requestsgeneral_rate_limit_exceeded触发账户/项目/调用方令牌桶限流是读取响应头 Retry-After(秒)或 X-RateLimit-Reset 执行退避重试
503 Service Unavailablegeneral_service_unavailable上游依赖(如外部模型供应商或队列)瞬时繁忙是采用带随机抖动(Jitter)的指数退避策略重试

分页与查询

列表端点接受 queries 数组,每个元素是一条结构化查询字符串(在 Server SDK 中由 Query 构造器生成,直接发起 HTTP 调用时可传 JSON 序列化后的查询描述或函数式语法):

限流与幂等

完整调用示例

以下示例基于展示项目 enterprise-ai-hub-210(企业智能客服与知识中台)演示标准 HTTP 调用形态:两头认证、数组型分页 query、total=false 跳过计数。

列出项目内激活状态的客服人员账号(带分页与过滤,queries[] 为数组形式):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable \
  '<APPBASE_ENDPOINT_WITH_V1>/users?queries[]=limit(25)&queries[]=offset(0)&queries[]=equal("status",true)&total=false' \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

创建资源(JSON 请求体;以创建二线技术支持团队为例):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/teams" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "unique()",
    "name": "OceanBase 向量检索专家支持组",
    "roles": ["owner", "engineer"]
  }'
)

成功响应为 201 Created + 资源 JSON;列表响应形如 {"total": 0, "teams": [...]}(total=false 时 total 恒为 0)。

典型错误响应(Key 缺失或无效,401):

{
  "message": "Project is not accessible in this region or API key is invalid.",
  "code": 401,
  "type": "general_access_forbidden",
  "version": "2.10.0"
}

Key 有效但缺少所需 Scope(401):

{
  "message": "The current API key does not have the required scope (teams.write) to perform this action.",
  "code": 401,
  "type": "general_unauthorized_scope",
  "version": "2.10.0"
}

限流超限(429,携带 Retry-After 响应头):

{
  "message": "Too many requests",
  "code": 429,
  "type": "general_rate_limit_exceeded",
  "version": "2.10.0"
}

排障时建议同时查看四处:HTTP 状态码、错误 type、响应头 X-RateLimit-Remaining / Retry-After、以及响应中的 requestId(可用于可观测性平台的请求级检索)。

与 Server SDK 的对应

全部 Server SDK(agentbase-node-sdk@2.10.0、agentbase-python-sdk==2.10.0 及 Java / Go Server SDK)共用本页约定;HTTP 层差异只体现在具体端点与业务参数,认证头、错误模型、分页与限流语义完全一致。

Server SDK ServiceAPI 参考文档核心职责说明
Usersauth/users.md用户生命周期、标签、会话、MFA 与 Token 签发
Teamsauth/teams.md团队与成员角色管理
TablesDB / DocumentsDB / Databasesdatabases/overview.md结构化表、集合、行/文档 CRUD、事务与 Schema 版本
Storagestorage.md存储桶与文件上传、预览、下载
Tokensfile-tokens.md存储文件短时访问令牌管理
Functionsfunctions.mdServerless 函数、部署包、环境变量与执行记录
Projectoverview/overview.md项目全局变量与 OceanBase 表模式转换
Messagingmessaging.md邮件/短信/推送 Provider、Topic 与消息发送
Sitessites.md静态与 SSR 站点构建、部署与预览域名
Memorymemory/overview.md长期记忆、用户画像、上下文做梦与技能蒸馏
KnowledgeBases / Lexiconsknowledge-base/overview.md知识库文档摄取、混合检索、词库、Wiki 与版本封存
LlmGatewaymodels-ai-gateway/llm-gateway.md模型供应商、配额与基础模型调用
AiGatewaymodels-ai-gateway/ai-gateway.md策略、MCP 与 A2A
AgentRuntimeagent-runtime.md项目级智能体工作台、Draft 预览与 Published 运行
Observabilityobservability/overview.mdOTLP 链路追踪上报、指标与评估运行
Moderationmoderation.md数据库文本与存储桶图片自动内容审核
Webhooks / Graphql / Avatars / Locale / Healthmisc/webhooks.md 等Webhook 订阅、GraphQL、图形工具、国际化字典与健康检查

权限字符串文法与各资源上的语义见 permissions。