项目 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/)聚焦于项目下全部业务功能的访问接口,其核心边界如下:
项目级多租户隔离:所有项目级资源(如业务库
enterprise_biz_db、知识库kb_enterprise_support、存储桶kb_enterprise_docs、记忆空间、AI 网关prod-enterprise-ai-gateway)均严格挂载在单个项目(如展示项目enterprise-ai-hub-210)之下。任何 HTTP 请求必须首先通过X-Appwrite-Project声明目标项目上下文。服务端与客户端双轨凭据:
服务端访问(Server SDK / 后端微服务):使用
X-Appwrite-Project+X-Appwrite-Key(项目 API Key)。服务端角色按 Key 绑定的scopes矩阵鉴权,默认绕过行级/文档级/文件级的$permissions用户 ACL。客户端/终端用户访问(Web SDK / 移动端 / Agent 对话端):使用
X-Appwrite-Project+ 用户会话(Session Cookie、X-Appwrite-Session或X-Appwrite-JWT),受资源上的$permissions(详见 权限字符串文法)严格约束。网关调用凭据:模型调用使用模型网关的授权凭据;AI 网关工具数据面使用对应网关授权的
abk_凭据。两者不可互换。
资源与基础路径
Base URL:
https://appbuild-sit.oceanbase.com/v1(或您的私有化实例地址https://<your-endpoint>/v1)。本目录下所有文档中的端点路径均为该 Base URL 下的相对路径(对应服务版本2.10.0)。路径参数与资源 ID 规范:
路径中的
{userId}、{databaseId}、{knowledgeBaseId}、{lexiconId}等为资源唯一标识(UID)。创建资源时,调用方既可传入自定义 ID(长度 1–36 字符,允许字母、数字、
.、-、_,且不得以特殊字符开头),也可传入字面量"unique()"由服务端自动生成全局唯一 ID。
认证与权限
完整请求头矩阵
| 请求头名称 | 必填性 | 适用场景 | 示例值 | 语义说明 |
|---|---|---|---|---|
X-Appwrite-Project | 必填 | 全部项目级 API | enterprise-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 Gateway | Bearer <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.read | users.write, teams.write, sessions.write | users.write 可签发 Custom Token(/users/{userId}/tokens) |
| 数据库 (Databases) | databases.read, tables.read, columns.read, indexes.read, rows.read | databases.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.read | buckets.write, files.write, tokens.write | 文件下载/预览在 fileSecurity=true 时支持 ?token=<secret> 免 Header 访问 |
| 知识库与词库 (Knowledge Base) | knowledgebases.read, lexicons.read | knowledgebases.write, lexicons.write | 词库(Lexicons)独立受 lexicons.read / lexicons.write 控制 |
| 记忆系统 (Memory) | memories.read | memories.write, memories.delete, memories.export, memories.share | 覆盖长期记忆、用户画像、上下文做梦(Dreaming)与经验技能蒸馏(Distillation) |
| 模型与 AI 网关 (LLM Gateway / AI Gateway) | llm-gateway.providers.read, llm-gateway.keys.read, aiGateway.read | llm-gateway.providers.write, llm-gateway.keys.write, aiGateway.write | 模型推理使用 llm-gateway.execute;AI 网关工具使用对应网关凭据 |
| 智能体运行时 (Agent Runtime) | agent-runtime.read, projects.read | agent-runtime.write, agent-runtime.project | 项目级智能体工作台(/v1/agent-runtime/project/*)使用 agent-runtime.project;普通项目 Key 不提供 projects.write |
| 函数与站点 (Functions / Sites) | functions.read, execution.read, sites.read | functions.write, execution.write, sites.write | 公开函数执行与已发布预览/生产域名访问无需服务端 API Key |
| 消息与审核 (Messaging / Moderation) | providers.read, topics.read, subscribers.read, messages.read, moderation.config.read, moderation.log.read | providers.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.read | observability.ingest.write, webhooks.write | OTLP Trace 上报需 observability.ingest.write;observability.write 是其兼容别名,其他读写权限按具体功能选择 |
Session / JWT / OAuth2 与 API Key 认证流对比
服务端直连流(API Key):后端服务在每次请求中附带
X-Appwrite-Project与X-Appwrite-Key。若 Key 缺失、伪造或与项目不匹配,返回401(general_access_forbidden);若 Key 有效但缺少当前端点声明的 Scope,返回401(general_unauthorized_scope)。服务端签发 Custom Token 交由客户端登录流:后端调用
POST /v1/users/{userId}/tokens(详见 Users API)生成一次性短时secret,下发给浏览器或 App;客户端凭(userId, secret)建立用户 Session,后续直接访问受$permissions保护的表行或存储文件。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.md | OpenTelemetry 链路追踪上报、GenAI 指标聚合、在线评估(Evaluations)与图文内容审核 |
| 计算、站点与通知 | /v1/functions/*, /v1/sites/*, /v1/messaging/* | functions.md, sites.md, messaging.md | Serverless 函数部署与同步/异步执行、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 方法 + 路径」清单请直接查阅上表对应的功能文档。
端点详解
请求与响应生命周期
协议与编码:全线强制使用
HTTPS(TLS 1.2+),请求与响应字符集统一为UTF-8。时间戳规范:所有日期时间字段(如
$createdAt、$updatedAt、expire、scheduledAt)均采用标准 ISO 8601 UTC 格式(例如2026-10-22T08:30:00.000+00:00);仅/v1/health/time與 OTLP 纳秒时间戳使用 Unix 时间戳。异步任务模式(
202 Accepted):对于耗时的后台计算(如知识库文档解析构建、大批量记忆抽取、异步函数执行、Agent Run 创建、表模式转换任务),创建端点立即返回202 Accepted及任务对象(含status: "pending"/"processing"与任务 ID),调用方可通过轮询详情端点、订阅 SSE 事件流或注册 Webhook 获取最终执行结果。
请求与响应格式
Memory 的业务删除请求使用 JSON 正文,列表主要使用 limit/cursor,与下述通用过滤约定不同;具体以 Memory API 为准。
GET/DELETE的过滤参数走 URL 查询串;POST/PUT/PATCH走application/json请求体。分页参数queries统一为数组形式(queries[]=...)。文件上传类端点(如存储文件分块上传、函数与站点的部署包上传)使用
multipart/form-data;单文件超过 5MB 时通过Content-Range头分片上传(详见 Storage API)。响应为 JSON。列表类响应统一为
total(匹配总数,整数)+ 资源名字段(如rows、users、files、lexicons)的结构;多数列表端点接受total=false跳过COUNT(*)查询以显著降低大表分页开销。下载类端点(文件
download/view/preview、部署包download、知识库文档source、词库export)返回二进制字节流或附件下载头,不返回通用 JSON 包装。
请求与响应
标准列表响应与单资源响应对比
单资源响应结构(以包含系统元数据的典型资源为例):
| 元数据字段 | 类型 | 说明 |
|---|---|---|
$id | string | 资源唯一标识 |
$createdAt | string | 创建时间(ISO 8601) |
$updatedAt | string | 最近一次更新时间(ISO 8601) |
$permissions | string[] | 资源级权限字符串数组(如 ["read(\"any\")", "update(\"team:dev/owner\")"]) |
列表资源响应结构:
| 字段 | 类型 | 说明 |
|---|---|---|
total | integer | 满足过滤条件的记录总数;当查询参数传入 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"
}type为小写下划线字符串;通用错误类型包括general_access_forbidden(401)、general_unauthorized_scope(401)、general_resource_blocked(403)、general_route_not_found(404)、general_cursor_not_found(400)、general_argument_invalid(400)、general_conflict(409)、general_rate_limit_exceeded(429)、general_service_unavailable(503)等。各功能域有自己的语义错误类型(如
user_not_found、database_not_found、storage_bucket_not_found、lexicon_not_found、knowledge_base_not_found),在对应文档的「错误与边界」一节登记。code字段与 HTTP 状态码一致;客户端自动重试策略应以 HTTP 状态码 +type共同决定。
错误与边界
| HTTP 状态码 | 典型 type 错误码 | 触发原因 | 是否可重试 | 处理建议 |
|---|---|---|---|---|
400 Bad Request | general_argument_invalid / general_query_invalid | 请求体字段类型不符、枚举值越界或 queries[] 语法错误 | 否 | 校验请求参数格式与字段约束后修正重试 |
401 Unauthorized | general_access_forbidden | X-Appwrite-Key 缺失、无效或与 X-Appwrite-Project 不匹配 | 否 | 检查环境变量中的项目 ID 与 API Key |
401 Unauthorized | general_unauthorized_scope | API Key 有效,但未授予当前端点所需的 Scope | 否 | 在控制台 API Keys 页面补充勾选对应 Scope |
403 Forbidden | general_resource_blocked / project_database_read_only | 资源被封禁,或项目正处于表模式转换(Cutover)只读冻结窗口 | 视情况 | 若为表模式切换冻结窗口,等待 Cutover 完成后重试 |
404 Not Found | *_not_found | 目标资源 ID 不存在,或客户端身份无读取权限(防枚举隐蔽返回 404) | 否 | 核对路径中的资源 ID 及资源级 $permissions |
409 Conflict | general_conflict / *_already_exists | 自定义资源 ID 重复、词库仍被引用时尝试删除、或乐观锁版本冲突 | 否 | 先查询现有资源状态或刷新最新版本号后再提交 |
429 Too Many Requests | general_rate_limit_exceeded | 触发账户/项目/调用方令牌桶限流 | 是 | 读取响应头 Retry-After(秒)或 X-RateLimit-Reset 执行退避重试 |
503 Service Unavailable | general_service_unavailable | 上游依赖(如外部模型供应商或队列)瞬时繁忙 | 是 | 采用带随机抖动(Jitter)的指数退避策略重试 |
分页与查询
列表端点接受 queries 数组,每个元素是一条结构化查询字符串(在 Server SDK 中由 Query 构造器生成,直接发起 HTTP 调用时可传 JSON 序列化后的查询描述或函数式语法):
分页算子:支持偏移量分页
limit(n)、offset(n),以及高性能游标分页cursorAfter("<lastId>")、cursorBefore("<firstId>")。cursor取自上一页最后一条资源的$id,当游标记录已被删除时返回400(general_cursor_not_found)。生产环境遍历超过 5,000 条记录时,强烈建议使用cursorAfter+total=false。过滤与排序算子:
精确匹配与否定:
equal("attr", ["val"])、notEqual("attr", ["val"])范围比较:
lessThan("attr", val)、lessThanEqual("attr", val)、greaterThan("attr", val)、greaterThanEqual("attr", val)、between("attr", min, max)空值与前缀/子串:
isNull("attr")、isNotNull("attr")、startsWith("attr", "prefix")、endsWith("attr", "suffix")、contains("attr", ["sub"])、search("attr", "keywords")逻辑组合与投影排序:
or([...])、and([...])、orderAsc("attr")、orderDesc("attr")、select(["$id", "status"])
查询配额边界:单次请求最多传入 100 条 query,单条最长 4096 字符;
limit单页上限以各端点标注为准(标准列表上限为 100)。默认顺序:未显式指定
orderAsc/orderDesc时,默认按资源创建顺序($id升序)返回。
限流与幂等
三层令牌桶限流:平台按「账户 → 项目 → 调用方(IP / 用户 / API Key)」三层令牌桶执行限流;响应头携带:
X-RateLimit-Limit:当前时间窗口的最大请求配额X-RateLimit-Remaining:当前窗口剩余可用次数X-RateLimit-Reset:当前限流窗口重置的 Unix 时间戳(秒)
超限行为:触发限流时返回
429 Too Many Requests,错误类型general_rate_limit_exceeded,并携带Retry-After头。幂等语义:
GET、HEAD、DELETE天然具备 HTTP 语义幂等;PUT语义为创建或整体替换(create-or-replace,如词库绑定PUT /v1/knowledgebases/{id}/lexicons);PATCH为局部字段更新;跨多行/多表的原子写入使用显式事务(见 Databases API)。
完整调用示例
以下示例基于展示项目 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 Service | API 参考文档 | 核心职责说明 |
|---|---|---|
Users | auth/users.md | 用户生命周期、标签、会话、MFA 与 Token 签发 |
Teams | auth/teams.md | 团队与成员角色管理 |
TablesDB / DocumentsDB / Databases | databases/overview.md | 结构化表、集合、行/文档 CRUD、事务与 Schema 版本 |
Storage | storage.md | 存储桶与文件上传、预览、下载 |
Tokens | file-tokens.md | 存储文件短时访问令牌管理 |
Functions | functions.md | Serverless 函数、部署包、环境变量与执行记录 |
Project | overview/overview.md | 项目全局变量与 OceanBase 表模式转换 |
Messaging | messaging.md | 邮件/短信/推送 Provider、Topic 与消息发送 |
Sites | sites.md | 静态与 SSR 站点构建、部署与预览域名 |
Memory | memory/overview.md | 长期记忆、用户画像、上下文做梦与技能蒸馏 |
KnowledgeBases / Lexicons | knowledge-base/overview.md | 知识库文档摄取、混合检索、词库、Wiki 与版本封存 |
LlmGateway | models-ai-gateway/llm-gateway.md | 模型供应商、配额与基础模型调用 |
AiGateway | models-ai-gateway/ai-gateway.md | 策略、MCP 与 A2A |
AgentRuntime | agent-runtime.md | 项目级智能体工作台、Draft 预览与 Published 运行 |
Observability | observability/overview.md | OTLP 链路追踪上报、指标与评估运行 |
Moderation | moderation.md | 数据库文本与存储桶图片自动内容审核 |
Webhooks / Graphql / Avatars / Locale / Health | misc/webhooks.md 等 | Webhook 订阅、GraphQL、图形工具、国际化字典与健康检查 |
权限字符串文法与各资源上的语义见 permissions。