API Overview

Airbrake provides easy access to all your data via an XML-based, RESTful API.

There are also a number of Alternative Plugins, Widgets, and Extras that Airbrake users have built. We also have a tutorial using Python as an example.

There is one prerequisite to using the API: you must have an auth_token. When logged in, you can find your auth_token near the bottom of the My Settings tab after clicking the Settings button.

If you are looking to send notifications to Airbrake (perhaps for your own custom notifier), instead of reading data, you'll want to read up on the Notifier API.

A note about SSL

If your plan supports SSL, you must access the API over an HTTPS connection. Standard HTTP requests to the API for these accounts will return an "HTTP 403 Forbidden" status.

Accessing the API using Ruby

If you are using Ruby, then you can use ActiveResource to write a client to easily connect to the API. Here is what it'd look like:

# code at http://gist.github.com/3350
# tests at http://gist.github.com/3354

class Airbrake < ActiveResource::Base
  self.site = "http://your_account.airbrake.io"

  class << self
    @@auth_token = 'your_auth_token'

    def find(*arguments)
      arguments = append_auth_token_to_params(*arguments)
      super(*arguments)
    end

    def append_auth_token_to_params(*arguments)
      opts = arguments.last.is_a?(Hash) ? arguments.pop : {}
      opts = opts.has_key?(:params) ? opts : opts.merge(:params => {}) 
      opts[:params] = opts[:params].merge(:auth_token => @@auth_token)
      arguments << opts
      arguments
    end
  end
end

class Error < Airbrake  
end

# Errors are paginated. You get 30 at a time.

@errors = Error.find :all
@errors = Error.find :all, :params => { :page => 2 }

Accessing the API Directly

The API is a normal Rails REST service, and while Ruby is our preferred language, you can use any language you want to query the API.

When getting multiple errors at once, the environment, backtrace, session, and request information will not be returned along with the errors. To view this additional information request the xml for the individual error:

http://your_account.airbrake.io/errors/1000.xml

Here is the XML for a typical error

<?xml version="1.0" encoding="UTF-8"?>
<group>
  <action>create</action>
  <controller>session</controller>
  <created-at type="datetime">2008-07-09T20:06:44-07:00</created-at>
  <error-class>NoMethodError</error-class>
  <error-message>NoMethodError: undefined method `password' for nil:NilClass</error-message>

  <file>[RAILS_ROOT]/app/models/user.rb</file>
  <id type="integer">5529</id>
  <last-notice-at type="datetime">2008-07-31T04:21:52-07:00</last-notice-at>
  <last-notice-id type="integer">203799</last-notice-id>
  <line-number type="integer">186</line-number>
  <notices-count type="integer">30</notices-count>

  <project-id type="integer">2</project-id>
  <rails-env>production</rails-env>
  <updated-at type="datetime">2008-07-31T04:21:52-07:00</updated-at>
  <visible type="boolean">true</visible>
</group>

To access a paginated list of notices for this error, request the notices index nested under the error:

http://your_account.airbrake.io/groups/1000/notices.xml?page=1

To get detailed information on a specific notice:

http://your_account.airbrake.io/groups/1000/notices/3456789.xml

To get a list of your projects:

http://your_account.airbrake.io/data_api/v1/projects.xml

To get a list of your deploys (for a project):

http://your_account.airbrake.io/projects/55/deploys.xml

Note: If your account supports SSL, make sure to use https instead of http

Submitting Errors to Airbrake

In order to submit errors to Airbrake, you can either use the airbrake plugin for Rails, or access the API directly. For information about the notifier, API, see http://help.airbrake.io/faqs/api-2/notifier-api-v2.