---
title: API v3 reference
description: 'Reference for the Honeybadger API v3 (preview): 123 operations across 20 resources.'
url: https://docs.honeybadger.io/api/v3/
---

API v3 is in preview

You can use it today, but endpoints, parameters, and response shapes can change before general availability, including in ways that break existing code. API v2 is unchanged, and is documented in the [Data API (REST) v2 reference](https://docs.honeybadger.io/api/getting-started/).

Calling API v3 requires an [API token or an OAuth access token](https://docs.honeybadger.io/api/v3/authentication/). API tokens are opt-in during the preview.

Send feedback and bug reports to <support@honeybadger.io>.

The Honeybadger API manages your Honeybadger account. It’s a REST API: resources have predictable URLs, request and response bodies are JSON, and responses use standard HTTP status codes. All requests go over HTTPS.

Base URLs:

* US: `https://app.honeybadger.io/v3`
* EU: `https://eu-app.honeybadger.io/v3`

Use the one for the region your account is in.

## Authentication

Send an API token as a Bearer token:

```plaintext
Authorization: Bearer YOUR_API_TOKEN
```

The token decides which account and projects a request reaches, and its scopes decide what it can do; `GET /v3/token` shows both. A request needing a scope the token lacks answers 403 `insufficient_scope`. See [Authentication](https://docs.honeybadger.io/api/v3/authentication/) for the kinds of token and how to create one.

## Requests

Request bodies are JSON with the resource’s fields at the top level:

```json
{"name": "Billing API", "language": "ruby"}
```

Updates (PATCH) merge: send only the fields you’re changing. `null` clears a nullable field or resets it to its default; the field’s description says which. `[]` empties a list. Objects merge too, except a few that are replaced whole, which their descriptions say; `{}` empties one of those. The `data` object from a GET can be sent back as is: read-only fields are ignored.

## Responses

Every response body except the OpenAPI document itself is a JSON object with `meta`, plus `data` on success or `error` on failure:

```json
{
  "data": { ... },
  "meta": { "request_id": "..." }
}
```

A list puts an array in `data`. A paged list also adds `pagination` and `links` (see Pagination). An error replaces `data` with `error` (see Errors). Include `meta.request_id` when you contact support.

## Errors

An error response has an `error` object instead of `data`:

```json
{
  "error": { "code": "validation_error", "message": "...", "details": [...] },
  "meta": { "request_id": "..." }
}
```

Branch on `error.code`, not the message. A request that needs a feature the plan doesn’t include gets 403 `feature_unavailable`, and one past a plan limit gets 403 `limit_reached`.

## Pagination

Most lists are paged. Follow `links` to move between pages: `next` and `prev` on numbered lists, `older` and `newer` on time-ordered ones such as notices. A null link means there’s nothing further in that direction. Each list’s page size and other paging parameters are on its own page.

## Rate limits

360 requests per hour, unless a higher limit has been set. User tokens and OAuth grants share one limit per person; account tokens share one per account. Each response reports the limit:

* `X-RateLimit-Limit`: requests allowed per hour
* `X-RateLimit-Remaining`: requests left in the current hour
* `X-RateLimit-Reset`: Unix time when the limit resets

Over the limit, requests answer 429 `rate_limit_exceeded` with a `Retry-After` header.

## Migrating from v2

**Credentials.** v2 personal auth tokens don’t work with v3; create an API token instead. v3 only accepts Bearer token auth: HTTP basic (`curl -u TOKEN:`) answers 401 `unsupported_auth_scheme`, and a token in the `auth_token` query parameter answers 401 `credential_in_query`.

**IDs.** Projects and most other records have new IDs in v3, such as `Xk9mZp` instead of v2’s integers. Get them by listing through v3 (for example `GET /v3/projects`). Fault IDs keep their numbers, as strings.

**Accounts.** v2 picked the account with `/accounts/:id/` in the path or an `account_id` parameter. v3 takes it from the token:

| v2 | v3 |
| - | - |
| `/v2/accounts` | None. A v3 token is bound to one account; `GET /v3/token` gives its `account_id`. |
| `/v2/accounts/:id` | `/v3/account` |
| `/v2/accounts/:id/users` | `/v3/account/members` |
| `/v2/accounts/:id/invitations` | `/v3/account/invitations` |
| `/v2/accounts/:id/status_pages` | `/v3/status_pages` |
| `/v2/projects?account_id=ID` | `/v3/projects` |
| `/v2/teams?account_id=ID` | `/v3/teams` |

**Request bodies.** v2 wrapped the fields in the resource name; v3 doesn’t:

```json
{"project": {"name": "Billing API"}}
```

becomes

```json
{"name": "Billing API"}
```

**Responses.** v2 returned a single resource as a bare object and a list as `{"results": [...], "links": {...}}`. v3 puts both under `data`, as described in Responses above.

**Pagination.** On time-ordered lists such as notices and deploys, v2’s `links.next` (older items) and `links.prev` (newer items) are now `links.older` and `links.newer`.

## Resources

Every operation in this reference is generated from the API’s OpenAPI spec, which you can download as [YAML](https://docs.honeybadger.io/api/v3/openapi.yaml) or [JSON](https://docs.honeybadger.io/api/v3/openapi.json).

| Resource | Operations | Base path |
| - | - | - |
| Error tracking | | |
| Faults | 18 | `/projects/{project_id}/faults` |
| Notices | 2 | `/projects/{project_id}/faults/{fault_id}/notices` |
| Comments | 5 | `/projects/{project_id}/faults/{fault_id}/comments` |
| Deploys | 3 | `/projects/{project_id}/deploys` |
| Uptime monitoring | | |
| Uptime sites | 7 | `/projects/{project_id}/sites` |
| Check-ins | 7 | `/projects/{project_id}/check_ins` |
| Status pages | | |
| Status pages | 5 | `/status_pages` |
| Incidents | 10 | `/status_pages/{status_page_id}/incidents` |
| Insights | | |
| Insights | 1 | `/projects/{project_id}/insights/queries` |
| Streams | 1 | `/projects/{project_id}/streams` |
| Dashboards | 5 | `/projects/{project_id}/dashboards` |
| Alarms | 6 | `/projects/{project_id}/alarms` |
| Project settings | | |
| Projects | 8 | `/projects` |
| Environments | 7 | `/projects/{project_id}/environments` |
| Integrations | 5 | `/projects/{project_id}/integrations` |
| Ingestion keys | 5 | `/projects/{project_id}/ingestion_keys` |
| Account | | |
| Accounts | 11 | `/account` |
| Teams | 14 | `/teams` |
| API metadata | | |
| Tokens | 1 | `/token` |
| OpenAPI | 2 | `/openapi.json` |

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)