# Use the Sentry API

Read issues and events through Sentry's own web API with a token, for sentry-cli, Sentry API clients and the Sentry MCP server.

Sentry's web API is served at `https://errors.<domain>/api/0/`, the **Sentry URL (sentry-cli)** a
project's **Setup** tab shows. `sentry-cli` uses it for releases, deploys and source-map uploads,
and Sentry API clients for reading issues and events. Replace _org-slug_ with your organization's
slug (the **Setup** tab shows it as **Organization slug**).

## Prerequisites

- A token: choose **Create token** on a project's **Setup** tab, or run
  `dcloud errors auth-tokens create` (see [Upload source maps](upload-source-maps.md)). Creating
  one needs `iam:CreateAccessKey` and `errors:UploadSourceMaps`. It is sent as
  `Authorization: Bearer <token>`.
- The token is an access key of yours limited to Error Tracking, so it reads what you may read:
  `errors:ListIssues` for issues and environments, and `errors:GetEvents` for events, on the
  projects concerned. The short-lived upload tokens a connected app's builds and CI jobs get can
  only upload; they read no issues or events.

## Read issues and events

| Endpoint                                                 | What                                                                                                                        |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `GET organizations/{org}/issues/`                        | Issues, with Sentry's search syntax, `sort`, `statsPeriod` and paging                                                       |
| `GET organizations/{org}/issues/{id or short id}/`       | One issue                                                                                                                   |
| `GET organizations/{org}/issues/{id}/events/latest/`     | Its latest event, source-mapped; also `oldest`, `recommended` (the latest) or an event id                                   |
| `GET organizations/{org}/events/?dataset=errors&field=…` | Error events as rows, or grouped with `count()`, `count_unique(user)`, `count_unique(issue)`, `last_seen()`, `first_seen()` |
| `GET organizations/{org}/events/validate/`               | Whether such a search is supported                                                                                          |
| `GET organizations/{org}/environments/`                  | The environments seen                                                                                                       |

```sh
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://errors.example.com/api/0/organizations/org-slug/issues/?query=is:unresolved"
```

The events search understands `level:`, `environment:`, `release:`, `issue:` (a short id),
`issue.id:`, `error.type:`, `user.id:`, `user.email:`, `user.username:`, `transaction:`,
`message:`, `title:`, `event.type:` and free text. Any other key is answered `400` with an error
naming the supported ones, never silently ignored; a negation (`!level:`) is not supported yet.

An issue's `permalink` in the answers is its page in the Deutsche Cloud Console. A Sentry web link on the
errors host (`https://errors.<domain>/organizations/…/issues/WEB-1A/`) redirects to the same page.
An issue list without `statsPeriod`, `start` or `end` covers the last 90 days.

## The Sentry MCP server

`@sentry/mcp-server` reads issues and events through these endpoints. Point it here and give it a
token:

```json
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": {
        "SENTRY_HOST": "errors.example.com",
        "SENTRY_AUTH_TOKEN": "<the token>",
        "DO_NOT_TRACK": "1"
      }
    }
  }
}
```

`DO_NOT_TRACK` asks the MCP server not to send its own telemetry to sentry.io. The API here is
read-only for issues: the MCP server's tools that change an issue (`update_issue`) or need parts of
Sentry's API beyond these endpoints (such as Session Replay or performance search) do not work.

## Related

- [Upload source maps](upload-source-maps.md)
- [Find and triage issues](triage-issues.md)
