> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/accounts-api/api-reference/organizations/teams.md).

# Teams

## List teams

> List the teams inside an organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization teams.","name":"organization_team"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"limit":{"name":"limit","description":"Limits the number of results to return","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"direction":{"name":"reverse","description":"Order in which to retrieve the results","in":"query","schema":{"type":"boolean","default":false}},"cursor":{"name":"pageToken","description":"Pagination token that keeps of track of the current position in the list","in":"query","schema":{"type":"string"}}},"schemas":{"TeamList":{"type":"object","title":"TeamList","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Team"}}},"required":["results"]},"Team":{"type":"object","title":"Team","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"accessibility":{"type":"string","enum":["open","request-to-join","invite-only"]},"activeMemberCount":{"type":"integer","minimum":0},"pendingMemberCount":{"type":"integer","minimum":0},"featuredMembers":{"type":"array","minItems":0,"maxItems":5,"items":{"$ref":"#/components/schemas/TeamMemberReference"}},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles assigned to the team","items":{"$ref":"#/components/schemas/iam_role_ref"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","visibility","accessibility","activeMemberCount","pendingMemberCount","featuredMembers","createdAt","updatedAt"]},"TeamMemberReference":{"type":"object","title":"TeamMemberReference","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"responseBody":{"type":"object","title":"PaginatedList","description":"A list of results that supports pagination.","properties":{"nextPageToken":{"type":"string","description":"The token to fetch the next page of results. If empty, there are no more results to fetch."}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/teams":{"get":{"description":"List the teams inside an organization.","operationId":"listTeams","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/direction"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TeamList"},{"$ref":"#/components/schemas/responseBody"}]}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"List teams","tags":["organization_team"]}}}}
```

## Create team

> Create a new team inside the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization teams.","name":"organization_team"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateTeam":{"type":"object","title":"CreateTeam","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":"string","maxLength":256},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles assigned to the team","items":{"$ref":"#/components/schemas/iam_role_ref"}}},"required":["name","description"]},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"Team":{"type":"object","title":"Team","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"accessibility":{"type":"string","enum":["open","request-to-join","invite-only"]},"activeMemberCount":{"type":"integer","minimum":0},"pendingMemberCount":{"type":"integer","minimum":0},"featuredMembers":{"type":"array","minItems":0,"maxItems":5,"items":{"$ref":"#/components/schemas/TeamMemberReference"}},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles assigned to the team","items":{"$ref":"#/components/schemas/iam_role_ref"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","visibility","accessibility","activeMemberCount","pendingMemberCount","featuredMembers","createdAt","updatedAt"]},"TeamMemberReference":{"type":"object","title":"TeamMemberReference","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/teams":{"post":{"description":"Create a new team inside the organization.","operationId":"createTeam","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTeam"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create team","tags":["organization_team"]}}}}
```

## Get team

> Retrieve a single team.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization teams.","name":"organization_team"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Team":{"type":"object","title":"Team","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"accessibility":{"type":"string","enum":["open","request-to-join","invite-only"]},"activeMemberCount":{"type":"integer","minimum":0},"pendingMemberCount":{"type":"integer","minimum":0},"featuredMembers":{"type":"array","minItems":0,"maxItems":5,"items":{"$ref":"#/components/schemas/TeamMemberReference"}},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles assigned to the team","items":{"$ref":"#/components/schemas/iam_role_ref"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","visibility","accessibility","activeMemberCount","pendingMemberCount","featuredMembers","createdAt","updatedAt"]},"TeamMemberReference":{"type":"object","title":"TeamMemberReference","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/teams/{teamId}":{"get":{"description":"Retrieve a single team.","operationId":"getTeam","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Get team","tags":["organization_team"]}}}}
```

## Delete team

> Delete a team from an organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization teams.","name":"organization_team"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}}},"paths":{"/organizations/{organizationId}/teams/{teamId}":{"delete":{"description":"Delete a team from an organization.","operationId":"deleteTeam","responses":{"204":{"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Delete team","tags":["organization_team"]}}}}
```

## Update team

> Update a team's details.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization teams.","name":"organization_team"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UpdateTeam":{"type":"object","title":"UpdateTeam","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":"string","maxLength":256},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles assigned to the team","items":{"$ref":"#/components/schemas/iam_role_ref"}}}},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"Team":{"type":"object","title":"Team","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"accessibility":{"type":"string","enum":["open","request-to-join","invite-only"]},"activeMemberCount":{"type":"integer","minimum":0},"pendingMemberCount":{"type":"integer","minimum":0},"featuredMembers":{"type":"array","minItems":0,"maxItems":5,"items":{"$ref":"#/components/schemas/TeamMemberReference"}},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles assigned to the team","items":{"$ref":"#/components/schemas/iam_role_ref"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","visibility","accessibility","activeMemberCount","pendingMemberCount","featuredMembers","createdAt","updatedAt"]},"TeamMemberReference":{"type":"object","title":"TeamMemberReference","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/teams/{teamId}":{"patch":{"description":"Update a team's details.","operationId":"updateTeam","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTeam"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Update team","tags":["organization_team"]}}}}
```