A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The BugSnag API is how an app or AI agent works with a BugSnag account: listing the errors on a project, reading the events behind an error, resolving errors, and tracking releases and stability over time. Access is granted through a personal auth token that acts as the user who created it, so a call reaches exactly the organizations and projects that user can reach, and that user's role decides what it can change. The API does not push events itself, though BugSnag, now SmartBear Insight Hub, can forward new errors through a separately configured webhook.
How an app or AI agent connects to BugSnag determines what it can reach. There is a route for making calls and a hosted server that exposes BugSnag tools to agents, and each is governed by the personal auth token behind it and the BugSnag access that token carries.
The Data Access API answers over HTTPS at https://api.bugsnag.com and returns JSON. A request selects version 2 with the X-Version header, or an Accept header of application/json; version=2, and authenticates with a personal auth token. It is the read and write API for organizations, projects, errors, events, and releases.
SmartBear's official MCP server connects an AI agent to BugSnag, now SmartBear Insight Hub, through the Model Context Protocol. The hosted remote server at https://bugsnag.mcp.smartbear.com/mcp uses an OAuth browser flow, while the npm package @smartbear/mcp can run locally with a BugSnag auth token and an optional project API key to scope searches to one project. The source is at github.com/SmartBear/smartbear-mcp.
BugSnag can post a payload to a receiver URL when a new error is reported, set up as a data-forwarding webhook integration in the dashboard. This is configured separately from the Data Access API, which itself does not push events.
A personal auth token is generated in the My Account section of BugSnag settings and sent as an Authorization header of 'token TOKEN', or as an auth_token query parameter. The token acts as the user who created it, so it reaches exactly the organizations and projects that user can reach, with no narrower per-endpoint scopes to set. What a call can do is then decided by that user's role, like project owner or organization administrator.
On an on-premise BugSnag installation, a request can authenticate with the user's email and password over HTTP Basic auth, sending an X-Bugsnag-API: true header. This route does not apply to the hosted service.
The BugSnag API is split into areas an agent can act on, like organizations, projects, errors, events, and releases. Each area has its own methods, and writes here resolve errors, change project settings, or delete error and event data.
List the organizations the token can reach, view an organization, and update or delete one.
List an organization's projects, view a project, create a project, and update one.
List the errors on a project, view a single error, update or resolve an error, and delete one.
List the events on an error or a project, view a single event, and view the latest event on an error.
List the pivots and their values that break an error or project down by event field, and read error and project trends over time.
List releases and release groups on a project, view a single release, and read a project's stability trend.
List the collaborators on an organization or project and view a single collaborator.
List the event fields a project captures and the saved searches stored on a project.
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 | |
|---|---|---|---|---|---|---|
OrganizationsList the organizations the token can reach, view an organization, and update or delete one.4 | ||||||
| GET | /user/organizations | List the organizations the authenticated user belongs to. | read | — | Current | |
Returns only the organizations the token's user can reach. The admin and per_page query parameters refine the list. The token carries the user's own access, with no per-endpoint scope to set. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /organizations | Create an organization. | write | — | Current | |
Whether this succeeds depends on the user's account and plan, not on a per-endpoint scope. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{id} | View an organization's details. | read | — | Current | |
Returns 404 rather than 403 when the token cannot see the organization, so it does not disclose that the organization exists. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /organizations/{id} | Update an organization's settings. | write | — | Current | |
Requires an organization administrator role on the user behind the token; otherwise the call returns API error code 40000. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsList an organization's projects, view a project, create a project, and update one.4 | ||||||
| GET | /organizations/{organization_id}/projects | List the projects in an organization. | read | — | Current | |
Returns only the projects the token's user can reach. Paginated through the Link header, with per_page up to 100. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /organizations/{organization_id}/projects | Create a project in an organization. | write | — | Current | |
Requires an organization administrator role on the user behind the token. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id} | View a project's details. | read | — | Current | |
Returns 404 rather than 403 when the token cannot see the project. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /projects/{project_id} | Update a project's settings. | write | — | Current | |
Requires a project owner or organization administrator role on the user behind the token. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ErrorsList the errors on a project, view a single error, update or resolve an error, and delete one.5 | ||||||
| GET | /projects/{project_id}/errors | List the errors on a project, with optional filters and sorting. | read | — | Current | |
Takes a filters parameter keyed by event field. Heavily sorted result sets are capped and return API error code 60000; set sort to unsorted, or add filters, for complete results. Acts onerror Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/errors/{error_id} | View a single error. | read | — | Current | |
An error groups together the events that share a root cause. Acts onerror Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /projects/{project_id}/errors/{error_id} | Update an error, for example to resolve, ignore, reopen, or reassign it. | write | — | Current | |
Resolving and reopening an error are operations on this endpoint, sent in the request body. Requires write access on the user behind the token. Acts onerror Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /projects/{project_id}/errors | Bulk update many errors in a project in one request. | write | — | Current | |
Applies the same change, such as resolving, across the errors selected by the request. Acts onerror Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{project_id}/errors/{error_id} | Permanently delete an error and its events. | write | — | Current | |
Irreversible. Removes the error group and the underlying event data. Acts onerror Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsList the events on an error or a project, view a single event, and view the latest event on an error.5 | ||||||
| GET | /projects/{project_id}/errors/{error_id}/events | List the events grouped under a single error. | read | — | Current | |
An event is a single occurrence of an error, carrying the metadata and diagnostics captured at the time. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/errors/{error_id}/latest_event | View the latest event recorded on an error. | read | — | Current | |
A shortcut to the most recent occurrence without listing all events. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/events | List the events across a whole project, with optional filters. | read | — | Current | |
For a live feed of new errors as they are reported, a webhook integration is set up in the dashboard instead of polling this endpoint. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/events/{event_id} | View a single event in full. | read | — | Current | |
Returns the full event including stacktrace, breadcrumbs, and any custom metadata fields. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{project_id}/events/{event_id} | Permanently delete a single event. | write | — | Current | |
Irreversible. Removes the one event occurrence. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Pivots & trendsList the pivots and their values that break an error or project down by event field, and read error and project trends over time.5 | ||||||
| GET | /projects/{project_id}/errors/{error_id}/pivots | List the pivots that break an error down by event field. | read | — | Current | |
A pivot groups an error's events by a chosen field, like browser or release stage, to show where it concentrates. Acts onpivot Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/errors/{error_id}/pivots/{event_field_display_id}/values | List the values of one pivot on an error, with counts. | read | — | Current | |
Returns each value of the chosen field and how many events carry it. Acts onpivot Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/pivots | List the pivots available across a project. | read | — | Current | |
The project-level version of pivots, breaking all errors down by field. Acts onpivot Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/errors/{error_id}/trend | Read how an error's event count trends over time, by bucket or resolution. | read | — | Current | |
Returns time-bucketed counts to chart whether an error is rising or falling. Acts ontrend Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/trend | Read how a project's overall event count trends over time. | read | — | Current | |
The project-level trend, aggregated across its errors. Acts ontrend Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Releases & stabilityList releases and release groups on a project, view a single release, and read a project's stability trend.5 | ||||||
| GET | /projects/{project_id}/releases | List the releases on a project. | read | — | Current | |
A release records a version of an app deployed to a stage, with its error and stability figures. Acts onrelease Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/releases/{release_id} | View a single release. | read | — | Current | |
Returns the release detail, including its sessions and error counts. Acts onrelease Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/release_groups | List the release groups on a project. | read | — | Current | |
A release group collects the releases that share a version across builds. Acts onrelease_group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /release_groups/{id} | Update a release group. | write | — | Current | |
Requires write access on the user behind the token. Acts onrelease_group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/stability_trend | View a project's stability trend, the share of sessions free of crashes over time. | read | — | Current | |
Stability is measured against the project's target, to see release health at a glance. Acts onstability_trend Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CollaboratorsList the collaborators on an organization or project and view a single collaborator.3 | ||||||
| GET | /organizations/{organization_id}/collaborators | List the collaborators on an organization. | read | — | Current | |
Returns the people who can reach the organization, with their email addresses and roles. Acts oncollaborator Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{organization_id}/collaborators/{id} | View a single collaborator on an organization. | read | — | Current | |
Returns one person's details, including their email address. Acts oncollaborator Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/collaborators | List the collaborators with access to a project. | read | — | Current | |
Returns the people who can reach this specific project. Acts oncollaborator Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Event fields & saved searchesList the event fields a project captures and the saved searches stored on a project.3 | ||||||
| GET | /projects/{project_id}/event_fields | List the event fields a project captures. | read | — | Current | |
Event fields are the metadata captured on events, both the defaults and any custom fields, and they are what filters and pivots key off. Acts onevent_field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /projects/{project_id}/saved_searches | List the saved searches stored on a project. | read | — | Current | |
A saved search is a set of filters and a sort order saved for reuse. Acts onsaved_search Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects/{project_id}/saved_searches | Create a saved search on a project. | write | — | Current | |
Stores a reusable filter and sort for the project. Requires write access on the user behind the token. Acts onsaved_search Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
The Data Access API does not push events. To learn about new errors as they are reported, an integration sets up a webhook in the BugSnag dashboard, which is configured separately from this read and write API.
| Event | What it signals | Triggered by |
|---|
BugSnag limits how fast an app or AI agent can call, through a per-token request quota measured over a rolling one-minute window, reported on every response.
BugSnag meters requests per personal auth token over a rolling one-minute window. Every request that is not rate limited carries an X-RateLimit-Limit header, the number of requests allowed in the window, and an X-RateLimit-Remaining header, the number left. Going over returns HTTP 429 with a Retry-After header that says how many seconds to wait before trying again. A separate cap protects heavy sorted queries: a result set sorted past a size threshold returns API error code 60000, and setting sort to unsorted or adding filters returns complete results.
List endpoints page through the Link header rather than hand-built URLs, since the pagination method can differ between resources. The Link header gives the next URL inside angled brackets with a rel of next. Results default to 30 per page, and the per_page parameter raises that up to 100, though some resources cap it lower and clamp anything higher to their maximum. Most list responses also carry an X-Total-Count header with the total number of matching results.
Responses are JSON over HTTPS, and timestamps come back in ISO 8601 form. A page returns at most 100 items, the per_page maximum, and the X-Total-Count header reports the full count behind the pages.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing or the personal auth token is invalid. | Send a valid token in the Authorization header as 'token TOKEN', and regenerate it if it has been revoked. |
| 402 | Payment required | Access is restricted by billing. API error code 30000 is a lapsed payment, 31000 an expired trial or invalid subscription, and 32000 a lack of available seats for the user. | Update billing, select a plan, or free up a seat, depending on the code returned in the body. |
| 403 | Forbidden | The user behind the token lacks the role for the action. API error code 40000 means a higher project or organization role is required. | Use a token whose user has the needed role, such as project owner or organization administrator. |
| 404 | Not Found | The resource does not exist, or the token cannot see it. BugSnag returns 404 rather than 403 on purpose, so it does not disclose that hidden data exists. | Confirm the path is correct and the token's user has access to the organization or project. |
| 429 | Too Many Requests | The per-token rate limit for the one-minute window was exceeded. | Wait the number of seconds given in the Retry-After header before retrying. |
BugSnag pins the Data Access API to a major version that a request selects with a version header, so an integration only moves up when it chooses to.
Version 2 is the current major version of the BugSnag Data Access API. A request selects it explicitly with the X-Version: 2 header, or an Accept header of application/json; version=2, and authenticates with a personal auth token over HTTPS at https://api.bugsnag.com. Since SmartBear's acquisition of BugSnag the product is branded Insight Hub, with newer API documentation on the SmartBear developer portal, while the v2 reference remains the source for the endpoints here.
Version 1 was the original Data Access API. Version 2 superseded it and is the version an integration should select with the X-Version header. BugSnag announced the v2 API ahead of this current reference.
Pin the version header and move up on a schedule that suits the integration.
BugSnag product updates ↗Bollard AI sits between a team's AI agents and BugSnag. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.