Docs
文档目录

团队 API

团队与团队成员(membership)管理:创建团队、维护成员邀请与角色、团队偏好。团队是权限体系中的核心分组:资源权限字符串 team:<teamId> / team:<teamId>/<role>(见 permissions)按团队与成员角色判定。

服务与资源边界

团队 API(/v1/teams/*)管理项目内的用户协作分组(Team)与成员角色关系(Membership):通过将用户组织为团队并赋予自定义角色(如 owner、specialist、dispatcher),可直接驱动数据库表/行、存储桶/文件、知识库与词库的 team:<teamId> 及 team:<teamId>/<role> 资源级 ACL 策略(见 权限字符串文法)。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:teams.read(读取团队与成员)、teams.write(创建/修改/删除团队与成员)。PATCH /teams/{teamId}/memberships/{membershipId}/status 在 spec 中标注为 public:它由受邀用户凭邀请 secret 完成确认,服务端集成场景一般不直接调用。

端点总览

Teams 模块共包含 12 个端点,涵盖团队 CRUD(5 个)、团队成员关系邀请/查询/角色更新/加入确认/移除(5 个)以及团队级共享偏好 prefs 读写(2 个)。

端点清单

方法 + 路径用途
GET /teams列出团队
POST /teams创建团队
GET /teams/{teamId}获取团队
PUT /teams/{teamId}更新团队名
DELETE /teams/{teamId}删除团队
GET /teams/{teamId}/memberships列出团队成员关系
POST /teams/{teamId}/memberships创建成员(发送邀请)
GET /teams/{teamId}/memberships/{membershipId}获取成员关系
PATCH /teams/{teamId}/memberships/{membershipId}更新成员角色
PATCH /teams/{teamId}/memberships/{membershipId}/status凭 secret 确认加入
DELETE /teams/{teamId}/memberships/{membershipId}移除成员
GET /teams/{teamId}/prefs读取团队偏好
PUT /teams/{teamId}/prefs覆盖写团队偏好

端点详解

通过服务端 API Key 调用 POST /v1/teams/{teamId}/memberships 添加已存在用户时,成员关系直接生效并实时更新该团队的 total 成员数;成员的 roles 数组变更会立即反映在后续所有涉及 team:<teamId>/<role> 的资源权限校验中。

请求与响应

以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。认证头与示例变量约定见 通用约定。

GET /v1/teams

列出项目内全部团队,支持按名称过滤与模糊搜索。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []可过滤字段:name、total(成员数)、billingPlan;分页用 limit(n)/offset(n)/cursorAfter(...)
searchquerystring否模糊搜索词(最长 256 字符),覆盖团队名
totalqueryboolean否默认 true传 false 跳过计数,total 恒返回 0

输出:200,返回 teamList 模型:total 为匹配总数,teams[] 为团队数组。team 字段结构见 POST /v1/teams。

字段类型说明
totalinteger匹配查询的团队总数
teams[]team[]团队对象,字段结构见 POST /v1/teams

调用示例:

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

响应示例:

{
  "total": 1,
  "teams": [
    {
      "$id": "66a9d93000b1a",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "name": "Platform",
      "total": 3,
      "prefs": {
        "theme": "pink",
        "timezone": "UTC"
      }
    }
  ]
}

POST /v1/teams

创建团队。创建者(服务端语境即项目本身)不自动产生 membership 记录;roles 仅用于指定创建者角色的默认值语义。

输入:

参数位置类型必填默认/枚举说明
teamIdbodystring是团队 ID:自定义或传 unique();可用字符 a-z、A-Z、0-9、.、-、_,不能以特殊字符开头,最长 36 字符
namebodystring是团队名,最长 128 字符
rolesbodystring[]否默认 ["owner"]创建者的默认角色数组;角色为任意字符串,最多 100 个

输出:201,返回 team 模型。完整字段表:

字段类型说明
$idstring团队 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
namestring团队名
totalinteger当前成员总数
prefsobject团队偏好键值对象

调用示例:

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": "66a9d93000b1a",
  "name": "Platform",
  "roles": [
    "owner",
    "admin"
  ]
}'

响应示例:

{
  "$id": "66a9d93000b1a",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Platform",
  "total": 3,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  }
}

GET /v1/teams/{teamId}

按 ID 获取单个团队。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID

输出:200,返回 team 模型,字段见 POST /v1/teams。

调用示例:

curl \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "66a9d93000b1a",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Platform",
  "total": 3,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  }
}

PUT /v1/teams/{teamId}

更新团队名。团队 ID 不可变。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
namebodystring是新团队名,最长 128 字符

输出:200,返回 team(关注 name 字段)。完整字段见 POST /v1/teams。

字段类型说明
namestring更新后的团队名

调用示例:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Platform Core"
}'

响应示例:

{
  "$id": "66a9d93000b1a",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Platform Core",
  "total": 3,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  }
}

DELETE /v1/teams/{teamId}

删除团队。级联删除全部成员关系;引用该团队的权限字符串(team:<teamId>、team:<teamId>/<role>)立即失效。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/teams/{teamId}/memberships

列出团队成员关系。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
queriesquerystring[]否默认 []可过滤字段:userId、teamId、invited、joined、confirm、roles
searchquerystring否模糊搜索词(最长 256 字符),覆盖成员姓名与邮箱
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 membershipList 模型:total + memberships[]。membership 字段结构见 POST /v1/teams/{teamId}/memberships。

字段类型说明
totalinteger成员关系总数
memberships[]membership[]成员关系对象

调用示例:

curl \
  'https://<your-endpoint>/v1/teams/66a9d93000b1a/memberships?queries[]=limit(25)&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "memberships": [
    {
      "$id": "66a9d94f00e3d",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "userId": "66a9d8ef00f21",
      "userName": "Ada Lovelace",
      "userEmail": "ada@example.com",
      "teamId": "66a9d93000b1a",
      "teamName": "Platform",
      "invited": "2020-10-15T06:38:00.000+00:00",
      "joined": "2020-10-15T06:38:00.000+00:00",
      "confirm": false,
      "mfa": false,
      "roles": [
        "owner"
      ]
    }
  ]
}

POST /v1/teams/{teamId}/memberships

向团队添加成员并触发邀请。成员已存在(按 userId)时直接关联;仅给 email/phone 时先创建用户再走邀请邮件。限流 10 次/小时。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
emailbodystring否新成员邮箱,与 userId/phone 至少提供其一
userIdbodystring否既有用户 ID,与 email/phone 至少提供其一
phonebodystring否手机号(+ 开头含国家码),与 email/userId 至少提供其一
rolesbodystring[]是最多 100 个,每个最长 81 字符团队内角色数组;角色为任意字符串,team:<teamId>/<role> 权限按此判定
urlbodystring否邀请邮件回跳 URL;携带 API Key 调用时可不传。仅允许项目平台列表内的主机名(防开放重定向)
namebodystring否新成员姓名,最长 128 字符

输出:201,返回 membership 模型(confirm=false 表示尚未确认)。完整字段表:

字段类型说明
$idstring成员关系 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
userIdstring成员用户 ID
userName / userEmailstring成员姓名/邮箱(可在控制台按隐私开关隐藏)
teamId / teamNamestring所属团队 ID/名称
invitedstring受邀时间(ISO 8601)
joinedstring接受邀请时间(ISO 8601;未接受为空)
confirmboolean是否已确认加入
mfaboolean该成员是否启用 MFA
rolesstring[]团队内角色(team:<teamId>/<role> 权限判定依据)

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a/memberships" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "bob@example.com",
  "roles": [
    "developer"
  ],
  "url": "https://example.com/join",
  "name": "Bob Chen"
}'

响应示例:

{
  "$id": "66a9d94f00e3d",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8f111b3c",
  "userName": "Bob Chen",
  "userEmail": "bob@example.com",
  "teamId": "66a9d93000b1a",
  "teamName": "Platform",
  "invited": "2020-10-15T06:38:00.000+00:00",
  "joined": null,
  "confirm": false,
  "mfa": false,
  "roles": [
    "developer"
  ]
}

邀请 secret 仅出现在本端点响应与邀请邮件中,供受邀用户经确认端点完成加入;服务端应把它转发给受邀用户,不应代为确认。

GET /v1/teams/{teamId}/memberships/{membershipId}

按 ID 获取团队成员关系。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
membershipIdpathstring是成员关系 ID

输出:200,返回 membership 模型,字段见 POST /v1/teams/{teamId}/memberships。

调用示例:

curl \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a/memberships/66a9d94f00e3d" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "66a9d94f00e3d",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8ef00f21",
  "userName": "Ada Lovelace",
  "userEmail": "ada@example.com",
  "teamId": "66a9d93000b1a",
  "teamName": "Platform",
  "invited": "2020-10-15T06:38:00.000+00:00",
  "joined": "2020-10-15T06:38:00.000+00:00",
  "confirm": false,
  "mfa": false,
  "roles": [
    "owner"
  ]
}

PATCH /v1/teams/{teamId}/memberships/{membershipId}

整体替换成员在团队内的角色数组。角色变更即时影响 team:<teamId>/<role> 权限判定。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
membershipIdpathstring是成员关系 ID
rolesbodystring[]是最多 100 个,每个最长 81 字符完整的新角色数组(全量替换语义)

输出:200,返回 membership(关注 roles 字段)。完整字段见 POST /v1/teams/{teamId}/memberships。

字段类型说明
rolesstring[]替换后的角色数组

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a/memberships/66a9d94f00e3d" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "roles": [
    "developer",
    "reviewer"
  ]
}'

响应示例:

{
  "$id": "66a9d94f00e3d",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8ef00f21",
  "userName": "Ada Lovelace",
  "userEmail": "ada@example.com",
  "teamId": "66a9d93000b1a",
  "teamName": "Platform",
  "invited": "2020-10-15T06:38:00.000+00:00",
  "joined": "2020-10-15T06:38:00.000+00:00",
  "confirm": false,
  "mfa": false,
  "roles": [
    "developer",
    "reviewer"
  ]
}

PATCH /v1/teams/{teamId}/memberships/{membershipId}/status

凭邀请 secret 确认加入团队:确认后 confirm 置为 true、joined 填充确认时间。spec 中该端点标注 public scope——设计上由受邀用户(凭邮件中的 secret)调用,服务端集成一般不直接调用。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
membershipIdpathstring是成员关系 ID
userIdbodystring是受邀用户 ID
secretbodystring是邀请 secret(来自创建成员响应或邀请邮件)

输出:200,返回 membership(confirm 置为 true、joined 填充确认时间)。完整字段见 POST /v1/teams/{teamId}/memberships。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a/memberships/66a9d94f00e3d/status" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "secret": "dZfJL2mXqA"
}'

响应示例:

{
  "$id": "66a9d94f00e3d",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8ef00f21",
  "userName": "Ada Lovelace",
  "userEmail": "ada@example.com",
  "teamId": "66a9d93000b1a",
  "teamName": "Platform",
  "invited": "2020-10-15T06:38:00.000+00:00",
  "joined": "2020-10-15T06:38:00.000+00:00",
  "confirm": true,
  "mfa": false,
  "roles": [
    "owner"
  ]
}

该端点不对资源级权限做检查:只要持有有效 secret 与正确的 userId 即可完成确认,secret 泄露即等同他人可加入团队。

DELETE /v1/teams/{teamId}/memberships/{membershipId}

移除团队成员。该成员的 team:<teamId> 系权限立即失效。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
membershipIdpathstring是成员关系 ID

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a/memberships/66a9d94f00e3d" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/teams/{teamId}/prefs

读取团队偏好(自由键值 JSON)。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID

输出:200,返回 preferences 键值对象。

调用示例:

curl \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a/prefs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "theme": "pink",
  "timezone": "UTC"
}

PUT /v1/teams/{teamId}/prefs

整体覆盖写入团队偏好:传入对象完整替换既有偏好(区别于用户偏好的合并语义)。

输入:

参数位置类型必填默认/枚举说明
teamIdpathstring是团队 ID
prefsbodyobject是完整的偏好键值对象

输出:200,返回覆盖后的 preferences 对象。

调用示例:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/teams/66a9d93000b1a/prefs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "prefs": {
    "theme": "dark",
    "timezone": "Asia/Shanghai"
  }
}'

响应示例:

{
  "theme": "dark",
  "timezone": "Asia/Shanghai"
}

错误与边界

与 Server SDK 的对应

service.method端点
Teams.listGET /teams
Teams.createPOST /teams
Teams.getGET /teams/{teamId}
Teams.updateNamePUT /teams/{teamId}
Teams.deleteDELETE /teams/{teamId}
Teams.listMembershipsGET /teams/{teamId}/memberships
Teams.createMembershipPOST /teams/{teamId}/memberships
Teams.getMembershipGET /teams/{teamId}/memberships/{membershipId}
Teams.updateMembershipPATCH /teams/{teamId}/memberships/{membershipId}
Teams.updateMembershipStatusPATCH /teams/{teamId}/memberships/{membershipId}/status
Teams.deleteMembershipDELETE /teams/{teamId}/memberships/{membershipId}
Teams.getPrefsGET /teams/{teamId}/prefs
Teams.updatePrefsPUT /teams/{teamId}/prefs