A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Rollbar API is how an app or AI agent works with a Rollbar project: reporting errors as occurrences, listing and reading the items those occurrences group into, marking an item resolved or muted, recording deploys, and querying error trends. Access is granted through an access token sent in a request header, where a project token stays inside one project and an account token reaches account-wide settings, each scoped to read or write. Rather than a generic event feed, Rollbar sends a message to a configured channel, like Slack or a webhook, when an item matches a notification rule.
How an app or AI agent connects to Rollbar determines what it can reach. There is a route for working with one project's errors and a route for account-wide settings, plus a hosted server that exposes Rollbar tools to agents, and each is governed by the access token behind it and the scope that token carries.
The REST API answers at https://api.rollbar.com/api/1/. Every call sends an access token in the X-Rollbar-Access-Token header, and the type of token, project or account, read or write, decides what the call can reach.
Rollbar's official Model Context Protocol server lets an agent call Rollbar through MCP. It runs locally over stdio and is configured with a project access token in the ROLLBAR_ACCESS_TOKEN environment variable. Its tools include list-projects, list-items, get-item-details, get-top-items, get-deployments, get-version, get-replay, and update-item. The source is at github.com/rollbar/rollbar-mcp-server.
Rather than a generic event feed, Rollbar sends a message to a configured channel, like Slack, email, PagerDuty, or a webhook URL, when an item matches a rule. The rules are set per project through the notifications endpoints.
A project access token works inside one project and carries one or more scopes: read for GET calls, write for PATCH and DELETE calls, post_server_item for reporting server-side occurrences and deploys, and post_client_item for reporting from browser, Android, or iOS. The scope set is the real boundary on what the token can do.
An account access token works across the whole account and carries a read or a write scope. It is required for account-level work, like listing or creating projects, managing project access tokens, and reading users and teams. A project access token cannot reach these endpoints.
The Rollbar API is split into areas an agent can act on, like errors grouped into items, the raw occurrences behind them, deploys, projects, and notification rules. Each area has its own methods, and the token type decides whether a call stays inside one project or reaches the whole account.
List and read the errors Rollbar groups into items, report a new occurrence, and update an item's status, level, assignment, or snooze.
List the raw occurrences behind an item or across a project, read a single occurrence, and delete one.
Report a deploy, list deploys, read a single deploy, and update a deploy's status.
Aggregate occurrence counts over time, and run SQL-like queries over item and deploy data with Rollbar Query Language.
List, read, create, and delete projects, and manage each project's access tokens.
List and read the users and teams on an account, and see which projects and teams a user belongs to.
Configure a notification channel, like Slack, email, PagerDuty, or a webhook, and create, list, update, and delete the rules that decide when it fires.
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 | |
|---|---|---|---|---|---|---|
ItemsList and read the errors Rollbar groups into items, report a new occurrence, and update an item's status, level, assignment, or snooze.5 | ||||||
| GET | /api/1/items | List items (grouped errors) in a project, with optional filters and sorting. | read | read | Current | |
Needs a project access token with read scope. The token decides which single project is reachable. Acts onitem Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/item/{itemId} | Get a single item by its API id, which differs from the counter shown in the Rollbar web URL. | read | read | Current | |
Needs a project access token with read scope. The itemId is the id field from other calls, not the counter in the web URL. Acts onitem Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/item_by_counter/{counter} | Get a single item by the project counter shown in the Rollbar web URL. Responds with a redirect to the item by its id. | read | read | Current | |
Needs a project access token with read scope. The counter is the number visible in the item's web URL. Acts onitem Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/1/item/ | Report an occurrence, an exception or message, which Rollbar groups into an item. | write | post_server_item | Current | |
Server-side reporting uses a post_server_item token; client platforms, like browser, Android, or iOS, use a post_client_item token instead. Returns the occurrence UUID. Acts onitem Permission (capability) post_server_itemVersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the per-token occurrence rate limit SourceOfficial documentation ↗ | ||||||
| PATCH | /api/1/item/{itemId} | Update an item's status (active, resolved, or muted), level, title, assignment, resolved_in_version, or snooze. | write | write | Current | |
Needs a project access token with write scope. Setting status to resolved or muted is done here. Team assignment is available on Advanced and Enterprise plans only. Acts onitem Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OccurrencesList the raw occurrences behind an item or across a project, read a single occurrence, and delete one.4 | ||||||
| GET | /api/1/instances | List the raw occurrences across a project, most recent first. | read | read | Current | |
Needs a project access token with read scope. Acts onoccurrence Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/item/{itemId}/instances | List the occurrences that belong to a single item. | read | read | Current | |
Needs a project access token with read scope. Acts onoccurrence Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/instance/{instanceId} | Get a single occurrence by its id, including the full payload sent to Rollbar. | read | read | Current | |
Needs a project access token with read scope. The payload can contain whatever data the reporting app attached to the occurrence. Acts onoccurrence Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/1/instance/{instanceId} | Delete a single occurrence. | write | write | Current | |
Needs a project access token with write scope. The deletion is permanent. Acts onoccurrence Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DeploysReport a deploy, list deploys, read a single deploy, and update a deploy's status.4 | ||||||
| POST | /api/1/deploy | Report a deploy to a project, with the environment and code revision, and an optional status. | write | post_server_item | Current | |
Needs a project access token with post_server_item scope. A deploy reported with status started must be updated to succeeded, failed, or timed_out within the time window, or Rollbar marks it timed_out. Acts ondeploy Permission (capability) post_server_itemVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/deploys | List deploys in a project, most recent first, in pages of 20. | read | read | Current | |
Needs a project access token with read scope. Acts ondeploy Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/deploy/{deployId} | Get a single deploy by its id. | read | read | Current | |
Needs a project access token with read scope. Acts ondeploy Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/1/deploy/{deployId} | Update a deploy's status, such as marking it succeeded or failed after a started report. | write | write | Current | |
Needs a project access token with write scope. Acts ondeploy Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Metrics & RQLAggregate occurrence counts over time, and run SQL-like queries over item and deploy data with Rollbar Query Language.4 | ||||||
| POST | /api/1/metrics/occurrences | Get occurrence counts over a span of time, with filtering, grouping, aggregation, and a chosen granularity. | read | read | Current | |
Needs a project access token with read scope. The Metrics API is part of Rollbar Analyze, available on Advanced and Enterprise plans. Acts onmetric Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/1/rql/jobs/ | Create an RQL job, running a SQL-like query over item and deploy data with Rollbar Query Language. | read | read | Current | |
Needs a project access token with read scope, even though it is a POST, because the job only reads data. RQL is part of Rollbar Analyze, available on Advanced and Enterprise plans. Acts onrql job Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/rql/jobs/{jobId} | Check the status of an RQL job (new, running, success, failed, cancelled, or timed_out). | read | read | Current | |
Needs a project access token with read scope. Acts onrql job Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/rql/jobs/{jobId}/result | Get the result rows of a completed RQL job. | read | read | Current | |
Needs a project access token with read scope. Acts onrql job Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsList, read, create, and delete projects, and manage each project's access tokens.6 | ||||||
| GET | /api/1/projects | List all projects on the account. | read | read | Current | |
Account-level call: needs an account access token with read scope, not a project token. Acts onproject Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/project/{projectId} | Get a single project by its id. | read | read | Current | |
Account-level call: needs an account access token with read scope. Acts onproject Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/1/projects | Create a project, optionally duplicating settings from an existing project by id. | write | write | Current | |
Account-level call: needs an account access token with write scope. The name is up to 32 characters and must start with a letter. Acts onproject Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/1/project/{projectId} | Delete a project. | write | write | Current | |
Account-level call: needs an account access token with write scope. The deletion removes the project and its data. Acts onproject Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/project/{projectId}/access_tokens | List the access tokens for a project, including each token's scopes and rate limit. | read | read | Current | |
Account-level call: needs an account access token with read scope. The response includes the token values, which grant access to the project. Acts onaccess token Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/1/project/{projectId}/access_tokens | Create a project access token with chosen scopes. | write | write | Current | |
Account-level call: needs an account access token with write scope. The new token can carry read, write, post_server_item, and post_client_item scopes. Acts onaccess token Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & teamsList and read the users and teams on an account, and see which projects and teams a user belongs to.4 | ||||||
| GET | /api/1/users | List all users on the account. | read | read | Current | |
Account-level call: needs an account access token with read scope. The response includes people's names and email addresses. Acts onuser Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/user/{userId} | Get a single user by id. | read | read | Current | |
Account-level call: needs an account access token with read scope. Returns the person's name and email address. Acts onuser Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/teams | List all teams on the account. | read | read | Current | |
Account-level call: needs an account access token with read scope. Acts onteam Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/1/teams | Create a team. | write | write | Current | |
Account-level call: needs an account access token with write scope. Acts onteam Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Notification rulesConfigure a notification channel, like Slack, email, PagerDuty, or a webhook, and create, list, update, and delete the rules that decide when it fires.4 | ||||||
| PUT | /api/1/notifications/slack | Configure a notification channel for a project. The Slack channel is shown here; email, PagerDuty, and webhook follow the same pattern under their own channel segment. | write | write | Current | |
Needs a project access token with write scope. The channel segment is the integration name, such as slack, email, pagerduty, or webhook. Acts onnotification channel Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/1/notifications/slack/rules | Create a rule that decides when a notification channel fires for an item. Shown for the Slack channel; other channels follow the same pattern. | write | write | Current | |
Needs a project access token with write scope. Acts onnotification rule Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/1/notifications/slack/rules | List the rules configured for a notification channel. Shown for the Slack channel; other channels follow the same pattern. | read | read | Current | |
Needs a project access token with read scope. Acts onnotification rule Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/1/notifications/slack/rule/{ruleId} | Delete a single notification rule. Shown for the Slack channel; other channels follow the same pattern. | write | write | Current | |
Needs a project access token with write scope. Acts onnotification rule Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Rollbar does not push a generic event feed. Instead, a notification rule sends a message to a configured channel, like Slack, email, PagerDuty, or a webhook URL, when an item matches the rule, so an integration learns about new or reactivated errors without polling.
| Event | What it signals | Triggered by |
|---|
Rollbar limits how fast an app or AI agent can report occurrences through a rate limit set per access token, and rejects a single request whose body is too large.
Rollbar rate-limits occurrence reporting per access token, and each project access token can be given its own limit, set in the UI or through the access-token API. When a token's limit is reached, further POST calls to report items return 429 Too Many Requests until the window resets. The window starts when Rollbar receives the first occurrence and resets after the limit period, so a limit of 100 per minute resets a minute after the first call. Every response carries the headers X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Remaining-Seconds, and X-Rate-Limit-Reset, which report the limit, how many calls are left, the seconds until reset, and the reset time.
List endpoints page through results. Deploys return 20 per page through a page parameter that starts at 1, and other list endpoints accept page and, where supported, a limit parameter. The newest records are returned first.
Requests and responses are JSON sent over HTTPS. A single request body is capped, and a request over the maximum returns 413 Request entity too large. Occurrence payloads should stay well under the cap, since oversized payloads are rejected rather than truncated.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad request | The request was malformed and could not be parsed, for example invalid JSON in the body. | Fix the request body or parameters so the request is well-formed, then resend. |
| 403 | Access denied | The access token is missing or invalid, or it does not carry the scope the call needs, for example a read token used for a write call, or a project token used on an account-level endpoint. | Send a valid X-Rollbar-Access-Token with the right type and scope for the endpoint. |
| 404 | Not found | The URL is invalid or the referenced resource does not exist. | Check the path and the resource id, then retry. |
| 413 | Request too large | The request body exceeded the maximum size Rollbar accepts. | Reduce the payload, for example by trimming large occurrence data, and resend. |
| 422 | Unprocessable entity | The body was valid JSON, but a parameter was missing or invalid. | Read the message field, correct the named parameter, and resend. |
| 429 | Too many requests | The per-token rate limit was reached, so the request was not processed. | Wait for the window to reset, shown by the X-Rate-Limit-Reset and X-Rate-Limit-Remaining-Seconds headers, before retrying. |
Rollbar serves a single, continuously updated API under one path version. There is no dated version to pin, so new fields are added in place rather than behind a version flag.
The Rollbar API is served under one path version, /api/1/, and is not dated. There is no version header to send and no migration between dated versions. New fields and endpoints are added in place, so an integration tracks the current API rather than pinning a version. The official Model Context Protocol server and the Metrics and RQL endpoints, part of Rollbar Analyze, are recent additions on top of this single version.
An integration tracks the current API; there is no dated version to pin or migrate between.
Rollbar changelog ↗Bollard AI sits between a team's AI agents and Rollbar. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.