> ## 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 API reference

> API reference for the Rollbar plugin in Corsair: every `rollbar.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Deploys

### create

`deploys.create`

Record a deploy with its environment, revision and optional status and comment; needs a project token with post\_server\_item scope

**Risk:** `write`

```ts theme={null}
await corsair.rollbar.api.deploys.create({ environment: 'production', revision: 'abc1234', comment: 'Ship it' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `environment` | `string` | Yes | The environment deployed to. |
| `revision` | `string` | Yes | The revision deployed, up to 40 characters. |
| `project_id` | `number` | No | — |
| `comment` | `string` | No | — |
| `local_username` | `string` | No | — |
| `rollbar_username` | `string` | No | — |
| `status` | `started \| succeeded \| failed \| timed_out` | No | — |

Needs a project token with `post_server_item`. Rollbar answers `{ data: { deploy_id } }`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `deploy_id` | `number \| null` | No | — |

***

### list

`deploys.list`

List deploys in a project, newest first, with page paging

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.deploys.list({ page: 1 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | 1-based page. Rollbar returns 20 per page unless `limit` is set. |
| `project_id` | `number` | No | Required with an account or personal access token, which Rollbar otherwise refuses with 403 "Requires project access". A project access token ignores it. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `deploys` | `object[]` | Yes | — |
| `page` | `number \| null` | Yes | — |
| `total_count` | `number \| null` | Yes | Total matches, or null when the project has more than 100,000 items. |

> [accordion] deploys full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   project_id?: number | null,
>   environment?: string | null,
>   revision?: string | null,
>   comment?: string | null,
>   status?: string | null,
>   local_username?: string | null,
>   user_id?: number | null,
>   username?: string | null,
>   start_time?: number | null,
>   finish_time?: number | null
> }[]
> ```

***

## Item Comments

### create

`itemComments.create`

Add a comment to an item, posted as the token owner; needs a personal access token with write scope and the project\_id

**Risk:** `write`

```ts theme={null}
await corsair.rollbar.api.itemComments.create({ item_id: 12345, project_id: 678, body: 'Fixed in the next deploy.' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `item_id` | `number` | Yes | — |
| `project_id` | `number` | Yes | The project that holds the item. Rollbar requires it here. |
| `body` | `string` | Yes | The comment text, sent to Rollbar as `comment`. |

Needs a personal access token with write scope and `project_id`; project and service tokens are refused. The text is sent as `comment`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `comment_id` | `number \| null` | No | — |
| `result` | `object \| null` | No | — |

> [accordion] result full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   type?: string | null,
>   source?: string | null,
>   item_id?: number | null,
>   user_id?: number | null,
>   username?: string | null,
>   text?: string | null,
>   timestamp?: number | null,
>   via_api?: boolean | null
> } | null
> ```

***

### list

`itemComments.list`

List the comments and resolve notes on an item, oldest first (Rollbar marks this route deprecated in favour of itemEvents.list)

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.itemComments.list({ item_id: 12345 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `item_id` | `number` | Yes | — |
| `project_id` | `number` | No | Required with an account or personal access token, which Rollbar otherwise refuses with 403 "Requires project access". A project access token ignores it. |
| `page` | `number` | No | 1-based page. Rollbar returns 20 per page unless `limit` is set. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `comments` | `object[]` | Yes | — |
| `page` | `number \| null` | Yes | — |
| `total_count` | `number \| null` | Yes | Total matches, or null when the project has more than 100,000 items. |

> [accordion] comments full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   type?: string | null,
>   source?: string | null,
>   item_id?: number | null,
>   user_id?: number | null,
>   username?: string | null,
>   text?: string | null,
>   timestamp?: number | null,
>   via_api?: boolean | null
> }[]
> ```

***

## Item Events

### list

`itemEvents.list`

List the history events for an item: status changes, assignments and comments

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.itemEvents.list({ item_id: 12345 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `item_id` | `number` | Yes | — |
| `project_id` | `number` | No | Required with an account or personal access token, which Rollbar otherwise refuses with 403 "Requires project access". A project access token ignores it. |
| `page` | `number` | No | 1-based page. Rollbar returns 20 per page unless `limit` is set. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `events` | `object[]` | Yes | — |
| `page` | `number \| null` | Yes | — |
| `total_count` | `number \| null` | Yes | Total matches, or null when the project has more than 100,000 items. |

> [accordion] events full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   type?: string | null,
>   item_id?: number | null,
>   user_id?: number | null,
>   username?: string | null,
>   timestamp?: number | null,
>   text?: string | null,
>   status?: string | null,
>   level?: string | null,
>   comment?: string | null
> }[]
> ```

***

## Items

### get

`items.get`

Fetch one item with its occurrence counts, timestamps and resolution state

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.items.get({ item_id: 12345 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `item_id` | `number` | Yes | — |
| `project_id` | `number` | No | Required with an account or personal access token, which Rollbar otherwise refuses with 403 "Requires project access". A project access token ignores it. |

With an account or personal access token, pass `project_id`; Rollbar answers 403 "Requires project access" without it.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `item` | `object` | Yes | — |

> [accordion] item full type
>
> ```ts theme={null}
> {
>   id?: number | string | null,
>   public_item_id?: number | null,
>   group_item_id?: number | null,
>   project_id?: number | null,
>   counter?: number | null,
>   title?: string | null,
>   hash?: string | null,
>   environment?: string | null,
>   platform?: string | null,
>   framework?: string | null,
>   level?: string | null,
>   status?: string | null,
>   group_status?: number | null,
>   total_occurrences?: number | null,
>   unique_occurrences?: number | null,
>   last_occurrence_id?: number | null,
>   last_occurrence_timestamp?: number | null,
>   first_occurrence_id?: number | null,
>   first_occurrence_timestamp?: number | null,
>   last_activated_timestamp?: number | null,
>   last_resolved_timestamp?: number | null,
>   last_modified_by?: number | null,
>   assigned_user_id?: number | null,
>   assigned_team_id?: number | null,
>   resolved_in_version?: string | null,
>   title_lock?: number | null,
>   level_lock?: number | null,
>   controlling_id?: number | null,
>   activating_occurrence_id?: number | null,
>   integrations_data?: string | Record<string, JsonValue> | null
> }
> ```

***

### list

`items.list`

List error items with status, level, environment and assignee filters plus page paging

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.items.list({ status: 'active', level: ['error', 'critical'], environment: 'production' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | 1-based page. Rollbar returns 20 per page unless `limit` is set. |
| `limit` | `number` | No | Records per page, up to 100. |
| `status` | `active \| resolved \| muted \| archived` | No | — |
| `level` | `(critical \| error \| warning \| info \| debug)[]` | No | Sent as a repeated parameter, so several levels can be asked for. |
| `environment` | `string` | No | — |
| `framework` | `string` | No | — |
| `query` | `string` | No | A search string. |
| `project_ids` | `number[]` | No | Account tokens only: search these projects. |
| `assigned_user` | `string` | No | A user id or email. |
| `assigned_team` | `string` | No | — |
| `is_snoozed` | `boolean` | No | — |

`level` and `project_ids` repeat the query parameter, so arrays send every value. Item `id` comes back as a numeric string and is returned as a number.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | — |
| `page` | `number \| null` | Yes | — |
| `total_count` | `number \| null` | Yes | Total matches, or null when the project has more than 100,000 items. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   id?: number | string | null,
>   public_item_id?: number | null,
>   group_item_id?: number | null,
>   project_id?: number | null,
>   counter?: number | null,
>   title?: string | null,
>   hash?: string | null,
>   environment?: string | null,
>   platform?: string | null,
>   framework?: string | null,
>   level?: string | null,
>   status?: string | null,
>   group_status?: number | null,
>   total_occurrences?: number | null,
>   unique_occurrences?: number | null,
>   last_occurrence_id?: number | null,
>   last_occurrence_timestamp?: number | null,
>   first_occurrence_id?: number | null,
>   first_occurrence_timestamp?: number | null,
>   last_activated_timestamp?: number | null,
>   last_resolved_timestamp?: number | null,
>   last_modified_by?: number | null,
>   assigned_user_id?: number | null,
>   assigned_team_id?: number | null,
>   resolved_in_version?: string | null,
>   title_lock?: number | null,
>   level_lock?: number | null,
>   controlling_id?: number | null,
>   activating_occurrence_id?: number | null,
>   integrations_data?: string | Record<string, JsonValue> | null
> }[]
> ```

***

### update

`items.update`

Update an item: its status, level, title, assignee, resolved-in version or snooze

**Risk:** `write`

```ts theme={null}
await corsair.rollbar.api.items.update({ item_id: 12345, status: 'resolved', resolved_in_version: '1.2.3' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `item_id` | `number` | Yes | — |
| `project_id` | `number` | No | Required with an account or personal access token, which Rollbar otherwise refuses with 403 "Requires project access". A project access token ignores it. |
| `status` | `active \| resolved \| muted` | No | — |
| `level` | `critical \| error \| warning \| info \| debug` | No | — |
| `title` | `string` | No | A new title, up to 255 characters. |
| `assigned_user_id` | `number \| null` | No | The user to assign, or null to clear the assignment. |
| `assigned_team_id` | `number \| null` | No | The team to assign, or null to clear the assignment. |
| `resolved_in_version` | `string` | No | The version the item is resolved in, up to 40 characters. |
| `snooze_enabled` | `boolean` | No | — |
| `snooze_expiration_in_seconds` | `number` | No | — |

A snooze needs a duration; `snooze_enabled` without `snooze_expiration_in_seconds` is rejected before the request.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `item` | `object` | Yes | — |

> [accordion] item full type
>
> ```ts theme={null}
> {
>   status?: string | null,
>   resolved_in_version?: string | null,
>   title?: string | null,
>   level?: string | null,
>   assigned_user_id?: number | null,
>   assigned_team_id?: number | null,
>   snooze_enabled?: boolean | null,
>   snooze_expiration_in_seconds?: number | null
> }
> ```

***

## Occurrences

### get

`occurrences.get`

Fetch one occurrence: its ids, timestamp and the payload the notifier sent under data (level, trace, request, person)

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.occurrences.get({ occurrence_id: 98765 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `occurrence_id` | `number` | Yes | — |
| `project_id` | `number` | No | Required with an account or personal access token, which Rollbar otherwise refuses with 403 "Requires project access". A project access token ignores it. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `occurrence` | `object` | Yes | — |

> [accordion] occurrence full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   project_id?: number | null,
>   item_id?: number | null,
>   timestamp?: number | null,
>   version?: number | null,
>   billable?: number | null,
>   data?: Record<string, JsonValue> | null
> }
> ```

***

### list

`occurrences.list`

List occurrences in a project with page paging, for a forward walk from a known id

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.occurrences.list({ page: 1, limit: 20 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | 1-based page. Rollbar returns 20 per page unless `limit` is set. |
| `limit` | `number` | No | Records per page, up to 5000. |
| `project_id` | `number` | No | Account tokens only: read this project. |
| `last_id` | `number` | No | Only occurrences after this id, for a forward walk. |

This route names occurrences `instances`; the plugin returns them as `occurrences`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `occurrences` | `object[]` | Yes | — |
| `page` | `number \| null` | Yes | — |
| `total_count` | `number \| null` | Yes | Total matches, or null when the project has more than 100,000 items. |

> [accordion] occurrences full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   project_id?: number | null,
>   item_id?: number | null,
>   timestamp?: number | null,
>   version?: number | null,
>   billable?: number | null,
>   data?: Record<string, JsonValue> | null
> }[]
> ```

***

## Projects

### list

`projects.list`

List the projects the token can see; needs an account or personal access token

**Risk:** `read`

```ts theme={null}
await corsair.rollbar.api.projects.list({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `projects` | `object[]` | Yes | — |

> [accordion] projects full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   name?: string | null,
>   account_id?: number | null,
>   status?: string | null,
>   date_created?: number | null,
>   date_modified?: number | null,
>   settings_data?: Record<string, JsonValue> | null
> }[]
> ```

***


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