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.


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, with particular endpoints following that prefix.

Example URL:


Content type


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. Required parameters are marked. Any parameters not marked are not required; if their inclusion affects the behavior, or if there is a default value, that is noted.

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


Authentication failures return 401 Unauthorized.

Failed requests return 400 Bad Request, and a JSON hash is provided containing a single key called message with further information about the issue. For example:

{"message":"Sad panda"}

Methods applied to an endpoint where they are not supported return 405 Method Not Allowed. If the resource is not found, 404 Not Found is returned.

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",

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

Example calls

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

Authenticate with an API token and list all systems:

curl -v -H "X-Papertrail-Token: abc123"

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'

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

curl -v -u "":"s3kr3t" -X PUT --data 'group[name]=Customer+servers'

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

curl -v -u "":"s3kr3t" -X POST --data 'group_id=12'

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).

For some more specific ideas, see the Configuration section, or ask us for details.