Feeling bold?
Sentry's Docs BotAsk A Bot
Product
API
Changelog
Sandbox
Sign In

Tutorial: Create and List Teams with the Sentry API

This guide walks you through the basics of using Sentry's API to list the teams in an organization and create a new team.

APIs used in this tutorial:

  • A Sentry authentication token with team:write scopes or higher and project:read scopes or higher.

    If you don't have an authentication token, follow the Create a Sentry Authentication Token tutorial to create an organization auth token with the following permissions, or higher:

    • Organization: Read
    • Team: Write

We recommend using a free Sentry developer account for this tutorial.

First, you will use the List an Organization's Teams API to list all the teams in your organization.

The list teams API requires you to pass in the an organization id to list teams for.

You can find your organization ID in the browser URL of your Sentry instance. For example, https://test-org.sentry.io/.

  1. Open your terminal.

  2. Save your auth token and organization ID as environment variables for ease of use. Paste the following commands into your terminal, replacing <organization_id> with your organization ID and <auth_token> with the auth token you copied previously:

    Copied
    export SENTRY_ORG_ID=<organization_id>
export SENTRY_AUTH_TOKEN=<auth_token>

  3. Paste the following cURL command into your terminal:

    Copied
    curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=0" \
    -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN'

  4. Here's an example of what the output of the command should be, for an organization that has a team called "test-team":

    Copied
    [
  {
    "id": "4505449964175360",
    "slug": "test-team",
    "name": "test-team",
    "dateCreated": "2023-06-30T18:44:59.196618Z",
    "isMember": false,
    "teamRole": null,
    "flags": {
      "idp:provisioned": false
    },
    "access": [
      "alerts:read",
      "team:read",
      "member:read",
      "org:read",
      "project:releases",
      "project:read",
      "event:write",
      "event:read"
    ],
    "hasAccess": true,
    "isPending": false,
    "memberCount": 1,
    "avatar": {
      "avatarType": "letter_avatar",
      "avatarUuid": null
    },
    "orgRole": null
  }
]

    The output gives you details about the teams within the specified organization.

    If your organization has enough teams, the API will return paginated results. See Sentry's docs on Pagination to learn how to handle paginated results.

  5. [Optional] To list information about the projects associated with each team you can set the detailed query parameter to 1:

    Copied
    curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=1" \
    -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN'

    Here's an example of what that output might look like if "test-team" has one associated project named "test-project":

    Copied
    [
    {
    ...
        "orgRole": null,
        "externalTeams": [],
        "projects": [
            {
                "id": "4505506997403648",
                "slug": "test-project",
                "name": "test-project",
                "platform": "javascript-react",
                "dateCreated": "2023-07-10T20:29:17.426792Z",
                "isBookmarked": false,
                "isMember": false,
                "features": [
                    "alert-filters",
                    "minidump",
                    "race-free-group-creation",
                    "similarity-indexing",
                    "similarity-view",
                    "releases"
                ],
                "firstEvent": "2023-07-10T20:39:35.811000Z",
                "firstTransactionEvent": true,
                "access": [],
                "hasAccess": true,
                "hasMinifiedStackTrace": true,
                "hasMonitors": false,
                "hasProfiles": false,
                "hasReplays": true,
                "hasSessions": true,
                "isInternal": false,
                "isPublic": false,
                "avatar": {
                    "avatarType": "letter_avatar",
                    "avatarUuid": null
                },
                "color": "#bf853f",
                "status": "active"
            }
        ]
    }
]

Now that you know what teams already exist in your org, use the Create a New Team API to create another.

  1. Make sure your auth token and organization ID are both still stored as environment variables in your shell.

  2. Paste the following cURL command into your terminal:

    Copied
    curl -d "name=tutorial-team" -X POST "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/" \
    -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN'

    The name query parameter means the name of the created team should be "tutorial-team".

  3. Here's an example of what the output of the command should be:

    Copied
    {
  "id": "4505524553711616",
  "slug": "tutorial-team",
  "name": "tutorial-team",
  "dateCreated": "2023-07-13T22:54:05.074990Z",
  "isMember": false,
  "teamRole": null,
  "flags": {
    "idp:provisioned": false
  },
  "access": [
    "event:write",
    "member:read",
    "alerts:read",
    "project:releases",
    "project:read",
    "event:read",
    "team:read",
    "org:read"
  ],
  "hasAccess": true,
  "isPending": false,
  "memberCount": 0,
  "avatar": {
    "avatarType": "letter_avatar",
    "avatarUuid": null
  },
  "orgRole": null
}

  4. [Optional] To create a team where the slug value is different than the name value, you can specify both in your POST call, like so:

    Copied
    curl -d "name=tutorial-team&slug=tutorial-team-slug" -X POST "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/" \
    -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN'

Finally, call the List an Organization's Teams API one more time to make sure your new team is returned.

  1. Make sure your auth token and organization ID are both still stored as environment variables in your shell.

  2. Paste the following cURL command into your terminal:

    Copied
    curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=0" \
    -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN'

  3. Your response should contain an entry for your new "tutorial-team" and look something like this:

    Copied
    [
  {
    "id": "4505524236910592",
    "slug": "test-team",
    "name": "test-team",
    "dateCreated": "2023-07-13T21:33:31.686812Z",
    "isMember": false,
    "teamRole": null,
    "flags": {
      "idp:provisioned": false
    },
    "access": [
      "member:read",
      "alerts:read",
      "org:read",
      "project:read",
      "team:read",
      "project:releases",
      "event:read",
      "event:write"
    ],
    "hasAccess": true,
    "isPending": false,
    "memberCount": 1,
    "avatar": {
      "avatarType": "letter_avatar",
      "avatarUuid": null
    },
    "orgRole": null
  },
  {
    "id": "4505524616167424",
    "slug": "tutorial-team",
    "name": "tutorial-team",
    "dateCreated": "2023-07-13T23:09:58.243168Z",
    "isMember": false,
    "teamRole": null,
    "flags": {
      "idp:provisioned": false
    },
    "access": [
      "member:read",
      "alerts:read",
      "org:read",
      "project:read",
      "team:read",
      "project:releases",
      "event:read",
      "event:write"
    ],
    "hasAccess": true,
    "isPending": false,
    "memberCount": 0,
    "avatar": {
      "avatarType": "letter_avatar",
      "avatarUuid": null
    },
    "orgRole": null
  }
]