Docs
Contents

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

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 + pathPurpose
GET /teamsList teams
POST /teamsCreate a team
GET /teams/{teamId}Get a team
PUT /teams/{teamId}Update team name
DELETE /teams/{teamId}Delete a team
GET /teams/{teamId}/membershipsList team memberships
POST /teams/{teamId}/membershipsCreate 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}/statusConfirm joining with a secret
DELETE /teams/{teamId}/memberships/{membershipId}Remove a member
GET /teams/{teamId}/prefsRead team preferences
PUT /teams/{teamId}/prefsOverwrite 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:

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []Filterable fields: name, total (member count), billingPlan; use limit(n)/offset(n)/cursorAfter(...) for pagination
searchquerystringNoFuzzy search term (up to 256 characters), covering the team name
totalquerybooleanNoDefault truePass 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.

FieldTypeDescription
totalintegerTotal 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdbodystringYesTeam 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
namebodystringYesTeam name, up to 128 characters
rolesbodystring[]NoDefault ["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:

FieldTypeDescription
$idstringTeam ID
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
namestringTeam name
totalintegerCurrent total number of members
prefsobjectTeam 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
namebodystringYesNew team name, up to 128 characters

Output: 200, returning team (focus on the name field). For full fields, see POST /v1/teams.

FieldTypeDescription
namestringUpdated 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
queriesquerystring[]NoDefault []Filterable fields: userId, teamId, invited, joined, confirm, roles
searchquerystringNoFuzzy search term (up to 256 characters), covering member names and emails
totalquerybooleanNoDefault truePass false to skip counting

Output: 200, returning the membershipList model: total + memberships[]. For the membership field structure, see POST /v1/teams/{teamId}/memberships.

FieldTypeDescription
totalintegerTotal 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
emailbodystringNoNew member email; provide at least one of userId/phone
userIdbodystringNoExisting user ID; provide at least one of email/phone
phonebodystringNoPhone number (including country code starting with +); provide either this or email/userId
rolesbodystring[]YesUp to 100 items, each up to 81 charactersArray of roles within the team; roles are arbitrary strings, and team:<teamId>/<role> permission checks are based on them
urlbodystringNoRedirect 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)
namebodystringNoNew member name, up to 128 characters

Output: 201, returns a membership model (confirm=false indicates not yet confirmed). Full field table:

FieldTypeDescription
$idstringMembership ID
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
userIdstringMember user ID
userName / userEmailstringMember name/email (may be hidden in the Console via privacy settings)
teamId / teamNamestringTeam ID/name the member belongs to
invitedstringInvitation time (ISO 8601)
joinedstringTime the invitation was accepted (ISO 8601; empty if not accepted)
confirmbooleanWhether joining has been confirmed
mfabooleanWhether MFA is enabled for this member
rolesstring[]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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
membershipIdpathstringYesMembership 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
membershipIdpathstringYesMembership ID
rolesbodystring[]YesUp to 100 items, each up to 81 charactersThe 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.

FieldTypeDescription
rolesstring[]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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
membershipIdpathstringYesMembership ID
userIdbodystringYesInvited user ID
secretbodystringYesInvitation 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
membershipIdpathstringYesMembership 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam 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:

ParameterLocationTypeRequiredDefault/enumDescription
teamIdpathstringYesTeam ID
prefsbodyobjectYesThe 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

Correspondence with the Server SDK

service.methodEndpoint
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