HTTP API

Papertrail’s HTTP API serves two primary purposes:

Papertrail’s own papertrail-cli exclusively uses API calls documented here. It implements most of the functionality in this document. Install the gem or read its search_query.rb and connection.rb sources.

Papertrail doesn’t accept log messages via HTTP. Why?

API Usage

Example uses

The authentication, format, and request structure is the same for all requests.

Do I need to use the API?

Most common tasks you might want to do outside the UI, like searching for logs, programmatically creating senders or adding them to groups, and retrieving logs during a certain time period, are possible with papertrail-cli, a small command-line tool with simple syntax, so you might be able to skip direct use of the API entirely.

Authentication

All API requests are authenticated using either:

Papertrail’s API supports cross-origin resource sharing (CORS), so it’s possible to retrieve log data from another domain. Because session cookies are not used with the API, you may be prompted to re-authenticate even when already logged in to the Papertrail website.

URL structure

The Papertrail API lives at https://papertrailapp.com/api/v1/, with particular endpoints following that prefix.

Example URL: https://papertrailapp.com/api/v1/systems.json.

Format

Content type

Either:

Responses containing multiple items are arrays. Responses containing a single item are hashes. No extra whitespace is provided; use a processor or pretty-printer to introduce formatting.

Requests and Responses

Request data uses URL-encoded query parameters. Unless otherwise noted, attributes are part of a hash named after the item type, such as:

system[name]=New%20System&system[ip_address]=1.2.3.4

Update requests may contain all attributes or only the attribute(s) to be modified. Absent attributes will not be modified.

Errors

Authentication failures return 401 Unauthorized.

Failed requests return 400 Bad Request, and a JSON hash is provided containing a single key called message. For example:

{"message":"Sad panda"}

Rate Limits

Papertrail limits the number of API requests made within a period of time.

The API returns the three headers that denote the status of the API rate limits:

When the limit is reached, further requests return 429 Rate Limit Exceeded.

The API limits may be adjusted from time to time. If possible, obey the returned header values rather than hardcoding a specific rate, but please let us know if there’s any mismatch.

API responses include URLs for getting details about, or performing actions on, related items. For example, a client can query for all systems, then follow URLs in the response to:

This allows API clients to avoid hardcoding multiple URLs for different calls.

Links to related resources appear in a hash key called _links with a hash per relation. For example:

"name":"Production servers",
"_links":{
  "self":{
    "href":"http://.."
  },
  "html":{
    "href":"http://.."
  }
}

When they apply to the item, these relations are used:

Example calls

These examples use curl, a command-line HTTP client.

Authenticate with an API token and list all systems:

curl -v -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/systems.json

Authenticate with an API token and save a search named Important stuff:

curl -v -H "X-Papertrail-Token: abc123" -X POST --data 'search[name]=Important+stuff&search[query]=very+important' https://papertrailapp.com/api/v1/searches.json

Authenticate with a username and password and update the name of group ID 12 to Customer servers:

curl -v -u "my@email.com":"s3kr3t" -X PUT --data 'group[name]=Customer+servers' https://papertrailapp.com/api/v1/groups/12.json

Authenticate with a username and password and add system ID 4321 to group ID 12:

curl -v -u "my@email.com":"s3kr3t" -X POST --data 'group_id=12' https://papertrailapp.com/api/v1/systems/4321/join.json

As a final example, a customer has implemented a wrapper library for group and search creation called paper_wrap.

Feel free to contact us and request a code sample for your language, or check out Search API and Settings API for more details.

Submitting log messages

Even though we love HTTP for interacting with logs and settings, Papertrail doesn’t accept log messages over HTTP. HTTP is very poorly suited for realtime logging because its characteristics are almost the opposite of what makes an easy, resilient log sender.

Here’s why HTTP doesn’t do your app any favors:

The final and biggest reason: Sending a syslog packet is extremely easy because at its core, a “syslog packet” is just a simple string (think printf). Generating and transmitting it is usually 2-4 lines of code. It’s often less code and easier to follow than generating an HTTP request (and is much shorter and more elegant than HTTP log submission).

If you’re still not sure how to submit a log message without an HTTP API, ask us for details.