Teams API
Team and team membership management: create teams, maintain member invitations and roles, and team preferences. Teams are the core grouping in the permission system: resource permission strings team:<teamId> / team:<teamId>/<role> (see permissions) are evaluated by team and member roles.
Service and resource boundaries
The Teams API (/v1/teams/*) manages user collaboration groups (Team) and member role relationships (Membership) within a project: by organizing users into teams and assigning custom roles (such as owner, specialist, dispatcher), you can directly drive the team:<teamId> and team:<teamId>/<role> resource-level ACL policies for database tables/rows, storage buckets/files, knowledge bases, and lexicons (see permission string grammar).
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/teams.Resources:
team(team),membership(membership).The team ID is a custom or auto-generated string (up to 36 characters); the membership ID is generated by the server.
Authentication and Permissions
For authentication and request header conventions, see general conventions. Scopes in this domain: teams.read (read teams and members), teams.write (create/modify/delete teams and members). PATCH /teams/{teamId}/memberships/{membershipId}/status is marked as public in the spec: it is confirmed by the invited user via invitation secret and is generally not called directly in server-side integration scenarios.
Endpoint overview
The Teams module contains 12 endpoints in total, covering team CRUD (5), team membership invitation/query/role update/join confirmation/removal (5), and team-level shared preference prefs read/write (2).
Endpoint List
| Method + path | Purpose |
|---|---|
GET /teams | List teams |
POST /teams | Create a team |
GET /teams/{teamId} | Get a team |
PUT /teams/{teamId} | Update team name |
DELETE /teams/{teamId} | Delete a team |
GET /teams/{teamId}/memberships | List team memberships |
POST /teams/{teamId}/memberships | Create a member (send invitation) |
GET /teams/{teamId}/memberships/{membershipId} | Get a membership |
PATCH /teams/{teamId}/memberships/{membershipId} | Update member roles |
PATCH /teams/{teamId}/memberships/{membershipId}/status | Confirm joining with a secret |
DELETE /teams/{teamId}/memberships/{membershipId} | Remove a member |
GET /teams/{teamId}/prefs | Read team preferences |
PUT /teams/{teamId}/prefs | Overwrite team preferences |
Endpoint details
When adding an existing user via POST /v1/teams/{teamId}/memberships using a server-side API Key, the membership takes effect immediately and the team's total member count is updated in real time; changes to the member's roles array are immediately reflected in all subsequent resource permission checks involving team:<teamId>/<role>.
Requests and Responses
The following sections give inputs, outputs, copyable call examples, and response examples for each endpoint. For authentication header and example variable conventions, see general conventions.
GET /v1/teams
List all teams in the project, with name filtering and fuzzy search support.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | Filterable fields: name, total (member count), billingPlan; use limit(n)/offset(n)/cursorAfter(...) for pagination |
search | query | string | No | Fuzzy search term (up to 256 characters), covering the team name | |
total | query | boolean | No | Default true | Pass false to skip counting; total always returns 0 |
Output: 200, returning the teamList model: total is the total number of matches, and teams[] is the teams array. For the team field structure, see POST /v1/teams.
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of teams matching the query |
| teams[] | team[] | Team object; for the field structure, see POST /v1/teams |
Call example:
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>"Response example:
{
"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
Create a team. The creator (the project itself in a server-side context) does not automatically get a membership record; roles is only used to specify the default role semantics for the creator.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | body | string | Yes | Team ID: custom or pass unique(); allowed characters are a-z, A-Z, 0-9, ., -, _; must not start with a special character, up to 36 characters | |
name | body | string | Yes | Team name, up to 128 characters | |
roles | body | string[] | No | Default ["owner"] | Array of default roles for the creator; roles are arbitrary strings, up to 100 of them |
Output: 201, returning the team model. Full field table:
| Field | Type | Description |
|---|---|---|
| $id | string | Team ID |
| $createdAt / $updatedAt | string | Creation/update time (ISO 8601) |
| name | string | Team name |
| total | integer | Current total number of members |
| prefs | object | Team preference key-value object |
Call example:
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"
]
}'Response example:
{
"$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}
Get a single team by ID.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID |
Output: 200, returning the team model; see fields in POST /v1/teams.
Call example:
curl \
"https://<your-endpoint>/v1/teams/66a9d93000b1a" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$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}
Update the team name. The team ID is immutable.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
name | body | string | Yes | New team name, up to 128 characters |
Output: 200, returning team (focus on the name field). For full fields, see POST /v1/teams.
| Field | Type | Description |
|---|---|---|
| name | string | Updated team name |
Call example:
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"
}'Response example:
{
"$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}
Delete a team. All memberships are deleted in cascade; permission strings referencing the team (team:<teamId>, team:<teamId>/<role>) become invalid immediately.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID |
Output: 204 No Content, no response body.
Call example:
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
List team memberships.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
queries | query | string[] | No | Default [] | Filterable fields: userId, teamId, invited, joined, confirm, roles |
search | query | string | No | Fuzzy search term (up to 256 characters), covering member names and emails | |
total | query | boolean | No | Default true | Pass false to skip counting |
Output: 200, returning the membershipList model: total + memberships[]. For the membership field structure, see POST /v1/teams/{teamId}/memberships.
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of memberships |
| memberships[] | membership[] | Membership object |
Call example:
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>"Response example:
{
"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
Add a member to a team and trigger an invitation. If the member already exists (by userId), they are associated directly; when only email/phone is provided, a user is created first and the invitation email flow is followed. Rate limited to 10 requests per hour.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
email | body | string | No | New member email; provide at least one of userId/phone | |
userId | body | string | No | Existing user ID; provide at least one of email/phone | |
phone | body | string | No | Phone number (including country code starting with +); provide either this or email/userId | |
roles | body | string[] | Yes | Up to 100 items, each up to 81 characters | Array of roles within the team; roles are arbitrary strings, and team:<teamId>/<role> permission checks are based on them |
url | body | string | No | Redirect URL for the invitation email; can be omitted when calling with an API Key. Only hostnames in the project's platform allowlist are permitted (to prevent open redirects) | |
name | body | string | No | New member name, up to 128 characters |
Output: 201, returns a membership model (confirm=false indicates not yet confirmed). Full field table:
| Field | Type | Description |
|---|---|---|
| $id | string | Membership ID |
| $createdAt / $updatedAt | string | Creation/update time (ISO 8601) |
| userId | string | Member user ID |
| userName / userEmail | string | Member name/email (may be hidden in the Console via privacy settings) |
| teamId / teamName | string | Team ID/name the member belongs to |
| invited | string | Invitation time (ISO 8601) |
| joined | string | Time the invitation was accepted (ISO 8601; empty if not accepted) |
| confirm | boolean | Whether joining has been confirmed |
| mfa | boolean | Whether MFA is enabled for this member |
| roles | string[] | Roles within the team (basis for team:<teamId>/<role> permission checks) |
Call example:
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"
}'Response example:
{
"$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"
]
}The invitation secret appears only in this endpoint's response and in the invitation email, for the invited user to complete joining via the confirmation endpoint; the server should forward it to the invited user and should not confirm on their behalf.
GET /v1/teams/{teamId}/memberships/{membershipId}
Get a team membership by ID.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
membershipId | path | string | Yes | Membership ID |
Output: 200, returning the membership model; see fields in POST /v1/teams/{teamId}/memberships.
Call example:
curl \
"https://<your-endpoint>/v1/teams/66a9d93000b1a/memberships/66a9d94f00e3d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$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}
Replace the member's role array within the team wholesale. Role changes take effect immediately on team:<teamId>/<role> permission checks.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
membershipId | path | string | Yes | Membership ID | |
roles | body | string[] | Yes | Up to 100 items, each up to 81 characters | The complete new role array (full replacement semantics) |
Output: 200, returning membership (focus on the roles field). For full fields, see POST /v1/teams/{teamId}/memberships.
| Field | Type | Description |
|---|---|---|
| roles | string[] | The role array after replacement |
Call example:
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"
]
}'Response example:
{
"$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
Confirm joining a team with the invitation secret: after confirmation, confirm is set to true and joined is filled with the confirmation time. The spec marks this endpoint with the public scope—it is designed to be called by the invited user (using the secret from the email); server-side integrations generally do not call it directly.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
membershipId | path | string | Yes | Membership ID | |
userId | body | string | Yes | Invited user ID | |
secret | body | string | Yes | Invitation secret (from the create-member response or the invitation email) |
Output: 200, returns membership (with confirm set to true and joined filled with the confirmation time). See POST /v1/teams/{teamId}/memberships for full fields.
Call example:
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"
}'Response example:
{
"$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"
]
}This endpoint does not check resource-level permissions: confirmation succeeds as long as a valid secret and the correct userId are presented; a leaked secret is equivalent to allowing others to join the team.
DELETE /v1/teams/{teamId}/memberships/{membershipId}
Remove a team member. All team:<teamId>-based permissions of that member take effect immediately invalid.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
membershipId | path | string | Yes | Membership ID |
Output: 204 No Content, no response body.
Call example:
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
Read team preferences (free-form key-value JSON).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID |
Output: 200, returns a preferences key-value object.
Call example:
curl \
"https://<your-endpoint>/v1/teams/66a9d93000b1a/prefs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"theme": "pink",
"timezone": "UTC"
}PUT /v1/teams/{teamId}/prefs
Overwrite team preferences wholesale: the passed object fully replaces existing preferences (unlike the merge semantics of user preferences).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
teamId | path | string | Yes | Team ID | |
prefs | body | object | Yes | The complete preferences key-value object |
Output: 200, returns the overwritten preferences object.
Call example:
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"
}
}'Response example:
{
"theme": "dark",
"timezone": "Asia/Shanghai"
}Errors and boundaries
Team does not exist:
404+team_not_found; membership does not exist:team_invite_not_found.When creating a member, at least one of
email/userId/phonemust be provided; creation fails ifuserIdrefers to a nonexistent user and no reachableemail/phoneexists.Roles are free-form strings: no pre-registration is needed before writing;
team:<teamId>/<role>permission strings become invalid immediately once the role is removed.Deleting a team cascades to delete all memberships; resource permission strings referencing that team become invalid immediately.
The invitation confirmation endpoint requires the invitation
secret; the secret is only delivered in the create-member response and the invitation email, and the server should forward it to the invited user rather than confirm on their behalf.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
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 |