> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Rollbar plugin

> Error monitoring with Rollbar - list and read error items and their occurrences, update an item's status, assignee or snooze, read an item's comments and events, comment on an item, and list and record deploys.

Use **Rollbar** through Corsair: one client, typed API calls.

Create an access token in Rollbar: a **project** token under **Settings → Project Access Tokens**, or an **account** token under **Settings → API access tokens**. Send it as the `X-Rollbar-Access-Token` header; the plugin never uses `Authorization` or the query string. Things to know before you call:

* **Every response carries `err`.** `err: 0` is success and anything else is a failure — and the HTTP status is not a reliable proxy for it. The live "access token required" response is a `401` with `{ "err": 1, "message": "access token required" }`, while a rejected item update can be a **`200` with `err: 1`**. The plugin reads `err` and turns a non-zero value into an error even on a 200.
* **Tokens are scoped, and no single token covers every operation.** A project token with `read` and `write` covers items, occurrences, events, comments (reading) and deploy listing for its own project; Rollbar will not give one token both `write` and `post_server_item`. `deploys.create` needs a project token with `post_server_item`. `projects.list` needs an account or personal access token. `itemComments.create` needs a personal access token with `write`, and posts as that user. With an account or personal token, pass `project_id` on the item and occurrence operations, or Rollbar answers `403` "Requires project access". A `401` means the token is missing or malformed; a `403` means it is valid but lacks the scope or project.
* **`instances` is the API's word for occurrences.** Rollbar lists occurrences at `/api/1/instances` and returns them under an `instances` key; the plugin exposes them as `occurrences` so the name matches the concept.
* **Repeated filters.** `level` and `project_ids` are repeated query parameters, so `items.list` takes arrays and sends each value under the same key. Rollbar's documented `ids` filter is not offered: in a live check it ignored one id and answered `502` to several.
* **Item ids.** `items.list` returns each `id` as a numeric string while `items.get` returns a number; the plugin returns a number from both.
* **Paging is a page number.** Lists return 20 per page by default (`items.list` 100) and the item, comment and event lists report `total_count` beside it, which is `null` when a project has more than 100,000 unique items. A snooze needs a duration, so `items.update` rejects `snooze_enabled` without `snooze_expiration_in_seconds`.
* **Timestamps are unix seconds**, on requests and responses alike.
* **Retries.** A `429` is the token's rate limit. Rollbar sends no `Retry-After`; the plugin waits for the time in `X-Rate-Limit-Remaining-Seconds` / `X-Rate-Limit-Reset` and backs off exponentially when neither is present. A `5xx` is retried only for a read; a body-level failure has no status and is never retried.
* **Deploys.** `deploys.create` answers `{ "data": { "deploy_id": … } }`, the one route without `err`/`result`; the plugin returns `deploy_id`. `deploys.list` has no environment filter (Rollbar ignores one).

**What you get:**

* 11 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/rollbar better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/rollbar better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/rollbar better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/rollbar better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { rollbar } from '@corsair-dev/rollbar';

export const corsair = createCorsair({
	plugins: [
		rollbar(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> No setup required yet. When you make your first request as a tenant, Corsair prompts for the API key.
>
> ```ts theme={null}
> rollbar()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'rollbar',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List errors in production**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.rollbar.api.items.list({ environment: 'production' });
```

**Snooze an item for an hour**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.rollbar.api.items.update({ item_id: 12345, snooze_enabled: true, snooze_expiration_in_seconds: 3600 });
```

See the full list on the [API](https://docs.corsair.dev/plugins/rollbar/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/rollbar/api.md)
>
> Every `rollbar.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.