agentbase-docs

GraphQL API

以 GraphQL 查询/变更访问平台数据面:查询语法与 REST 数据模型一致。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。

端点清单

方法 + 路径用途
POST /graphqlGraphQL 查询
POST /graphql/mutationGraphQL 变更

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。

GraphQL

POST /v1/graphql

执行 GraphQL 查询:body 为标准 GraphQL query / variables 文档,schema 覆盖各域 REST 的等价读取操作。

输入:

参数位置类型必填默认/枚举说明
querybodystring是—GraphQL 文档字符串(查询或变更)。平台 GraphQL schema 覆盖各域 REST 的等价操作;spec 未展开 body schema,具体字段以当前项目 schema 为准。
variablesbodyobject否—文档变量对象,与文档中的 $var 占位对应。
operationNamebodystring否—多操作文档中要执行的操作名。

输出:返回 200 + 标准 GraphQL 响应:data(结果)与/或 errors(错误数组)。GraphQL 层错误不产生非 2xx 状态码,调用方必须检查 errors 字段。

调用示例:

curl -X POST "https://<your-endpoint>/v1/graphql" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetUserName { account { name email } }",
    "variables": {}
  }'

响应示例:

{
  "data": {
    "account": {
      "name": "Docs Bot",
      "email": "bot@example.com"
    }
  }
}

POST /v1/graphql/mutation

执行 GraphQL 变更:body 为标准 GraphQL mutation 文档,schema 覆盖各域 REST 的等价写入操作。

输入:

参数位置类型必填默认/枚举说明
querybodystring是—GraphQL 文档字符串(查询或变更)。平台 GraphQL schema 覆盖各域 REST 的等价操作;spec 未展开 body schema,具体字段以当前项目 schema 为准。
variablesbodyobject否—文档变量对象,与文档中的 $var 占位对应。
operationNamebodystring否—多操作文档中要执行的操作名。

输出:返回 200 + 标准 GraphQL 响应(data / errors)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/graphql/mutation" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateTeam($id: String!, $name: String!) { teamsCreate(teamId: $id, name: $name) { _id name } }",
    "variables": { "id": "team_docs", "name": "Docs" }
  }'

响应示例:

{
  "data": {
    "teamsCreate": {
      "_id": "team_docs",
      "name": "Docs"
    }
  }
}

错误与边界

与 Server SDK 的对应

service.method端点
Graphql.query / mutationPOST /graphql、POST /graphql/mutation

事实源