A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Sentry API is how an app or AI agent works with a Sentry organization: listing and triaging the issues an application is reporting, reading the underlying error events, creating and updating projects, and recording releases and their deploys. Access is granted through an auth token and a set of scopes that decide what each call can read or write, and an agent is limited to the organization and the areas its scopes reach. Sentry can also push events to a receiver URL when something happens, such as an issue being created or an alert firing.
How an app or AI agent connects to Sentry determines what it can reach. There are a few routes, each governed by the token behind it and the scopes that token carries.
The web API answers at region domains such as us.sentry.io, de.sentry.io, and the default sentry.io, under the /api/0/ path. It is on a single version, v0, with public endpoints generally stable and beta endpoints subject to change.
Sentry hosts a remote MCP server at https://mcp.sentry.dev/mcp, launched June 2025, that lets an agent reach issues, errors, projects, and Seer analysis through the Model Context Protocol. It signs in with OAuth through an existing Sentry organization, with nothing to install. It exposes around 16 tools.
An internal integration registers a receiver URL and Sentry posts a JSON payload when a chosen resource fires. The Sentry-Hook-Resource header names the resource, and the Sentry-Hook-Signature header is an HMAC-SHA256 of the body using the client secret, which the receiver checks.
An internal integration created inside a Sentry organization issues a token that acts as the organization, with the scopes chosen when it was set up. It is the usual choice for an automation, because the scopes are explicit and it is not tied to one person's account.
An organization auth token authenticates as the organization and is passed as a Bearer token. It suits scripts and CI tasks that act for the organization rather than a single user.
A user auth token is created under a person's account settings with chosen scopes and acts as that user. Some endpoints require a token associated with a user rather than an organization.
A small set of endpoints can authenticate with a project's DSN, which acts as a client key, passed as 'Authorization: DSN
The Sentry API is split into areas an agent can act on, such as issues and events, projects, organizations, teams, and releases. Each area has its own methods and its own scopes, and some grant access to far more than others.
List a project's issues, retrieve, update, and delete a single issue, bulk-mutate a list of issues, and read the error events behind an issue or a project.
Create a project on a team, retrieve and update a project, delete a project, and list its observed users and client keys.
Retrieve an organization, update its settings, and list the projects it contains.
List an organization's teams, create a team, retrieve, update, and delete a team, and list its projects and members.
List and create releases, retrieve, update, and delete a release, and list and create the deploys recorded against a release.
List an organization's members, invite a new member, retrieve a member, update a member's roles, and remove a member.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Issues & eventsList a project's issues, retrieve, update, and delete a single issue, bulk-mutate a list of issues, and read the error events behind an issue or a project.9 | ||||||
| GET | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/issues/ | List the issues (grouped errors) bound to a project. | read | event:read | Current | |
Listing a project's issues is project-scoped in the path but governed by the event:read scope, not a project scope. Acts onissue Permission (capability) event:readVersionAvailable since the API’s base version Webhook event issueRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/issues/{issue_id}/ | Retrieve a single issue, with its basic stats, comment and user-report counts, and a summary of the latest event. | read | event:read | Current | |
Single-issue methods are organization-scoped in the path. Any of event:read, event:write, or event:admin satisfies this read. Acts onissue Permission (capability) event:readVersionAvailable since the API’s base version Webhook event issueRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/0/organizations/{organization_id_or_slug}/issues/{issue_id}/ | Update a single issue's attributes, such as status, assignee, or whether it is bookmarked. Only the fields sent are changed. | write | event:write | Current | |
Resolving, ignoring, and assigning all go through this method. event:admin also satisfies it. Acts onissue Permission (capability) event:writeVersionAvailable since the API’s base version Webhook event issueRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/0/organizations/{organization_id_or_slug}/issues/{issue_id}/ | Queue a single issue for asynchronous deletion. | write | event:admin | Current | |
Deleting an issue needs event:admin, the highest event level. Acts onissue Permission (capability) event:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/issues/ | Bulk-mutate attributes across a list of a project's issues, such as resolving or ignoring many at once. | write | event:write | Current | |
Bulk mutate is project-scoped in the path, unlike the single-issue methods, but is governed by event:write. Acts onissue Permission (capability) event:writeVersionAvailable since the API’s base version Webhook event issueRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/issues/{issue_id}/events/ | List the error events bound to an issue. | read | event:read | Current | |
Any of event:read, event:write, or event:admin satisfies this read. Acts onevent Permission (capability) event:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/issues/{issue_id}/events/{event_id}/ | Retrieve a single event associated with an issue. | read | event:read | Current | |
Any of event:read, event:write, or event:admin satisfies this read. Acts onevent Permission (capability) event:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/events/ | List the error events associated with a project. | read | project:read | Current | |
Project-level event listing uses a project scope, not event:read. Any of project:read, project:write, or project:admin satisfies it. Acts onevent Permission (capability) project:readVersionAvailable since the API’s base version Webhook event errorRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/events/{event_id}/ | Retrieve a single event within a project by its id. | read | project:read | Current | |
Any of project:read, project:write, or project:admin satisfies this read. Acts onevent Permission (capability) project:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsCreate a project on a team, retrieve and update a project, delete a project, and list its observed users and client keys.6 | ||||||
| POST | /api/0/teams/{organization_id_or_slug}/{team_id_or_slug}/projects/ | Create a new project bound to a team. | write | project:write | Current | |
A project is created under a team, so the path is team-scoped. project:admin also satisfies it. Acts onproject Permission (capability) project:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/ | Retrieve a single project within an organization. | read | project:read | Current | |
Any of project:read, project:write, or project:admin satisfies this read. Acts onproject Permission (capability) project:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/ | Update a project's attributes and configurable settings. | write | project:write | Current | |
project:admin also satisfies this write. Acts onproject Permission (capability) project:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/ | Schedule a project for asynchronous deletion. | write | project:admin | Current | |
Deleting a project needs project:admin, the highest project level. Acts onproject Permission (capability) project:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/users/ | List the users observed within a project, the people seen in its error reports. | read | project:read | Current | |
These are end users seen in events, not Sentry members. Any of project:read, project:write, or project:admin satisfies it. Acts onproject user Permission (capability) project:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/keys/ | List the client keys (DSNs) associated with a project. | read | project:read | Current | |
A client key is the DSN an SDK uses to send events. Any of project:read, project:write, or project:admin satisfies it. Acts onclient key Permission (capability) project:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsRetrieve an organization, update its settings, and list the projects it contains.3 | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/ | Retrieve a single organization, including its membership access and team information. | read | org:read | Current | |
Any of org:read, org:write, or org:admin satisfies this read. Acts onorganization Permission (capability) org:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/0/organizations/{organization_id_or_slug}/ | Update an organization's attributes and settings, such as name, slug, roles, privacy, and data scrubbing. | write | org:write | Current | |
org:admin also satisfies this write. Acts onorganization Permission (capability) org:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/projects/ | List the projects belonging to an organization. | read | org:read | Current | |
Any of org:read, org:write, or org:admin satisfies this read. Acts onproject Permission (capability) org:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsList an organization's teams, create a team, retrieve, update, and delete a team, and list its projects and members.7 | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/teams/ | List the teams belonging to an organization. | read | org:read | Current | |
Listing teams is governed by org:read, not team:read. Any of org:read, org:write, or org:admin satisfies it. Acts onteam Permission (capability) org:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/0/organizations/{organization_id_or_slug}/teams/ | Create a new team within an organization. | write | team:write | Current | |
org:write and org:admin also satisfy this write. Acts onteam Permission (capability) team:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/teams/{organization_id_or_slug}/{team_id_or_slug}/ | Retrieve a single team within an organization. | read | team:read | Current | |
Any of team:read, team:write, or team:admin satisfies this read. Acts onteam Permission (capability) team:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/0/teams/{organization_id_or_slug}/{team_id_or_slug}/ | Update a team's attributes and settings. | write | team:write | Current | |
team:admin also satisfies this write. Acts onteam Permission (capability) team:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/0/teams/{organization_id_or_slug}/{team_id_or_slug}/ | Schedule a team for asynchronous deletion, releasing its slug immediately. | write | team:admin | Current | |
Deleting a team needs team:admin, the highest team level. Acts onteam Permission (capability) team:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/teams/{organization_id_or_slug}/{team_id_or_slug}/projects/ | List the projects belonging to a team. | read | project:read | Current | |
Listing a team's projects uses a project scope. Any of project:read, project:write, or project:admin satisfies it. Acts onproject Permission (capability) project:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/teams/{organization_id_or_slug}/{team_id_or_slug}/members/ | List the members of a team, excluding pending invitations. | read | team:read | Current | |
Any of team:read, team:write, or team:admin satisfies this read. Acts onteam member Permission (capability) team:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReleasesList and create releases, retrieve, update, and delete a release, and list and create the deploys recorded against a release.7 | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/releases/ | List the releases recorded for an organization. | read | project:releases | Current | |
Releases use the dedicated project:releases scope rather than a project level. Acts onrelease Permission (capability) project:releasesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/0/organizations/{organization_id_or_slug}/releases/ | Create a new release for an organization, to correlate events with the release they came from. | write | project:releases | Current | |
Creating a release uses the project:releases scope. Acts onrelease Permission (capability) project:releasesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/releases/{version}/ | Retrieve a single release within an organization. | read | project:releases | Current | |
Reading a release also accepts org:ci, project:read, project:write, or project:admin. Acts onrelease Permission (capability) project:releasesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/0/organizations/{organization_id_or_slug}/releases/{version}/ | Update a release's metadata, such as its commit ref, URL, or release date. | write | project:releases | Current | |
Updating a release also accepts org:ci, project:write, or project:admin. Acts onrelease Permission (capability) project:releasesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/0/organizations/{organization_id_or_slug}/releases/{version}/ | Delete a release and all its associated files from an organization. | write | project:releases | Current | |
Deleting a release also accepts project:admin. Acts onrelease Permission (capability) project:releasesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/releases/{version}/deploys/ | List the deploys recorded against a release. | read | project:releases | Current | |
Reading deploys also accepts org:ci, project:read, project:write, or project:admin. Acts ondeploy Permission (capability) project:releasesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/0/organizations/{organization_id_or_slug}/releases/{version}/deploys/ | Record a deploy for a release version, such as a deploy to production. | write | project:releases | Current | |
Creating a deploy also accepts org:ci, project:write, or project:admin. Acts ondeploy Permission (capability) project:releasesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MembersList an organization's members, invite a new member, retrieve a member, update a member's roles, and remove a member.5 | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/members/ | List an organization's members, including pending invites awaiting acceptance. | read | member:read | Current | |
Any of member:read, member:write, or member:admin satisfies this read. Acts onmember Permission (capability) member:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/0/organizations/{organization_id_or_slug}/members/ | Add or invite a member to an organization, with the roles and team assignments given. | write | member:write | Current | |
member:invite and member:admin also satisfy this write. Acts onmember Permission (capability) member:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/0/organizations/{organization_id_or_slug}/members/{member_id}/ | Retrieve a single organization member, including pending invite status. | read | member:read | Current | |
Any of member:read, member:write, or member:admin satisfies this read. Acts onmember Permission (capability) member:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/0/organizations/{organization_id_or_slug}/members/{member_id}/ | Update a member's organization-level and team-level roles. | write | member:write | Current | |
member:invite and member:admin also satisfy this write. Acts onmember Permission (capability) member:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/0/organizations/{organization_id_or_slug}/members/{member_id}/ | Remove a member from an organization. | write | member:admin | Current | |
Removing a member needs member:admin, the highest member level. Acts onmember Permission (capability) member:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sentry can notify an app or AI agent when something happens, such as an issue being created or an alert firing, instead of the app repeatedly asking. An internal integration registers a receiver URL, and Sentry posts the event payload to it.
| Event | What it signals | Triggered by |
|---|---|---|
issue | Fires on activity on an issue, such as it being created, resolved, assigned, or ignored. The Sentry-Hook-Resource header is issue and the payload's action field names the change. | In-app only |
error | Fires when an error event is created, delivering the individual error to the receiver rather than the grouped issue. | In-app only |
event_alert | Fires when an issue alert rule is triggered, delivering the event that matched the alert. | In-app only |
metric_alert | Fires when a metric alert changes state, such as opening a critical or warning incident or resolving one. | In-app only |
comment | Fires when a comment is created, updated, or deleted on an issue. | In-app only |
installation | Fires when the integration is installed on or uninstalled from an organization. | In-app only |
Sentry limits how fast an app or AI agent can call, through a per-window request count and a separate cap on how many calls can run at once. Both are tied to the caller's identity rather than the token, so adding more tokens does not raise the ceiling.
Sentry rate-limits the web API in two ways at once. A per-window request count rejects calls once a caller exceeds the number allowed in the current time window, and a concurrency cap rejects calls when too many requests from the same caller are already in flight. The limiter keys on the caller's identity rather than the token or cookie, so issuing more tokens does not raise the ceiling. Every response carries the current state in headers: X-Sentry-Rate-Limit-Limit and X-Sentry-Rate-Limit-Remaining for the window, X-Sentry-Rate-Limit-Reset for when it resets as a Unix timestamp, and X-Sentry-Rate-Limit-ConcurrentLimit with X-Sentry-Rate-Limit-ConcurrentRemaining for the concurrency cap. A call that exceeds a limit returns 429, and Sentry recommends webhooks over polling to stay under the limits.
List endpoints use cursor-based pagination through the Link header. Each response returns both a previous and a next link, each marked results="true" or results="false" so a caller knows whether that page holds data, and the cursor is an opaque value passed back as the cursor query parameter. List endpoints commonly return 100 results per page. The next link should be followed rather than building the cursor by hand.
Requests and responses are JSON. Event and issue lists are paginated rather than returned whole, so size is controlled by following the cursor through the Link header rather than by a single large response.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The auth token is missing, invalid, or expired, so the request is not authenticated. | Send a valid token in the Authorization header, as 'Bearer |
| 403 | Forbidden | The request is authenticated but the token lacks the scope the endpoint requires, or the account cannot act on the resource. | Grant the missing scope, such as event:write to update an issue or project:admin to delete a project, then retry. |
| 404 | Not Found | The organization, project, team, issue, or other resource does not exist, or the token cannot see it. | Confirm the path and the organization or project identifier, and that the token has access to the resource. |
| 429 | Too Many Requests | A rate limit was exceeded, either the per-window request count or the concurrency cap. | Read the X-Sentry-Rate-Limit-Reset header and wait for the window to reset, or reduce concurrent requests, before retrying. |
Sentry's web API is on a single version, v0, with public endpoints generally stable and beta endpoints subject to change. There is no dated version to pin, so changes ship continuously and are tracked in the changelog.
The Sentry web API is on a single version, v0, served under the /api/0/ path. Public endpoints are generally stable, while endpoints marked beta can change. There is no dated version header, so changes ship continuously and are announced through the documentation changelog. The entries below are notable dated changes to the API and the way agents connect to Sentry.
The permissions documentation was updated to spell out the create, read, update, and delete operations for releases within the scope model, clarifying how project:releases and the org:ci scope govern release and deploy endpoints. Dated 30 March 2026 in the documentation changelog.
Sentry published a formal API deprecation policy describing how endpoints are retired or changed, giving integrations a defined process for handling removals on a single-version API. Dated 13 March 2026 in the documentation changelog.
Sentry launched a hosted, remote Model Context Protocol server at mcp.sentry.dev, letting an AI agent reach issues, errors, projects, and Seer analysis through MCP with OAuth sign-in and nothing to install. Announced on the Sentry blog on 10 June 2025.
An integration calls v0 directly; there is no version header to set.
Sentry documentation changelog ↗Bollard AI sits between a team's AI agents and Sentry. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.