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.

The settings API endpoints are part of Papertrail’s HTTP API. All API calls use the same authentication and request/response format. This document covers system and group settings and account information; for event search, see Search API.

API Endpoints

In the charts below, the paths listed for each endpoint are relative to the API root:

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

Manage Systems

Papertrail automatically recognizes most systems so that explicit configuration is not needed. See Add Systems for standard system setup.

The REST API handles unusual cases like:

OperationVerbPathRequired
ListGETsystems.json
ShowGETsystems/<id>.json
RegisterPOSTsystems.jsonsee details
UpdatePUTsystems/<id>.json
RemoveDELETEsystems/<id>.json
Join GroupPOSTsystems/<id>/join.json group_id
Leave GroupPOSTsystems/<id>/leave.json group_id

List systems

Returns information for all systems.

Sample request

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

Sample response

[
  {
    "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
  }
]

Data types

Show system

Returns information for a single system.

Sample request

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

Sample response

{
  "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"
    }
  }
}

Data types

Register system

Creates a system.

Account-specific log destination

Creates a system that logs to a log destination assigned to the account.

POST data items

A “last resort” system is a system that events will be assigned to if they don’t come from any recognized hostname assigned to that destination.

Sample request

  curl -v -X POST -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/systems.json \
  -d 'system[name]=ProdWebServer&system[hostname]=wwwprod&destination_id=9291'

Sample response

{
  "id": 8694,
  "name": "ProdWebServer",
  "last_event_at": null,
  "auto_delete": true,
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/systems/ProdWebServer.json"
    },
    "html": {
      "href": "https://papertrailapp.com/systems/ProdWebServer"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?system_id=8694"
    }
  },
  "ip_address": null,
  "hostname": "wwwprod",
  "syslog": {
    "hostname": "logsN.papertrailapp.com",
    "port": XXXXX
  }
}

Standard syslog port

Creates a system that logs to the standard syslog port logs.papertrailapp.com:514. Intended for systems that can’t send to a custom port. The system should have a static public IP.

POST data items

If hostname is set, events that come from the same IP, but with a different hostname, will be dropped.

Sample request

    curl -v -X POST -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/systems.json \
    -d 'system[name]=ProdWebServer&system[ip_address]=72.175.32.101'

Sample response

{
  "id": 8684,
  "name": "ProdWebServer",
  "last_event_at": null,
  "auto_delete": false,
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/systems/ProdWebServer.json"
    },
    "html": {
      "href": "https://papertrailapp.com/systems/ProdWebServer"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?system_id=8684"
    }
  },
  "ip_address": "72.175.32.101",
  "hostname": null,
  "syslog": {
    "hostname": "logs.papertrailapp.com",
    "port": 514
  }
}

Update system

Changes information for a system. It does not allow changing a system’s log destination after creation.

PUT data items

Sample request

  curl -v -X PUT -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/systems/8684.json \
  -d 'system[name]=ProdWebServer1&system[description]=Production%20Webserver'

Sample response

{
  "id": 8684,
  "name": "ProdWebServer1",
  "last_event_at": null,
  "auto_delete": true,
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/systems/ProdWebServer1.json"
    },
    "html": {
      "href": "https://papertrailapp.com/systems/ProdWebServer1"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?system_id=8684"
    }
  },
  "ip_address": null,
  "hostname": "wwwprod",
  "syslog": {
    "hostname": "logsN.papertrailapp.com",
    "port": XXXXX
  }
}

Remove system

Deletes a system.

Sample request

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

Sample response

{"message":"System deleted"}

Join group

Adds a system to a group.

POST data items

Sample request

  curl -v -X POST -H "X-Papertrail-Token: abc123" 'https://papertrailapp.com/api/v1/systems/8596/join.json' \
  -d 'group_id=5207'

Sample response

{"message":"System updated"}

Leave group

Removes a system from a group.

POST data items

Sample request

  curl -v -X POST -H "X-Papertrail-Token: abc123" 'https://papertrailapp.com/api/v1/systems/8596/leave.json' \
  -d 'group_id=5207'

Sample response

{"message":"System updated"}

Groups

OperationVerbPathRequired
ListGETgroups.json
ShowGETgroups/<id>.json
CreatePOSTgroups.jsonname
UpdatePUTgroups/<id>.json
DeleteDELETEgroups/<id>.json

List groups

Lists all groups, including the systems they contain.

Sample request

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

Sample response

[
  {
    "name":"All Systems",
    "id":31,
    "system_wildcard":"*",
    "systems":[
      "array of all systems in the group;
      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
  }
]

Data types

All systems (whether static members or matching via wildcard) will be included in the systems array.

Show group

Returns information for the requested group.

Sample request

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

Sample response

{
  "id": 31,
  "name": "All Systems",
  "system_wildcard": "*",
  "systems": [
    "array of all systems in the group;
    see Systems - List for example array"
  ],
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/groups/31.json"
    },
    "html": {
      "href": "https://papertrailapp.com/groups/31"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?group_id=31"
    }
  }
}

Data types

All systems (whether static members or matching via wildcard) will be included in the systems array.

Create group

Creates a new group.

POST data items

Sample request

  curl -v -X POST -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/groups.json \
  -d 'group[name]=ProdWebServers&group[system_wildcard]=*prod*&group[system_ids][]=31&group[system_ids][]=62'

Sample response

{
  "id": 5207,
  "name": "ProdWebServers",
  "system_wildcard": "*prod*",
  "systems": [
    "array of all systems in the group;
    see Systems - List for example array"
  ],
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/groups/5207.json"
    },
    "html": {
      "href": "https://papertrailapp.com/groups/5207"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?group_id=5207"
    }
  }
}

Update group

Changes the details of a group. Cannot be used to add or remove systems from a group; use Join Group and Leave Group instead.

PUT data items

Sample request

  curl -v -X PUT -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/groups/5207.json \
  -d 'group[name]=ProductionWebServers

Sample response

{
  "id": 5207,
  "name": "ProductionWebServers",
  "system_wildcard": "*prod*",
  "systems": [
    "array of all systems in the group;
    see Systems - List for example array"
  ],
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/groups/5207.json"
    },
    "html": {
      "href": "https://papertrailapp.com/groups/5207"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?group_id=5207"
    }
  }
}

Delete group

Sample request

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

Sample response

{"message":"Group deleted"}

Saved searches

OperationVerbPathRequired
ListGETsearches.json
ShowGETsearches/<id>.json
CreatePOSTsearches.jsonname, query
UpdatePUTsearches/<id>.json
DeleteDELETEsearches/<id>.json

List searches

Returns all saved searches.

Sample request

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

Sample response

[
  {
    "name":"Login rejections",
    "id":1111,
    "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/1111.json"},
      "search": {
        "href":"https://papertrailapp.com/api/v1/events/search.json?q=%22access+denied%22+OR+ssh"},
      "html": {
        "href":"https://papertrailapp.com/searches/1111/edit"
      }
    }
  },
  {
    # another search
  }
]

Returns information for the requested search.

Sample request

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

Sample response

{
  "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/1111.json"},
    "search": {
      "href":"https://papertrailapp.com/api/v1/events/search.json?q=%22access+denied%22+OR+ssh"},
    "html": {
      "href":"https://papertrailapp.com/searches/1111/edit"
    }
  }
}

POST data items

Sample request

  curl -v -X POST -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/searches.json \
  -d 'search[name]=Test%20search&search[query]=test'

Sample response

{
  "id": 2055,
  "name": "Test search",
  "query": "test",
  "group": {
    "id": 31,
    "name": "All Systems",
    "_links": {
      "self": {
        "href": "https://papertrailapp.com/api/v1/groups/31.json"
      }
    }
  },
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/searches/2055.json"
    },
    "html": {
      "href": "https://papertrailapp.com/searches/2055/edit"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?q=test"
    },
    "html_search": {
      "href": "https://papertrailapp.com/searches/2055"
    }
  }
}

PUT data items

Sample request

  curl -v -X PUT -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/searches/2055.json \
  -d 'search[name]=Test%20search&search[query]=test%20test&search[group_id]=5207'

Sample response

{
  "id": 2055,
  "name": "Test search",
  "query": "test test",
  "group": {
    "id": 5207,
    "name": "ProdWebServers",
    "_links": {
      "self": {
        "href": "https://papertrailapp.com/api/v1/groups/5207.json"
      }
    }
  },
  "_links": {
    "self": {
      "href": "https://papertrailapp.com/api/v1/searches/2055.json"
    },
    "html": {
      "href": "https://papertrailapp.com/searches/2055/edit"
    },
    "search": {
      "href": "https://papertrailapp.com/api/v1/events/search.json?q=test+test"
    },
    "html_search": {
      "href": "https://papertrailapp.com/searches/2055"
    }
  }
}

Sample request

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

Sample response

{"message":"Search deleted"}

Log destinations

OperationVerbPath
ListGETdestinations.json
ShowGETdestinations/<id>.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.

List destinations

Returns information for all log destinations.

Sample request

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

Sample response

[
  {
    "id":31,
    "filter": null
    "syslog": {
      "hostname": "logsN.papertrailapp.com",
      "port": XXXXX,
      "description": "user-provided description"
    }
  },
  {
    # Another destination
  }
]

Data types

Show destination

Returns information for the requested destination.

Sample request

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

Sample response

{
  "id":31,
  "filter": null
  "syslog": {
    "hostname": "logsN.papertrailapp.com",
    "port": XXXXX,
    "description": "user-provided description"
  }
}

Data types

Manage users

OperationVerbPathRequired
ListGETusers.json
InvitePOSTusers/invite.jsonemail, read_only
UpdatePUTusers/<id>.json
DeleteDELETEusers/<id>.json

List users

Sample request

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

Sample response

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

Invite user

Invite a user by email.

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 email values with existing Papertrail user accounts, access will be granted immediately.

POST data items

If manage_members or manage_billing is set to 1, the read_only setting will be ignored and the request will grant them write access to the account, and the ability to manage other members and/or account billing. If purge_logs is set to 1, the request will grant the user access to purge log events unless read_only or can_access_all_groups is set to 0, in which case they will not receive permission to purge, and will be read_only.

To limit group access to a subset of groups, pass user[can_access_all_groups]=0 and provide group IDs, as shown in the sample. If the user can access all groups, group IDs will have no effect.

Sample request

curl -v -X POST -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/users/invite.json \
-d 'user[email]=sarah@example.com&user[read_only]=1&user[can_access_all_groups]=0&user[group_ids][]=77&user[group_ids][]=78'

Sample response

If the invitation is successful, the request returns 200 OK with no content.

Update user

Modify email address or permissions for an existing user. Recommended use: submit the complete set of desired permissions.

PUT data items

If manage_members or manage_billing is set to 1, the read_only setting will be ignored and the request will grant them write access to the account, and the ability to manage other members and/or account billing. If purge_logs is set to 1, the request will grant the user access to purge log events unless read_only or can_access_all_groups is set to 0, in which case they will not receive permission to purge, and will be read_only. If manage_billing or purge_logs is passed in an update without passing additional account management permissions, the user will no longer have other permissions after the update (their default is 0 if not included). If read_only is passed without other permissions, the user will only have read access to the account, without any management permissions.

To limit group access to a subset of groups, pass user[can_access_all_groups]=0 and provide group IDs, as shown in the sample. If the user can access all groups, group IDs will have no effect. Users with access only to a specific set of groups cannot purge logs, even if user[purge_logs] is set to 1. Users cannot be configured to have access to no groups through the API.

Sample request

curl -v -X PUT -H "X-Papertrail-Token: abc123" https://papertrailapp.com/api/v1/users/5198.json \
-d 'user[email]=sarah@example.com&user[read_only]=0&user[can_access_all_groups]=1&user[manage_members]=1'

Sample response

If the update is successful, the request returns 200 OK with no content.

Delete user

Sample request

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

Sample response

If the deletion is successful, the request returns 200 OK with no content.

Retrieve account usage

OperationVerbPath
ListGETaccounts.json

List usage

Sample request

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

Sample response

{
  "log_data_transfer_used":15878175,
  "log_data_transfer_used_percent":15.142607688903809,
  "log_data_transfer_plan_limit":104857600,
  "log_data_transfer_hard_limit":104857600
}

Data types

Usage represents data transferred since the start of the current billing period. 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

OperationVerbPath
ListGETarchives.json

List archives

Retrieve an array of available archive downloads, one per file.

Sample request

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

Sample response

[
  {
    "start": "2016-12-27T00:00:00Z",
    "end": "2016-12-27T23:59:59Z",
    "start_formatted": "Tuesday, December 27 UTC",
    "duration_formatted": "1 day",
    "filename": "2016-12-27.tsv.gz",
    "filesize": 374725,
    "_links": {
      "download": {
        "href": "https://papertrailapp.com/api/v1/archives/2016-12-27/download"
      }
    }
  },
  {
    # another archive
  }
]

Data types