Publish API

Exceptional Publish API

The Exceptional Publish API accepts error information which is then processed and made available on Currently, client implementations exist for:

This document will help anyone wishing to develop an exceptional client for other platforms.

JSON Document

The core of the API is a suitably structured JSON document. This document is processed by the Exceptional publish API.
{ "request": { "session": { "session_variable_1": "Session 1 Variable Value", "session_variable_2": "Session 2 Variable Value" }, "remote_ip": "", "parameters": { "action": "gonuts", "controller": "spike" }, "action": "gonuts", "url": "http://localhost/spike/gonuts", "request_method": "get", "controller": "SpikeController", "headers": { "Version": "HTTP/1.1", "User-Agent": "Mozilla/5.0", "Accept-Encoding": "gzip,deflate", "Keep-Alive": "300", "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.7", "Accept-Language": "en-us,en;q=0.5", "Connection": "keep-alive", "Host": "" } }, "application_environment": { "framework": "rails", "env": { "MANPATH": "/usr/local/git/man:/opt/local/share/man", "SHELL": "/bin/bash", "DISPLAY": "/tmp/launch-SYxDj8/:0", "CVSEDITOR": "mate -w", "LANG": "en_IE.UTF-8", "PWD": "/var/www/myapp", "PATH": "/opt/local/bin:/usr/local/git/bin:/opt/local/bin" }, "language": "ruby", "language_version": "1.8.7 p72 2008-08-11 i686-darwin9", "application_root_directory": "/var/www/myapp" }, "exception": { "occurred_at": "2010-10-29T10:48:54+01:00", "message": "NoMethodError: undefined method horse!' for nil:NilClass", "backtrace": [ "/Users/wal/work/myapp/app/controllers/spike_controller.rb:16:ingonuts'", "/actionpack-2.3.2/lib/action_controller/base.rb:1322:in send'", "/actionpack-2.3.2/lib/action_controller/base.rb:1322:inperform_action_without_filters'", "/actionpack-2.3.2/lib/action_controller/filters.rb:617:in call_filters'", "/actionpack-2.3.2/lib/action_controller/filters.rb:610:inperform_action_without_benchmark'", "/actionpack-2.3.2/lib/action_controller/benchmarking.rb:68:in perform_action_without_rescue'", "/activesupport-2.3.2/lib/active_support/core_ext/benchmark.rb:17:inms'", "/ruby/1.8/benchmark.rb:308:in realtime'", "/ruby/gems/1.8/gems/activesupport-2.3.2/lib/active_support/core_ext/benchmark.rb:17:inms'"], "exception_class": "RuntimeError" }, "client": { "name": "getexceptional-rails-plugin", "version": "0.2.0", "protocol_version": 6 } }

Mandatory Fields

The more information from above that can be provided, the more exceptional features that will be available, but at a minimum the following 6 properties are required for processing:


A JSON Array of strings representing the backtrace where the error occurred


This string represents the name of the class within which the error occurred


The error details string for the error


The time the error occurred at in ISO 8601 format (e.g '2010-10-29T10:48:54+01:00')


The local(client) filesystem location of the project


A hash containing key value pairs about the applications environment (this can be empty)


Once the document above is prepared, it must be compressed using gzip (for protocol version 6) or ZLib compression (for protocol version 5). Protocols 5 and 6 are identical except for the compression format.

POST'ing to

Once compressed, the document needs to be posted to the exceptional api. You will need your API_KEY to post this:


Thats all you should need to pass your own error data to exceptional!