Settings API

While it’s easy to make occasional settings changes in the account settings, when working with a larger number of systems, using papertrail-cli or the API may be easier.

This document covers system and group settings and account information; for event search, see Search API.

API Endpoints

The settings API endpoints are part of Papertrail’s HTTP API. All API calls use the same authentication and request/response format.

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

Manage systems

OperationVerbPathPath ExampleRequired
ListGETsystemssystems.json
ShowGETsystems/<id>systems/42.json
RegisterPOSTsystemssystems.jsonsee details
UpdatePUTsystems/<id>systems/42.json
UnregisterDELETEsystems/<id>systems/42.json
Join GroupPOSTsystems/<id>/joinsystems/42/join.json group_id
Leave GroupPOSTsystems/<id>/leavesystems/42/leave.json group_id

Manage saved searches

OperationVerbPathPath ExampleRequired
ListGETsearchessearches.json
ShowGETsearches/<id>searches/42.json
CreatePOSTsearchessearches.jsonname; query
UpdatePUTsearches/<id>searches/42.json
DeleteDELETEsearches/<id>searches/42.json

Manage groups

OperationVerbPathPath ExampleRequired
ListGETgroupsgroups.json
ShowGETgroups/<id>groups/42.json
CreatePOSTgroupsgroups.jsonname
UpdatePUTgroups/<id>groups/42.json
DeleteDELETEgroups/<id>groups/42.json

Log destinations

OperationVerbPathPath Example
ListGETdestinationsdestinations.json
ShowGETdestinations/<id>destinations/42.json

Creating and updating log destinations by API is not currently supported, since most accounts only need a small number of log destinations and the total number per account is limited.

Manage users

OperationVerbPathPath ExampleRequired
ListGETusersusers.json
InvitePOSTusers/inviteusers/invite.jsonemail, read_only
DeleteDELETEusers/<id>users/42.json

Account usage

OperationVerbPathPath Example
ListGETaccountsaccounts.json

Archive details

OperationVerbPathPath Example
ListGETarchivesarchives.json

Endpoint Details

Manage Systems

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

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

Like List, but only the hash for the requested system is returned.

Register

Systems can be registered in two ways:

Using a regular log destination

Destinations: Either the destination_id or destination_port must be specified.

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

Using port 514

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
  }
]

Show

Like List, but 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.

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"
      }
    }
  },
  {
	  # another search
  }
]

Show

Like List, but only the hash for the requested search is returned.

Create

Log Destinations

List

[
  {
    "id":31,
    "syslog": {
      "hostname":"logs.papertrailapp.com",
      "port":514,
      "description":"user-provided description"
    },
  },
  {
    # Another destination
  }
]

Show

Like List, but only the hash for the requested destination is returned.

Manage Users

List

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

Invite

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

For email values that don’t already have associated Papertrail accounts, an email will be sent to the address provided 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
}

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

Retrieve archive information

List

Retrieve an array of available archive downloads, one per file. start and end timestamps are in UTC, since archive divisions are based on UTC time.

[
  {
    "start":"2014-11-30T00:00:00Z",
    "end":"2014-11-30T23:59:59Z",
    "filename":"2014-11-30.tsv.gz",
    "filesize":26140153,
    "_links": {
      "download": {
        "href":"https://papertrailapp.com/api/v1/archives/2012-11-30/download"
      }
    }
  }
]