Team Public REST API

About

The Teams REST API enables you to build apps, script interactions, or develop any other type of integration with Atlassian teams.

Version

This documentation is for version 1 of the Teams REST API, which is the latest version.

Authentication and authorization

Get an API token

Basic auth requires API tokens. You generate an API token for your Atlassian account and use it to authenticate anywhere where you would have used a password. This enhances security because:

• you're not saving your primary account password outside of where you authenticate.
• you can quickly revoke individual API tokens on a per-use basis.
• API tokens will allow you to authenticate even if your Atlassian Cloud organization has two-factor authentication or SAML enabled. See the Atlassian Cloud Support API tokens article to discover how to generate an API token.

See the Atlassian Cloud Support API tokens article to discover how to generate an API token.

Simple example

Most client software provides a simple mechanism for supplying a user name (in our case, the email address) and API token that the client uses to build the required authentication headers. For example, you can specify the -u argument in cURL as follows

1
2
curl -u fred@example.com:freds_api_token \ 
  -X GET \ 
  -H "Content-Type: application/json" \ 
https://sitename.atlassian.net/gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}

Supply basic auth headers

You can construct and send basic auth headers. To do this you perform the following steps:

1. Generate an API token for your account using your Atlassian Account.
2. Build a string of the form useremail:api_token.
3. BASE64 encode the string.
   • Linux/Unix/MacOS:

     1
     2
     echo -n user@example.com:api_token_string | base64
     

   • Windows 7 and later, using Microsoft Powershell:

     1
     2
     $Text = ‘user@example.com:api_token_string’
     $Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)
     $EncodedText = [Convert]::ToBase64String($Bytes)
     $EncodedText
     

4. Supply an Authorization header with content Basic followed by the encoded string. For example, the string fred:fred encodes to ZnJlZDpmcmVk in base64, so you would make the request as follows:

1
2
curl -X GET \
    -H "Authorization: Basic ZnJlZDpmcmVk" \
    -H "Content-Type: application/json" \
    'https://sitename.atlassian.net/gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}'
  

Exceptions

Organization admins, unlike regular users, can also change any team and its members through the public API without being a member of the team.

Pagination

When you're making calls to the Team Get Members REST API, there’s a good chance the search will return a huge amount of results. We paginate results to help make responses easier to handle.

Set the first parameter

Set the first parameter to ensure you know how many results per page you'll get. The maximum number of results we can return is 50.

Your GET would look something like this:

1
2
curl -D- \
    -X POST \
    -H "Authorization: Basic ZnJlZDpmcmVk" \
    -H "Content-Type: application/json" \
    -H "Accept: */*" \
    -d '{
             "after": <optional-cursor-to-fetch-next-set-of-items>
             "first": 10
        }'
  'https://sitename.atlassian.net/gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}/members'

Show more results

This is indicated by the hasNextPage key in the response.

Fetching the next page of results

You can then make a call to return the next page. Use the endCursor from the earlier response here as input for the after parameter to get the next set of results.

Example response from a paginated endpoint

1
2
{
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "<cursor-feeds-into-after-parameter>"
  },
  "results": [
    ...
  ]
}

Rest APIs

Create a team

POST /gateway/api/public/teams/v1/org/{orgId}/teams/

Creates a team, and adds the requesting user as the initial member.

API Reference

Get a single team

GET /gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}

Get the information of the team.

API Reference

Delete a team

DELETE /gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}

Delete the team.

API Reference

Modify a team

PATCH /gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}

Update the details of the team.

API Reference

Fetch a set of membership(s).

POST /gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}/members

Fetch members of the specified team.

API Reference

Add a set of membership(s).

POST /gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}/members/add

Add members to a team.

API Reference

Remove a set of membership(s).

POST /gateway/api/public/teams/v1/org/{orgId}/teams/{teamId}/members/remove

Remove members from a team

API Reference