Team
A team is a sub-group of a work group. Teams are small and self managing with a team leader. An example hierarychy may be.
- Workgroup: Engineering Department
- Teams: Systems Team, Structural Team, Mechanical Team, Electrical Team
Team Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the team's id |
| organisation_id | snowflake | the team's organisation id |
| workgroup_id | snowflake | the workgroup's id |
| name | string | the team's name (2-20 characters) |
| description | string | a description of the team |
| color | string | an rgb colour in hex format (e.g. #RRGGBB) |
Team Member Object
| Field | Type | Description |
|---|---|---|
| user | user object | the user who is a member of the team |
| is_leader | boolean | whether the user is a team leader |
| joined_at | string | when the user joined the team (ISO8601 timestamp) |
List Teams
GET /workgroups/{workgroup.id}/teams
Returns a list of teams that belong to the workgroup. Requires membership in the organisation that owns the workgroup.
Error Responses
| Status Code | Description |
|---|---|
| 404 | The workgroup does not exist |
| 403 | The caller is not a member of the organisation |
Create Team
POST /workgroups/{workgroup.id}/teams
Create a new team inside the workgroup. Requires the MANAGE_TEAMS permission on the workgroup.
Request Body
| Field | Type | Description |
|---|---|---|
| name? | string | the team's name (2-20 characters) |
| colour | string | an RGB colour in hex format (e.g. #RRGGBB) |
Error Responses
| Status Code | Description |
|---|---|
| 400 | The workgroup is invalid |
| 403 | The caller lacks the MANAGE_TEAMS permission |
Add User To Team
PUT /workgroups/{workgroup.id}/teams/{team.id}/members/{user.id}
Adds a user to the specified team. Requires the MANAGE_TEAMS permission on the team or the caller to be a team leader.
Error Responses
| Status Code | Description |
|---|---|
| 400 | The team, workgroup, or user is invalid |
| 400 | The user is already a member of the team |
| 400 | The user is not a member of the organisation |
| 403 | The caller lacks the MANAGE_TEAMS permission |
Update Team Membership
PATCH /workgroups/{workgroup.id}/teams/{team.id}/members/{user.id}
Update a team membership (e.g. make/remove team leader). Requires the MANAGE_TEAMS permission or the caller to be a team leader.
Request Body
| Field | Type | Description |
|---|---|---|
| IsLeader | boolean | whether the user should be a team leader |
Error Responses
| Status Code | Description |
|---|---|
| 400 | The inputs are invalid |
| 400 | Attempting to change own leadership without permission |
| 403 | The caller lacks the MANAGE_TEAMS permission |
Remove User From Team
DELETE /workgroups/{workgroup.id}/teams/{team.id}/members/{user.id}
Removes a user from the team. Requires the MANAGE_TEAMS permission or the caller to be a team leader.
Team leaders are prevented from removing other team leaders unless they have
MANAGE_TEAMSpermission.
Error Responses
| Status Code | Description |
|---|---|
| 400 | The inputs are invalid |
| 403 | The caller lacks the MANAGE_TEAMS permission |
Get Team
GET /team/{team.id}
Returns the team object for the specified id. Requires membership in the organisation that owns the team.
Error Responses
| Status Code | Description |
|---|---|
| 404 | The team does not exist |
| 403 | The caller is not a member of the organisation |
Update Team
PATCH /team/{team.id}
Partially update a team. Only name and colour are accepted and will be updated if provided. Requires the MANAGE_TEAMS permission on the owning organisation.
Request Body
| Field | Type | Description |
|---|---|---|
| name? | string | the team's name (2-20 characters) |
| colour? | string | an RGB colour in hex format (e.g. #RRGGBB) |
Error Responses
| Status Code | Description |
|---|---|
| 400 | The input is invalid or the organisation is missing |
| 403 | The caller lacks the MANAGE_TEAMS permission |
Delete Team
DELETE /team/{team.id}
Deletes the team and removes all team members and permission grants. Requires the MANAGE_TEAMS permission on the owning organisation.
Error Responses
| Status Code | Description |
|---|---|
| 400 | The team or organisation is invalid |
| 403 | The caller lacks the MANAGE_TEAMS permission |
List Team Members
GET /team/{team.id}/members
Returns a list of users who are members of the team. Requires membership in the organisation that owns the team.
Error Responses
| Status Code | Description |
|---|---|
| 404 | The team does not exist |
| 403 | The caller is not a member of the organisation |