团队 API
团队与团队成员(membership)管理:创建团队、维护成员邀请与角色、团队偏好。团队是权限体系中的核心分组:资源权限字符串 team:<teamId> / team:<teamId>/<role>(见 permissions)按团队与成员角色判定。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/teams。 - 资源:
team(团队)、membership(成员关系)。 - 团队 ID 为自定义或自动生成字符串(最长 36 字符);membership ID 由服务端生成。
认证与权限
认证与请求头约定见 通用约定。本域 scope:teams.read(读取团队与成员)、teams.write(创建/修改/删除团队与成员)。PATCH /teams/{teamId}/memberships/{membershipId}/status 在 spec 中标注为 public:它由受邀用户凭邀请 secret 完成确认,服务端集成场景一般不直接调用。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
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 | 覆盖写团队偏好 |
请求与响应
以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。认证头与示例占位符约定见 通用约定。
GET /v1/teams
列出项目内全部团队,支持按名称过滤与模糊搜索。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | 可过滤字段:name、total(成员数)、billingPlan;分页用 limit(n)/offset(n)/cursorAfter(...) |
search | query | string | 否 | 模糊搜索词(最长 256 字符),覆盖团队名 | |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数,total 恒返回 0 |
输出:200,返回 teamList 模型:total 为匹配总数,teams[] 为团队数组。team 字段结构见 [POST /v1/teams](#post-v1teams)。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 匹配查询的团队总数 |
| teams[] | team[] | 团队对象,字段结构见 [POST /v1/teams](#post-v1teams) |
调用示例:
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 仅用于指定创建者角色的默认值语义。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | body | string | 是 | 团队 ID:自定义或传 unique();可用字符 a-z、A-Z、0-9、.、-、_,不能以特殊字符开头,最长 36 字符 | |
name | body | string | 是 | 团队名,最长 128 字符 | |
roles | body | string[] | 否 | 默认 ["owner"] | 创建者的默认角色数组;角色为任意字符串,最多 100 个 |
输出:201,返回 team 模型。完整字段表:
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 团队 ID |
| $createdAt / $updatedAt | string | 创建/更新时间(ISO 8601) |
| name | string | 团队名 |
| total | integer | 当前成员总数 |
| prefs | object | 团队偏好键值对象 |
调用示例:
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 获取单个团队。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID |
输出:200,返回 team 模型,字段见 [POST /v1/teams](#post-v1teams)。
调用示例:
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 不可变。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
name | body | string | 是 | 新团队名,最长 128 字符 |
输出:200,返回 team(关注 name 字段)。完整字段见 [POST /v1/teams](#post-v1teams)。
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | 更新后的团队名 |
调用示例:
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>)立即失效。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 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
列出团队成员关系。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
queries | query | string[] | 否 | 默认 [] | 可过滤字段:userId、teamId、invited、joined、confirm、roles |
search | query | string | 否 | 模糊搜索词(最长 256 字符),覆盖成员姓名与邮箱 | |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 membershipList 模型:total + memberships[]。membership 字段结构见 [POST /v1/teams/{teamId}/memberships](#post-v1teamsteamidmemberships)。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 成员关系总数 |
| 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 次/小时。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
email | body | string | 否 | 新成员邮箱,与 userId/phone 至少提供其一 | |
userId | body | string | 否 | 既有用户 ID,与 email/phone 至少提供其一 | |
phone | body | string | 否 | 手机号(+ 开头含国家码),与 email/userId 至少提供其一 | |
roles | body | string[] | 是 | 最多 100 个,每个最长 81 字符 | 团队内角色数组;角色为任意字符串,team:<teamId>/<role> 权限按此判定 |
url | body | string | 否 | 邀请邮件回跳 URL;携带 API Key 调用时可不传。仅允许项目平台列表内的主机名(防开放重定向) | |
name | body | string | 否 | 新成员姓名,最长 128 字符 |
输出:201,返回 membership 模型(confirm=false 表示尚未确认)。完整字段表:
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 成员关系 ID |
| $createdAt / $updatedAt | string | 创建/更新时间(ISO 8601) |
| userId | string | 成员用户 ID |
| userName / userEmail | string | 成员姓名/邮箱(可在控制台按隐私开关隐藏) |
| teamId / teamName | string | 所属团队 ID/名称 |
| invited | string | 受邀时间(ISO 8601) |
| joined | string | 接受邀请时间(ISO 8601;未接受为空) |
| confirm | boolean | 是否已确认加入 |
| mfa | boolean | 该成员是否启用 MFA |
| roles | string[] | 团队内角色(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 获取团队成员关系。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
membershipId | path | string | 是 | 成员关系 ID |
输出:200,返回 membership 模型,字段见 [POST /v1/teams/{teamId}/memberships](#post-v1teamsteamidmemberships)。
调用示例:
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> 权限判定。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
membershipId | path | string | 是 | 成员关系 ID | |
roles | body | string[] | 是 | 最多 100 个,每个最长 81 字符 | 完整的新角色数组(全量替换语义) |
输出:200,返回 membership(关注 roles 字段)。完整字段见 [POST /v1/teams/{teamId}/memberships](#post-v1teamsteamidmemberships)。
| 字段 | 类型 | 说明 |
|---|---|---|
| roles | string[] | 替换后的角色数组 |
调用示例:
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)调用,服务端集成一般不直接调用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
membershipId | path | string | 是 | 成员关系 ID | |
userId | body | string | 是 | 受邀用户 ID | |
secret | body | string | 是 | 邀请 secret(来自创建成员响应或邀请邮件) |
输出:200,返回 membership(confirm 置为 true、joined 填充确认时间)。完整字段见 [POST /v1/teams/{teamId}/memberships](#post-v1teamsteamidmemberships)。
调用示例:
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> 系权限立即失效。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
membershipId | path | string | 是 | 成员关系 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)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 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
整体覆盖写入团队偏好:传入对象完整替换既有偏好(区别于用户偏好的合并语义)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
teamId | path | string | 是 | 团队 ID | |
prefs | body | object | 是 | 完整的偏好键值对象 |
输出: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"
}错误与边界
- 团队不存在:
404+team_not_found;成员关系不存在:team_invite_not_found。 - 创建成员时
email/userId/phone至少提供一个;userId指向不存在用户且无email/phone可达时创建失败。 - 角色是自由字符串:写入前不必预注册;
team:<teamId>/<role>权限字符串在角色被移除后立即失效。 - 删除团队会级联删除全部成员关系;引用该团队的资源权限字符串立即失效。
- 邀请确认端点需要邀请
secret;secret 只在创建成员响应与邀请邮件中下发,服务端应转发给受邀用户而非代为确认。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Teams.list | GET /teams |
Teams.create | POST /teams |
Teams.get | GET /teams/{teamId} |
Teams.updateName | PUT /teams/{teamId} |
Teams.delete | DELETE /teams/{teamId} |
Teams.listMemberships | GET /teams/{teamId}/memberships |
Teams.createMembership | POST /teams/{teamId}/memberships |
Teams.getMembership | GET /teams/{teamId}/memberships/{membershipId} |
Teams.updateMembership | PATCH /teams/{teamId}/memberships/{membershipId} |
Teams.updateMembershipStatus | PATCH /teams/{teamId}/memberships/{membershipId}/status |
Teams.deleteMembership | DELETE /teams/{teamId}/memberships/{membershipId} |
Teams.getPrefs | GET /teams/{teamId}/prefs |
Teams.updatePrefs | PUT /teams/{teamId}/prefs |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(/teams域 13 个端点、参数与team/teamList/membership/membershipList模型)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0Teamsservice。