# Team members
Easily add or remove users from teams, as well as fine-tune their specific roles within a team to ensure secure, well-organized collaboration.
## The TeamMember object
```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"TeamMember":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/TeamMemberRole"}},"required":["role"]},"TeamMemberRole":{"type":"string","description":"\"The role of a team member.\n\"owner\": Can manage team members.\n\"member\": Is a member of the team.\n","enum":["owner","member"]}}}}
```
## List all team members
> Lists members, and their roles, for the specified organization team.
```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"team-members","description":"Easily add or remove users from teams, as well as fine-tune their specific roles within a team to ensure secure, well-organized collaboration.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"TeamMember\" grouped=\"false\" %}\n The TeamMember object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"OrganizationTeamMember":{"type":"object","description":"A member of a team in an organization, including its relationship to it","properties":{"organization":{"description":"User information as an organization member","$ref":"#/components/schemas/OrganizationMember"},"team":{"description":"User information as a team member","$ref":"#/components/schemas/TeamMember"},"permissions":{"type":"object","description":"The set of permissions for the team member","properties":{"view":{"type":"boolean","description":"Can the user view the team member"}},"required":["view"]}},"required":["organization","team","permissions"]},"OrganizationMember":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"member\"","enum":["member"]},"id":{"type":"string","description":"Unique identifier for the user."},"role":{"$ref":"#/components/schemas/MemberRoleOrGuest"},"user":{"$ref":"#/components/schemas/User"},"disabled":{"type":"boolean","description":"Whatever the membership of this user is disabled and prevent them from accessing content."},"joinedAt":{"description":"Date at which the user joined the organization.","$ref":"#/components/schemas/Timestamp"},"lastSeenAt":{"description":"Date at which the user was last seen active in the organization.","$ref":"#/components/schemas/Timestamp"},"sso":{"type":"boolean","description":"Whether the user can login with SSO."},"spaces":{"type":"number"},"teams":{"type":"number"},"sites":{"type":"number"}},"required":["object","id","role","user","disabled","joinedAt","sso","spaces","teams","sites"]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]},"User":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"user\"","enum":["user"]},"id":{"type":"string","description":"Unique identifier for the user"},"displayName":{"type":"string","description":"Full name for the user"},"email":{"type":"string","description":"Email address of the user"},"photoURL":{"type":"string","description":"URL of the user's profile picture"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["location"]}},"required":["object","id","displayName","urls"]},"Timestamp":{"type":"string","format":"date-time"},"TeamMember":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/TeamMemberRole"}},"required":["role"]},"TeamMemberRole":{"type":"string","description":"\"The role of a team member.\n\"owner\": Can manage team members.\n\"member\": Is a member of the team.\n","enum":["owner","member"]}}},"paths":{"/orgs/{organizationId}/teams/{teamId}/members":{"get":{"operationId":"listTeamMembersInOrganizationById","summary":"List all team members","description":"Lists members, and their roles, for the specified organization team.\n","tags":["team-members"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/teamId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationTeamMember"}}}}]}}}}}}}}}
```
## Updates members of a team
> Updates members of an organization team, either adding or removing them. If a the same user is included as both an add and a remove, they will be removed from the team.
```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"team-members","description":"Easily add or remove users from teams, as well as fine-tune their specific roles within a team to ensure secure, well-organized collaboration.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"TeamMember\" grouped=\"false\" %}\n The TeamMember object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"UpdateMembersInOrganizationTeam":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string","description":"A user to add. It can either be a user ID or an email."}},"memberships":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TeamMember"}},"remove":{"type":"array","items":{"type":"string","description":"A user to remove. It can either be a user ID or an email."}}}},"TeamMember":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/TeamMemberRole"}},"required":["role"]},"TeamMemberRole":{"type":"string","description":"\"The role of a team member.\n\"owner\": Can manage team members.\n\"member\": Is a member of the team.\n","enum":["owner","member"]}}},"paths":{"/orgs/{organizationId}/teams/{teamId}/members":{"put":{"operationId":"updateMembersInOrganizationTeam","summary":"Updates members of a team","description":"Updates members of an organization team, either adding or removing them. If a the same user is included as both an add and a remove, they will be removed from the team.\n","tags":["team-members"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/teamId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMembersInOrganizationTeam"}}}},"responses":{"204":{"description":"Members have been updated"}}}}}}
```
## Add a team member
> Add or updates member in the specified organization team.
```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"team-members","description":"Easily add or remove users from teams, as well as fine-tune their specific roles within a team to ensure secure, well-organized collaboration.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"TeamMember\" grouped=\"false\" %}\n The TeamMember object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}},"userId":{"name":"userId","in":"path","required":true,"description":"The unique ID of the User","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"TeamMemberRole":{"type":"string","description":"\"The role of a team member.\n\"owner\": Can manage team members.\n\"member\": Is a member of the team.\n","enum":["owner","member"]}}},"paths":{"/orgs/{organizationId}/teams/{teamId}/members/{userId}":{"put":{"operationId":"addMemberToOrganizationTeamById","summary":"Add a team member","description":"Add or updates member in the specified organization team.\n","tags":["team-members"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/teamId"},{"$ref":"#/components/parameters/userId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/TeamMemberRole"}}}}}},"responses":{"204":{"description":"Member has been added to the team"}}}}}}
```
## Delete a team member
> Deletes member from the specified organization team.
```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"team-members","description":"Easily add or remove users from teams, as well as fine-tune their specific roles within a team to ensure secure, well-organized collaboration.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"TeamMember\" grouped=\"false\" %}\n The TeamMember object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}},"userId":{"name":"userId","in":"path","required":true,"description":"The unique ID of the User","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/orgs/{organizationId}/teams/{teamId}/members/{userId}":{"delete":{"operationId":"deleteMemberFromOrganizationTeamById","summary":"Delete a team member","description":"Deletes member from the specified organization team.\n","tags":["team-members"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/teamId"},{"$ref":"#/components/parameters/userId"}],"responses":{"204":{"description":"Member was not part of the team"},"205":{"description":"Member has been deleted from the team"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/teams/team-members.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.