# Team management ## Overview The team management API allows you to programmatically manage teams and team members in Swarmia, enabling you to sync team data from external systems like HR platforms or identity providers. The API provides two operations: * List organization's teams `GET /api/v0/teams` * Update organization's teams `PUT /api/v0/teams` ## Authentication Authentication works based on a token which you can generate [here](https://app.swarmia.com/settings/api-tokens). Two options are currently available: * Include an HTTP header like `Authorization: Bearer {TOKEN}` header in the request. Example request with the `curl` command line tool: `curl https://app.swarmia.com/api/v0/teams -H "Authorization: Bearer {TOKEN}"` * *(Only GET requests)* Pass the token as a value for the `token` query parameter. Example request line: `GET https://app.swarmia.com/api/v0/teams?token={TOKEN}` * **Security note**: even though Swarmia redacts secret tokens from query logs, please bear in mind that some other proxies might log query parameters before reaching Swarmia. ## List organization's teams `GET /api/v0/teams` Lists the current teams and their settings. > **Note:** If your teams contain members attached via GitHub teams, those won't be included in the response. Additionally, when using API-based team management, GitHub teams cannot be used as team members. > **Note:** Teams created through the Swarmia UI will have `externalId` set to `null` until you assign an `externalId` via the API. This is expected and normal for teams that haven't been migrated to API-based management yet. ### **Example query** ```bash curl -H "Accept: application/json" -H "Authorization: Bearer TOKEN" \ https://app.swarmia.com/api/v0/teams ``` ### Parameters #### Query parameters **token:** string The authentication token, for accessing the organization's endpoint ### Response Response codes | **Code** | **Description** | | -------- | --------------- | | 200 | Ok | #### **Example response** ```json { "teams": [ { "id": "3eaa7913-cf0a-4ecb-a9b1-953444d3fdf4", "parentId": null, "name": "Engineering", "externalId": "engineering", "parentExternalId": null, "jiraProjectKeys": null, "members": [] }, { "id": "7e14ac2c-5090-4426-b371-4bee7e9ba2bb", "parentId": "3eaa7913-cf0a-4ecb-a9b1-953444d3fdf4", "name": "Platform team", "externalId": "platform-team", "parentExternalId": "engineering", "jiraProjectKeys": [ "PLA" ], "members": [ { "id": "87197b8b-20f8-4a8d-98c8-d4ccfc64c0b9", "email": "aimo@example.com", "githubUsername": "aimo", "country": "NL", "name": "Aimo K." }, { "id": "d7770e04-7155-40c9-ba24-fef7aef9b58f", "email": "bee@example.com", "name": "Bumble Bee" } ] } ] } ``` #### **Response schema** ```json { "title": "Teams", "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": ["null", "string"] }, "parentId": { "type": [ "null", "string" ] }, "parentExternalId": { "type": [ "null", "string" ] }, "jiraProjectKeys": { "type": ["null", "array"], "items": { "type": "string" } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": ["null", "string"] }, "githubUsername": { "type": "string" }, "country": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "name", "members" ] } } } } ``` ## Update organization's teams `PUT /api/v0/teams` Update teams of the organization. After the operation is complete all of the data is recalculated and the updates in the application can take a while to be visible. > ⚠️ This is a destructive operation. We recommend storing the current state of teams with the GET request before doing any changes. All teams not present in the query will be removed. ### **Example query** ```bash curl -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" \ -X PUT https://app.swarmia.com/api/v0/teams \ -d ' { "teams": [{ "name": "Engineering", "externalId": "engineering", "parentExternalId": null, "jiraProjectKeys": null, "teamAdmins": null, "members": [] }] }' ``` ### Parameters #### Query parameters `token` *string* The authentication token, for accessing the organization's endpoint #### Body parameters `teams` *Array* ***Team***** parameters** `id` *uuid* optional Swarmia identifier of the team *** `externalId` *string* required Identifier for the team used in the external system. This should not change between the updates. Otherwise a new team will be created and the returned Swarmia identifier will change. > **Note:** The `externalId` is your stable identifier for matching teams across API calls. It's different from Swarmia's internal `id` - you provide `externalId`, while Swarmia generates `id`. *** `name` *string* required Descriptive name of the team *** `members` *Array* required Array of team members. To remove all members from the team set this to `[]` *** `parentExternalId` *string* optional If the team is a child of another team, this is the reference to that team's `externalId` > 📢 A parent cannot have Jira projects mapped. The parent teams will inherit the issues from the child teams. When a team becomes a parent, the mapping is removed for that team. *** `jiraProjectKeys` Array<*string> optional* Array of Jira project keys, to assign for this team. If omitted no changes are made to the mapping. To remove the mapping set the value to `[]` or `null`. To skip affecting the field leave it `undefined` or omit the field from the request.\ \ All new Jira projects listed in the array, will be automatically synced to Swarmia. > 📢 Only leaf-teams in the hierarchy can have Jira projects assigned. Omit this field if the team is a parent team `teamAdmins` *string | Array\ | null* optional The email address(es) of the team's administrator(s) who will be granted `Manage Team Configuration` permissions. This field controls who can manage team settings and configurations. * **When string:** Assigns the specified user as the team administrator. * **When array:** Assigns multiple users as team administrators. Duplicate emails are automatically deduplicated. * **When null or empty array:** Removes all existing team administrator permissions for this team. **Validation:** * All emails must be in a valid email address format * Users must exist in the organization with the specified email * If an email is invalid, the API returns a 400 error * If a user doesn't exist for a given email, that email is silently ignored (warning logged server-side) > **Note:** The deprecated `teamAdmin` field is still supported for backwards compatibility but accepts the same values. Do not specify both `teamAdmin` and `teamAdmins` in the same request—this will return a 400 error. **Member** parameters `name` *string* required Name of the team member *** `email` *string* required Email of the team member. This field is required when creating or updating teams via the API. *** `githubUsername` *string* optional Member's Github username *** `country` *string* optional Member's country using ISO 3166-1 alpha-2 format (e.g., `US`, `NL`, `FI`). Must be exactly 2 uppercase characters. See the [full list of valid codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) *** If separate authors are found for the `email` and `githubUsername` they will get merged automatically, and only one author is retained. ### Response Response codes | **Code** | **Description** | | -------- | ---------------- | | 200 | Ok | | 400 | Validation error | * Parent team has `jiraProjectKeys` defined. Only leaf teams can have issue ownership definitions. * Multiple teams found with same `externalId` * Found team with incorrect `parentExternalId` * Cyclic dependency between parents and child teams | #### Example response Same as in `GET` request when the operation is successful #### Response schema Same as in `GET` request ## Taking the API into use > ⚠️ **Important:** Once you start using the API to manage teams, the team management UI in Swarmia becomes read-only. This prevents conflicts between API updates and manual UI changes. You can still view teams in the UI, but all modifications must be made through the API. ### With existing teams in Swarmia If you have existing teams created through the Swarmia UI, they will have `externalId` set to `null`. To migrate to API-based team management, you need to link these teams with your external system by assigning `externalId` values. **To not remove any existing team configuration**, send the existing Swarmia `id` along the new `externalId` with the first `PUT` request. * Take the current state using `GET /api/v0/teams`. This state includes our internal `id` for the teams. Teams created via the UI will have `externalId: null`. Example result: ```json { "teams": [ { "id": "3eaa7913-cf0a-4ecb-a9b1-953444d3fdf4", "name": "Engineering", "externalId": null, "parentExternalId": null, "members": [] } ] } ``` * Add `externalId` along with the `id` for all of the existing teams. ```json { "teams": [ { "id": "3eaa7913-cf0a-4ecb-a9b1-953444d3fdf4", "name": "Engineering", "externalId": "engineers", "parentExternalId": null, "members": [] } ] } ``` * Decorate that state with any new teams or memberships. ```json { "teams": [ { "id": "3eaa7913-cf0a-4ecb-a9b1-953444d3fdf4", "name": "Engineering", "externalId": "engineers", "parentExternalId": null, "members": [] }, { "name": "Platform", "externalId": "platform", "parentExternalId": "engineers", "members": [{ "name": "Aimo", "email": "aimo@swarmia.com" }] } ] } ``` * Send that state to Swarmia via the `PUT /api/v0/teams`. This request will retain the "Engineers" team and link it via the `externalId` and create a new team "Platform" as a sub-team of "Engineers". After this Swarmia will have linked the `externalId` to the correct teams. After the initial setup, we are able to match the teams with the `externalId`. So the `id` parameter is redundant in consecutive requests. > **Note:** After your first successful `PUT` request, Swarmia's team management UI becomes read-only. All future team updates must be made through the API to maintain consistency. ### Without existing teams No migration actions needed if you do not have any existing teams in Swarmia. --- # 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://help.swarmia.com/settings/integrations/swarmia-apis/team-management.md?ask= ``` 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.