# 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"]}}}}}}}}
```