Team Management API

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.

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}"

• 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

curl -H "Accept: application/json" \
https://app.swarmia.com/api/v0/teams?token=TOKEN

Parameters

Query parameters

token: string

The authentication token, for accessing the organization's endpoint

Response

Response codes

Code	Description
200	Ok

Example response

{
    "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": "[email protected]",
                    "githubUsername": "aimo",
                    "country": "NL",
                    "name": "Aimo K."
                },
                {
                    "id": "d7770e04-7155-40c9-ba24-fef7aef9b58f",
                    "email": "[email protected]",
                    "name": "Bumble Bee"
                }
            ]
        }
    ]
}

Response schema

{
  "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

curl -H "Content-Type: application/json" \
-X PUT https://app.swarmia.com/api/v0/teams?token=TOKEN \
-d '
{
	"teams": [{
		"name": "Engineering",
		"externalId": "engineering",
		"parentExternalId": null,
		"jiraProjectKeys": null,
		"teamAdmin": 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.

📢 Only leaf-teams in the hierarchy can have Jira projects assigned. Omit this field if the team is a parent team

teamAdmin <string> optional

The email address of the team's administrator 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 null: Removes any existing team administrator permissions for this team.

Validation:

• Must be a valid email address format

• The user must exist in the organization with the specified email

• If the email is invalid or the user doesn't exist, the API returns 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

---

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:

{
    "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.

{
    "teams": [
        {
            "id": "3eaa7913-cf0a-4ecb-a9b1-953444d3fdf4",
            "name": "Engineering",
            "externalId": "engineers",
            "parentExternalId": null,
            "members": []
        }
    ]
}

• Decorate that state with any new teams or memberships.

{
    "teams": [
        {
            "id": "3eaa7913-cf0a-4ecb-a9b1-953444d3fdf4",
            "name": "Engineering",
            "externalId": "engineers",
            "parentExternalId": null,
            "members": []
        },
        {
            "name": "Platform",
            "externalId": "platform",
            "parentExternalId": "engineers",
            "members": [{
	            "name": "Aimo",
	            "email": "[email protected]"
            }]
        }
    ]
}

• 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.