agentbase-docs

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

本文是 project/ 下全部功能 API 的公共约定:认证头、scope、请求/响应格式、统一错误模型、分页与限流。各功能点的端点、参数与错误细节见对应文档(索引见文末「与 Server SDK 的对应」表)。

资源与基础路径

认证与权限

服务端访问使用两个请求头(兼容命名):

请求头含义
X-Appwrite-Project项目 ID
X-Appwrite-Key项目 API Key(在该项目的设置中创建)

约定要点:

请求与响应格式

统一错误模型

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

{
  "message": "Not found",
  "code": 404,
  "type": "not_found",
  "version": "2.6.0",
  "requestId": "<关联 ID,用于排障与观测查询>"
}

分页与查询

列表端点接受 queries 数组,每个元素是一条查询字符串(SDK 中由 Query 构造器生成,形如 limit(25)、cursorAfter("...")、equal("name","x")):

限流与幂等

完整调用示例

以下示例演示一次典型调用的完整形态:两头认证、数组型分页 query、total=false 跳过计数。

列出用户(带分页与过滤,queries[] 为数组形式):

curl \
  'https://<your-endpoint>/v1/users?queries[]=limit(25)&queries[]=offset(0)&queries[]=equal("status","true")&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

创建资源(JSON 请求体;以团队为例):

curl -X POST "https://<your-endpoint>/v1/teams" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "unique()",
    "name": "Platform"
  }'

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

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

{
  "message": "Not found",
  "code": 401,
  "type": "general_access_forbidden",
  "version": "2.6.0"
}

Key 有效但缺 scope(401):

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

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

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

排障时同时查看三处:HTTP 状态码、错误 type、响应头 X-RateLimit-Remaining / Retry-After;requestId 可用于观测平台的请求级检索。

与 Server SDK 的对应

全部 Server SDK service 共用本页约定;HTTP 层差异只体现在端点与参数,认证头、错误模型、分页与限流语义完全一致。

Server SDK serviceAPI 文档
Usersusers
Teamsteams
TablesDB / DocumentsDB / Databasesdatabases
Storagestorage
Tokensfile-tokens
Functionsfunctions
Projectprojects
Messagingmessaging
Sitessites
Memorymemory
KnowledgeBasesknowledge-bases
LlmGatewayllm-gateway
AiGatewayai-gateway
Observabilityobservability
Moderationmoderation
Webhooks / Graphql / Avatars / Locale / Healthmisc/webhooks 等

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

事实源