Getting Started

Our API can be used to access the data stored in your Honeybadger account and to make changes to your account data. To learn about reporting exception data, deployments, and other events, check out the API documentation.

Glossary

The resource names used by the API may be different from those used in our web UI. Here is a glossary of the most important resource names:

Project: A container that holds all your data for a single app or service.
Fault: Called an "error" in the web UI. It has many Notices.
Notice: Called an "error occurrence" in the web UI.
Site: Called an "uptime check" in the web UI.
CheckIn: Manages dead-man-switch checks.
Team: Connects Honeybadger users to projects.
TeamInvitation: Invites a user to join a team.

Authentication

Authentication to the API is performed via HTTP Basic Auth. Each request should be sent with your personal authentication token (available from your profile page) as the basic auth username value. You do not need to provide a password.

For example, you can request your projects list with curl like so (the trailing colon after the token prevents curl from asking for a password):

bash

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects

Rate Limiting

You can make up to 360 requests per hour to our API. After you reach the limit for the hour, additional requests will receive a response with the 403 (Forbidden) status code. The following headers, returned with every API response, can provide you the information about your rate limit:

Header	Description
`X-RateLimit-Limit`	The number of requests that you can make per hour
`X-RateLimit-Remaining`	The number of requests you can make before getting an error
`X-RateLimit-Reset`	A Unix timestamp (number of seconds since the epoch) when remaining requests counter will be reset to the maximum

Format

The API returns JSON by default, but you should include Accept: application/json in your request headers. Lists of items are always paginated, even if there is only one page of results. The general response format for a list is as follows:

json

  

{
  "links": {
    "self": "https://app.honeybadger.io/v2/...",
    "next": "https://app.honeybadger.io/v2/..."
  }
  "results": [
    { ... },
    { ... }
  ]
}

You can get the page after the current page by loading the value found in the next element of the links hash and the page before the current page by loading the value found in the prev element of the links hash. Either or both of those elements may be missing from the links hash if we can determine there is no next page or previous page of results. On the other hand, there may be a next link that, when loaded, results in no records being found -- in which case, the results top-level element will be an empty array.

Requests and Responses

When you create or update resources, send the request (via POST for creations or PUT for updates) with the Content-type header as application/json, the Accept header as application/json and the request body as a valid json object. No request body is required for deleting a resource via the DELETE method.

A successful POST request will return a 201 status code and the JSON representation of the just-created resource as the response body.

A PUT request that successfully updates an object will return a 204 status code with no response body.

Responses for successful DELETE requests return a status code of 204 and an empty response body.

Requests that result in errors will return a JSON response body like so:

json

{ "errors": "Reason for error" }

The status code will be 403 if there is a permissions problem, 422 if the request was invalid, or in the 500 range if something unexpected happened.