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:
Authorization: Bearer YOUR_API_TOKENThe 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 for the
kinds of token and how to create one.
Requests
Request bodies are JSON with the resource’s fields at the top level:
{"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:
{ "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:
{ "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 hourX-RateLimit-Remaining: requests left in the current hourX-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:
{"project": {"name": "Billing API"}}becomes
{"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
20Every operation in this reference is generated from the API’s OpenAPI spec, which you can download as YAML or 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 |