Papertrail Knowledge Base

HTTP API

Your apps can make HTTP requests to Papertrail to programmatically search for events and manage groups, saved searches, systems, and log destinations.

To make the documentation easier to navigate, Papertrail's HTTP API is divided into 2 documents based on what you want to accomplish:

The authentication, format, and structure is the same.

Usage

Do I need to use the API?

The HTTP API is entirely optional and not necessary for typical use of Papertrail. Most situations, like searching for logs, programmatically creating senders, and retrieving logs during a certain time period are included as features of papertrail-cli.

Example uses:

Overview

Authentication

All API requests are authenticated using either:

Papertrail supports cross-origin resource sharing (CORS), so it's possible to retrieve log data from another domain.

URL

All Papertrail API requests are rooted at https://papertrailapp.com/api/v1/.

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

Examples

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 search_query.rb source.

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 an API token and search events for Critical error as a quoted phrase:

curl -v -H "X-Papertrail-Token: abc123" "https://papertrailapp.com/api/v1/events/search.json?q='Critical error'"

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.

Format

JSON

Either:

Responses containing multiple items are arrays. Responses about a single item are hashes. No root node is present.

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

See curl examples above or response examples below.

Update requests may contain all attributes or only the attribute(s) which are to be modified. Absent attributes will be left unmodified.

Errors

Failed requests return 400 Bad Request. Authentication failures return 403 Unauthorized.

For failed requests, a JSON hash is returned containing a single key called message. For example:

{"message":"Sad panda"}

Hypermedia

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

As a result, an API consumer will often only need to hardcode one URL.

Hypermedia links are contained 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:

API Endpoints

Within https://papertrailapp.com/api/v1/:

Search Events

ItemOperationVerbPathPath ExampleRequired
EventsSearchGET
events/search
events/search.json



Manage Systems

ItemOperationVerbPathPath ExampleRequired
SystemsListGET
systems
systems.json
SystemShowGET
systems/<id>
systems/42.json
SystemRegisterPOST
systems
systems.json
Varies; see details
SystemUpdatePUT
systems/<id>
systems/42.json
SystemUnregisterDELETE
systems/<id>
systems/42.json
SystemJoin GroupPOST
systems/<id>/join
systems/42/join.json
group_id
SystemLeave GroupPOST
systems/<id>/leave
systems/42/leave.json
group_id



Manage Saved Searches

ItemOperationVerbPathPath ExampleRequired
Saved SearchesListGET
searches
searches.json
Saved SearchShowGET
searches/<id>
searches/42.json
Saved SearchCreatePOST
searches
searches.json
name; query
Saved SearchUpdatePUT
searches/<id>
searches/42.json
Saved SearchDeleteDELETE
searches/<id>
searches/42.json



Manage Groups

ItemOperationVerbPathPath ExampleRequired
GroupsListGET
groups
groups.json
GroupShowGET
groups/<id>
groups/42.json
GroupCreatePOST
groups
groups.json
name
GroupUpdatePUT
groups/<id>
groups/42.json
GroupDeleteDELETE
groups/<id>
groups/42.json



Manage Log Destinations

ItemOperationVerbPathPath ExampleRequired
Log DestinationsListGET
destinations
destionations.json
Log DestinationShowGET
destinations/<id>
destinations/42.json


Manage Users

ItemOperationVerbPathPath ExampleRequired
UsersListGET
users
users.json
UserInvitePOST
users/invite
users/invite.json
email, read_only
UserDeleteDELETE
users/<id>
users/42.json


Retrieve account usage

ItemOperationVerbPathPath ExampleRequired
AccountsListGET
accounts
accounts.json



Examples: Provisioning API

Manage Systems

Papertrail automatically recognizes most systems so that explicit configuration is not needed. See Add Systems. The REST API handles unusual cases like:

In the examples below, whitespace is added for clarity.

List

[ 
  {
    "name":"www5",
    "id":3248,
    "ip_address":"1.2.3.4",
    "hostname":null,
    "last_event_at":null,
    "syslog": {
      "hostname":"logs.papertrailapp.com",
      "port":514
    },
    "_links": { 
      "self": {
        "href":"https://papertrailapp.com/api/v1/systems/www5.json"
      },
      "search": {
        "href":"https://papertrailapp.com/api/v1/events/search.json?system_id=3248"
      },
      "html": {
        "href":"https://papertrailapp.com/systems/www5"
      }
    },
  },

  { 

    # Another system
  }
]

Notes:

Show

See List. Only the hash for the requested system is returned.

Register

Systems can be registered in 2 ways:

Typical system

Note on destinations: Either the destination_id or destination_port must be specified.

Note on identification: Either the system[hostname] must be provided (typical and recommended) or the system will be created as the fallback "last resort" on the destination port provided.

Example:

system[name]=My%20Big%20Server&destination_id=42&hostname=bigserver

Logging to the standard syslog port

When the system's IP address does not change, this is an option.

Example:

system[name]=My%20Big%20Server&system[ip_address]=2.3.4.5&system[hostname]=bigserver

Optional attributes

Optional with both methods:

Update

See Register.

Groups

List

[ 
  { 
    "name":"All Systems",
    "id":31,
    "system_wildcard":"*",
    "systems":[

      # see "Systems - List" for example array
     ],
    "_links": { 
      "self": {
        "href":"https://papertrailapp.com/api/v1/groups/31.json"
      },
      "search": {
        "href":"https://papertrailapp.com/api/v1/events/search.json?group_id=31"
      },
      "html": {
        "href":"https://papertrailapp.com/groups/31" 
      },
    },
  },

  { 

    # Another group
  } 
]

Notes:

Show

See List. Only the hash for the requested group is returned.

Create

group[name]=us-west%20zone&group[system_wildcard]=*west*&group[system_ids][]=31&group[system_ids][]=62

Update

See Create.

Manage Saved Searches

List

[
  {
    "name":"Login rejections",
    "id":1,
    "query":"\"access denied\" OR ssh",
    "group": { 
      "name":"All Systems",
      "id":31,
      "_links": {
        "self": {
          "href":"https://papertrailapp.com/api/v1/groups/31.json"
        }
      }
    },
    "_links": {
      "self": {
        "href":"https://papertrailapp.com/searches/1.json"},
      "search": {
        "href":"https://papertrailapp.com/api/v1/events/search.json?q=%22access+denied%22+OR+ssh"},
      "html": {
        "href":"https://papertrailapp.com/searches/1/edit"
      }
    }
  }
]

Show

See List. Only the hash for the requested search is returned.

Create

Manage Log Destinations

List

[ 
  { 
    "id":31,
    "syslog": {
      "hostname":"<host>.papertrailapp.com",
      "port":11111
    },
  },

  { 

    # Another destination
  } 
]

Show

See List. Only the hash for the requested destination is returned.

Manage Users

List

[
  {
    "email":"sally@example.com",
    "id":1
  }
]

Invite

user[email]=new@example.com&user[read_only]=1

For email addresses which are not already active Papertrail accounts, an email will be sent to the address provided in email with a link to accept the invitation, create an account, and choose a password.

For existing Papertrail users, access will be granted immediately.

Retrieve account usage

List

{
  "log_data_transfer_hard_limit":1111111,
  "log_data_transfer_used":1111111,
  "log_data_transfer_used_percent":1.1111111,
  "log_data_transfer_plan_limit":111111111
}

All values are shown in bytes other than the percentage transferred. All include additional usage, if enabled, other than the plan limit. The percentage used may thus be greater than 100%. Usage represents data transferred since the start of the current billing period.

Search Events

See Search API.