Teams
Teams, simplifies role and permission management by grouping users. Instead of assigning roles individually or at the stack level, you can directly assign roles to a team. This ensures that all team members share the same set of role permissions.
Get all teams
https://api.contentstack.io/v4/teamsThe Get all teams request returns comprehensive information about all the teams in your organization, so you can review how users are grouped and which organization roles, stack roles, and project roles each team carries.
Contentstack identifies the organization from the organization_uid request header and returns the teams that the requesting user can access. By default, the response is wrapped in a { count, teams } object and paginated, with x-total-results, x-skip, and x-limit returned as response headers. Use skip and limit to page through the results (default limit is 500), or set skip_pagination to “true” to receive every team as a plain array without the wrapper.
Refine the results with typeahead to match team names, user_uid or stack_api_key to filter by membership or stack mapping, and asc or desc to sort. Set include_user_details to “true” to expand each team’s users array from UID strings into full user objects, and group_roles_by_domain to “true” to add a rolesByDomain object that groups each team’s roles by domain. When the organization has no teams, the request returns a 204 response with no body.
{
"count": 2,
"teams": [
{
"_id": "65b*****************e9a",
"name": "Team A",
"description": "Marketing team",
"createdAt": "2024-02-01T09:55:46.703Z",
"createdBy": "blt**************f0",
"createdByUserName": "Jane Doe",
"updatedAt": "2024-02-01T09:56:36.724Z",
"updatedBy": "blt**************f0",
"updatedByUserName": "Jane Doe",
"organizationUid": "blt**************b5",
"users": [
"blt**************a0",
"blt**************8d"
],
"organizationRoles": [
"blt**************8d"
],
"stackRoleMapping": [
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************37"
]
}
],
"projectRoles": [
{
"projectUid": "blt**************p1",
"domain": "am",
"roles": [
"blt**************r1"
]
}
],
"__v": 0,
"uid": "65b*****************e9a"
},
{
"_id": "65b*****************892",
"name": "Sample Team",
"createdAt": "2024-01-31T11:52:27.049Z",
"createdBy": "blt**************f0",
"createdByUserName": "Jane Doe",
"updatedAt": "2024-01-31T11:52:27.049Z",
"updatedBy": "blt**************f0",
"updatedByUserName": "Jane Doe",
"organizationUid": "blt**************b5",
"users": [],
"organizationRoles": [],
"stackRoleMapping": [],
"projectRoles": [],
"__v": 0,
"uid": "65b*****************892"
}
]
}Get a single team
https://api.contentstack.io/v4/teams/{team_uid}The Get a single team request returns comprehensive information about one team in your organization, including its members and its assigned organization roles, stack role mappings, and project roles.
Pass the team’s UID as team_uid in the request path and your organization’s UID in the organization_uid header. By default, the users array contains user UID strings. Set include_user_details to “true” to expand them into full user objects that include uid, username, email, firstName, lastName, active, and orgInvitationStatus.
The uid and _id fields hold the same value; use either to reference the team in follow-up requests. A request for a team that does not exist returns a 404 error.
{
"_id": "65b*****************e9a",
"name": "Sample Team",
"description": "Marketing team",
"createdAt": "2024-02-01T09:55:46.703Z",
"createdBy": "blt**************f0",
"createdByUserName": "Sample User",
"updatedAt": "2024-02-01T09:56:36.724Z",
"updatedBy": "blt**************f0",
"updatedByUserName": "Sample User",
"organizationUid": "blt**************b5",
"users": [
"blt**************a0",
"blt**************8d"
],
"organizationRoles": [
"blt**************8d"
],
"stackRoleMapping": [
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************37"
]
}
],
"projectRoles": [
{
"projectUid": "blt**************p1",
"domain": "am",
"roles": [
"blt**************r1"
]
}
],
"__v": 0,
"uid": "65b*****************e9a"
}Create a team
https://api.contentstack.io/v4/teamsThe Create a team request creates a team in the specified organization and assigns its initial members and roles in a single call.
Provide the team name (required) and, optionally, a description. Add members through the users array, where each entry identifies a user by email or uid. Grant access by including organizationRoles (organization-level role UIDs), stackRoleMapping (per-stack role assignments), and projectRoles (project-scoped roles; the am domain is currently supported). The users and stackRoleMapping arrays are required, but you can send them empty.
On success, the request returns a 201 response with the created team, including its generated uid. The users array in the response contains UID strings; use the Get a single team request with include_user_details set to “true” to resolve full user objects. Invalid input, such as an unknown role or stack, returns a 400 error that identifies the failed field.
{
"name": "Team A",
"description": "Marketing team",
"users": [
{
"email": "[email protected]"
}
],
"organizationRoles": [
"blt**************8d"
],
"stackRoleMapping": [
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************f6"
]
}
],
"projectRoles": [
{
"projectUid": "blt**************p1",
"domain": "am",
"roles": [
"blt**************r1"
]
}
]
}{
"_id": "65b******************11",
"name": "Team A",
"description": "Marketing team",
"createdAt": "2024-02-01T11:01:33.399Z",
"createdBy": "blt**************f0",
"createdByUserName": "Jane Doe",
"updatedAt": "2024-02-01T11:01:33.399Z",
"updatedBy": "blt**************f0",
"updatedByUserName": "Jane Doe",
"organizationUid": "blt**************b5",
"users": [
"blt**************a0"
],
"organizationRoles": [
"blt**************8d"
],
"stackRoleMapping": [
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************f6"
]
}
],
"projectRoles": [
{
"projectUid": "blt**************p1",
"domain": "am",
"roles": [
"blt**************r1"
]
}
],
"__v": 0,
"uid": "65b******************11"
}Update a team
https://api.contentstack.io/v4/teams/{team_uid}The Update a team request modifies an existing team, including its name, description, members, organization roles, stack role mappings, and project roles.
This request replaces values rather than merging them. The users, organizationRoles, and stackRoleMapping values you send become the team’s complete set, so include every member and role you want to keep, not only the ones you are adding or changing. To clear one of these, send an empty array, for example "users": []. The projectRoles field behaves differently: it stays unchanged only when you omit it entirely, and sending it with any value, including [], replaces the existing project roles.
Pass the team’s UID as team_uid in the request path and your organization’s UID in the organization_uid header. On success, the request returns a 200 response with the updated team. Set include_user_details to “true” to receive full user objects in the response.
{
"name": "Team A",
"description": "Marketing team",
"users": [
{
"email": "[email protected]"
}
],
"organizationRoles": [
"blt**************8d"
],
"stackRoleMapping": [
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************f6"
]
}
],
"projectRoles": [
{
"projectUid": "blt**************p1",
"domain": "am",
"roles": [
"blt**************r1"
]
}
]
}{
"_id": "65b*****************e9a",
"name": "Team A",
"description": "Marketing team",
"createdAt": "2024-02-01T09:55:46.703Z",
"createdBy": "blt**************f0",
"createdByUserName": "Jane Doe",
"updatedAt": "2024-02-01T11:06:35.107Z",
"updatedBy": "blt**************f0",
"updatedByUserName": "Jane Doe",
"organizationUid": "blt**************b5",
"users": [
"blt**************21"
],
"organizationRoles": [
"blt**************8d"
],
"stackRoleMapping": [
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************f6"
]
}
],
"projectRoles": [
{
"projectUid": "blt**************p1",
"domain": "am",
"roles": [
"blt**************r1"
]
}
],
"__v": 0,
"uid": "65b*****************e9a"
}Delete a team
https://api.contentstack.io/v4/teams/{team_uid}The Delete a team request removes an existing team along with its members and assigned roles.
Deletion is a soft delete: Contentstack marks the team as deleted and excludes it from subsequent reads instead of removing the record permanently. Deleting a team revokes the access that the team granted through its organization, stack, and project roles, unless a member holds the same access through another team or a direct assignment.
Pass the team’s UID as team_uid in the request path and your organization’s UID in the organization_uid header. A successful request returns a 200 response, and deleting a team that does not exist returns a 404 error.
Get all users of team
https://api.contentstack.io/organizations/{organization_uid}/teams/{team_uid}/usersThe Get all users of team request retrieves information about all the users associated with a particular team.
Additionally, you can also set the query parameters: includeUserDetails or include_count to true to include user details and the count of users in the response.
Add users to team
{
"users": [
{
"uid": "blt**************f0",
"username": "jane_blt6266157b",
"email": "[email protected]",
"firstName": "Jane",
"lastName": "Doer",
"active": true,
"orgInvitationStatus": "accepted"
},
{
"uid": "blt**************8d",
"username": "john_blt28057039",
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"active": true,
"orgInvitationStatus": "accepted"
},
{
"uid": "blt**************21",
"username": "jane_blt9d1e076e",
"email": "[email protected]",
"firstName": "Jane",
"lastName": "Doe",
"active": true,
"orgInvitationStatus": "accepted"
},
{
"uid": "blt**************a0",
"username": "sample_blt03a1b0ad",
"email": "[email protected]",
"firstName": "Sample",
"lastName": "User",
"active": true,
"orgInvitationStatus": "accepted"
}
],
"count": 4
}Add users to team
https://api.contentstack.io/organizations/{organization_uid}/teams/{team_uid}/usersThe Add users to team request allows you to send invitations to add users and assign them organizational and stack roles.
NoteOnly the Owner or the Admin of the organization can add users to a team.
You need to pass the email IDs of the users in the request body as follows:
{
"emails": [ "[email protected]", "[email protected]"]
}Remove a user from team
{
"emails":["[email protected]", "[email protected]"]
}Remove a user from team
https://api.contentstack.io/organizations/{organization_uid}/teams/{team_uid}/users/{user_uid}The Remove a user from team request allows you to remove an existing user from a particular team.
NoteOnly the Owner or the Admin of the organization can remove users from a team.
All accounts registered with Contentstack are known as Users. An organization can have many users with varying permissions and roles.
Get all users of team
Get all stack role mapping
https://api.contentstack.io/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappingsThe Get all stack role mapping request allows you to retrieve details of all associated stacks for a specified team in your organization.
Add a stack role mapping
{
"stackRoleMappings": [
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************f6"
]
},
{
"stackApiKey": "blt**************fe",
"roles": [
"blt**************3a"
]
}
]
}Add a stack role mapping
https://api.contentstack.io/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappingsThe Add a stack role mapping request allows you to associate users from a specified team with the available stacks in your organization.
You need to pass the API key of the stack and the role UIDs in the request body as follows:
{
"stackApiKey": "stack_api_key",
"roles": [
"role_one_uid",
"role_two_uid"
]
}
Update a stack role mapping
{
"stackApiKey": "blt**************74",
"roles": [
"blt**************f6",
"blt**************37"
]
}{
"stackRoleMapping": {
"stackApiKey": "blt**************74",
"roles": [
"blt**************f6",
"blt**************37"
]
}
}Update a stack role mapping
https://api.contentstack.io/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappings/{stack_api_key}The Update a stack role mapping request allows you to update the stack roles for a specific stack in your organization. You need to pass the role UIDs in the request body as follows:
{
"roles": [
"role_uid"
]
}Remove a stack role mapping
{
"roles": [
"blt**************48",
"blt**************f4"
]
}{
"stackRoleMapping": {
"stackApiKey": "blt**************74",
"roles": [
"blt**************48",
"blt**************f4"
]
}
}Remove a stack role mapping
https://api.contentstack.io/organizations/{organization_uid}/teams/{team_uid}/stack_role_mappings/{stack_api_key}The Remove a stack role mapping request allows you to delete the associations of team users for a specified stack in your organization.
When adding users to a team, you have the option to simultaneously assign roles for the available stacks within the organization. This process involves mapping stack roles for all the users added to the team.