Feeling bold?
Ask 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:

Prerequisites

  • A Sentry authentication

    tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
    with team:write scopes or higher and
    projectRepresents your service in Sentry and allows you to scope events to a distinct application.
    :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.

List an Organization's Teams

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

Find your organization ID

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

Make the cURL call

  1. Open your terminal.

  2. Save your auth

    tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
    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 our 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

    projectRepresents your service in Sentry and allows you to scope events to a distinct application.
    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"
            }
        ]
    }
]

Create a Team

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

    tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
    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

List an Organization's Teams

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

    tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
    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
  }
]
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
Suggest an edit to this page   |  Contribute to Docs   |  Report a problem