# Teams

Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management.

## The Team object

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"Team":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"team\"","enum":["team"]},"id":{"type":"string","description":"Unique identifier for the team"}},"required":["object","id"]}}}}
```

## GET /orgs/{organizationId}/teams

> List all teams

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"teams","description":"Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Team\" grouped=\"false\" %}\n    The Team 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"}},"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"}}},"OrganizationTeam":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"team\"","enum":["team"]},"id":{"type":"string","description":"Unique identifier for the team."},"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"},"members":{"type":"integer","description":"Count of members in this team."},"spaces":{"type":"number","description":"Count of spaces this team has access to."},"createdAt":{"description":"Date at which the team was created.","$ref":"#/components/schemas/Timestamp"},"permissions":{"type":"object","description":"The set of permissions for the team","properties":{"admin":{"type":"boolean","description":"Can the user manage the team"},"view":{"type":"boolean","description":"Can the user view the team and list its members"}},"required":["admin","view"]}},"required":["object","id","title","members","spaces","createdAt","permissions"]},"OrganizationTeamTitle":{"type":"string","description":"Title of the team","minLength":1,"maxLength":64},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/orgs/{organizationId}/teams":{"get":{"operationId":"listTeamsInOrganizationById","summary":"List all teams","tags":["teams"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"},{"in":"query","name":"owner","description":"The unique identifier of a member of the organization. Only teams they can manage will be returned.","schema":{"type":"string"}},{"in":"query","name":"title","description":"If provided, only teams whose name contains the given parameter will be returned. Case insensitive.","schema":{"type":"string"}}],"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/OrganizationTeam"}}}}]}}}}}}}}}
```

## PUT /orgs/{organizationId}/teams

> Create a team

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"teams","description":"Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Team\" grouped=\"false\" %}\n    The Team 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"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"OrganizationTeam":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"team\"","enum":["team"]},"id":{"type":"string","description":"Unique identifier for the team."},"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"},"members":{"type":"integer","description":"Count of members in this team."},"spaces":{"type":"number","description":"Count of spaces this team has access to."},"createdAt":{"description":"Date at which the team was created.","$ref":"#/components/schemas/Timestamp"},"permissions":{"type":"object","description":"The set of permissions for the team","properties":{"admin":{"type":"boolean","description":"Can the user manage the team"},"view":{"type":"boolean","description":"Can the user view the team and list its members"}},"required":["admin","view"]}},"required":["object","id","title","members","spaces","createdAt","permissions"]},"OrganizationTeamTitle":{"type":"string","description":"Title of the team","minLength":1,"maxLength":64},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/orgs/{organizationId}/teams":{"put":{"operationId":"createOrganizationTeam","summary":"Create a team","tags":["teams"],"parameters":[{"$ref":"#/components/parameters/organizationId"}],"responses":{"201":{"description":"Team has been created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationTeam"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"},"members":{"description":"A list of organization member identifiers","type":"array","items":{"type":"string"}}},"required":["title"]}}}}}}}}
```

## GET /orgs/{organizationId}/teams/{teamId}

> Get a team

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"teams","description":"Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Team\" grouped=\"false\" %}\n    The Team 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"},"OrganizationTeam":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"team\"","enum":["team"]},"id":{"type":"string","description":"Unique identifier for the team."},"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"},"members":{"type":"integer","description":"Count of members in this team."},"spaces":{"type":"number","description":"Count of spaces this team has access to."},"createdAt":{"description":"Date at which the team was created.","$ref":"#/components/schemas/Timestamp"},"permissions":{"type":"object","description":"The set of permissions for the team","properties":{"admin":{"type":"boolean","description":"Can the user manage the team"},"view":{"type":"boolean","description":"Can the user view the team and list its members"}},"required":["admin","view"]}},"required":["object","id","title","members","spaces","createdAt","permissions"]},"OrganizationTeamTitle":{"type":"string","description":"Title of the team","minLength":1,"maxLength":64},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/orgs/{organizationId}/teams/{teamId}":{"get":{"operationId":"getTeamInOrganizationById","summary":"Get a team","tags":["teams"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/teamId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationTeam"}}}}}}}}}
```

## DELETE /orgs/{organizationId}/teams/{teamId}

> Delete a team

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"teams","description":"Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Team\" grouped=\"false\" %}\n    The Team 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"}}},"paths":{"/orgs/{organizationId}/teams/{teamId}":{"delete":{"operationId":"removeTeamFromOrganizationById","summary":"Delete a team","tags":["teams"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/teamId"}],"responses":{"204":{"description":"The team did not exist in the organization."},"205":{"description":"The team was deleted from the organization."}}}}}}
```

## PATCH /orgs/{organizationId}/teams/{teamId}

> Update a team

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"teams","description":"Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Team\" grouped=\"false\" %}\n    The Team 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"},"OrganizationTeam":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"team\"","enum":["team"]},"id":{"type":"string","description":"Unique identifier for the team."},"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"},"members":{"type":"integer","description":"Count of members in this team."},"spaces":{"type":"number","description":"Count of spaces this team has access to."},"createdAt":{"description":"Date at which the team was created.","$ref":"#/components/schemas/Timestamp"},"permissions":{"type":"object","description":"The set of permissions for the team","properties":{"admin":{"type":"boolean","description":"Can the user manage the team"},"view":{"type":"boolean","description":"Can the user view the team and list its members"}},"required":["admin","view"]}},"required":["object","id","title","members","spaces","createdAt","permissions"]},"OrganizationTeamTitle":{"type":"string","description":"Title of the team","minLength":1,"maxLength":64},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/orgs/{organizationId}/teams/{teamId}":{"patch":{"operationId":"updateTeamInOrganizationById","summary":"Update a team","tags":["teams"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/teamId"}],"responses":{"200":{"description":"The team has been updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationTeam"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"}},"required":["title"]}}}}}}}}
```


---

# 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.md?ask=<question>
```

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.