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:

  • automatically registering lots of systems that need explicit configuration
  • changing settings on many systems (synchronizing with an existing system metadata source)
  • identifying systems that have stopped sending logs
OperationVerbPathRequired
ListGETsystems.json
ShowGETsystems/<id>.json
RegisterPOSTsystems.jsonsee details
UpdatePUTsystems/<id>.json
RemoveDELETEsystems/<id>.json
Join GroupPOSTsystems/<id>/join.jsongroup_id
Leave GroupPOSTsystems/<id>/leave.jsongroup_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

  • last_event_at may be a timestamp in the zone of the API token owner, or null.
  • The top-level hostname and ip_address keys for the system may be strings or null.

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

  • last_event_at may be a timestamp in the zone of the API token owner, or null.
  • The top-level hostname and ip_address keys for the system may be strings or null.

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

  • system[name]: display name of the system (Required)
  • system[hostname]: hostname to filter by (Required unless the system is a last resort)
  • destination_id or destination_port: ID or number of the destination port the system will log to (see Manage Log Destinations for ID) (Required)
  • system[description]: freeform description
  • system[auto_delete]: whether to automatically remove the system (default: inherit setting from the log destination)

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

  • system[name]: display name of the system (Required)
  • system[ip_address]: source IP address of the system (Required)
  • system[hostname]: filter events to only those from this syslog hostname
  • system[description]: freeform description
  • system[auto_delete]: whether to automatically remove the system (default: false)

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

  • system[name]: display name of the system
  • system[ip_address]: source IP address of the system
  • system[hostname]: source hostname of the system
  • system[description]: freeform description
  • system[auto_delete]: whether to automatically delete the system (default: inherit setting from the log destination)

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

  • group_id: group to join

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

  • group_id: group to leave

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

  • system_wildcard may be a string or null.
  • systems may be an empty array if no systems are in the group.

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

  • system_wildcard may be a string or null.
  • systems may be an empty array if no systems are in the group.

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

  • group[name]: name of the group (Required)
  • group[system_wildcard]: wildcard for system names that belong to the group
  • group[system_ids]: specific system IDs that belong to the group

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

  • group[name]: name of the group
  • group[system_wildcard]: wildcard for system names that belong to the group

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

  • search[name]: descriptive name of the search (Required)
  • search[query]: query to run (Required)
  • search[group_id]: group ID to associate the search with (default: All Systems or first group)

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

  • search[name]: descriptive name of the search (Required)
  • search[query]: query to run (Required)
  • search[group_id]: group ID to associate the search with (default: All Systems or first group)

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

  • filter may be a string (representing the applied filter regex) or null.
  • description may be empty.

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

  • filter may be a string (representing the applied filter regex) or null.
  • description may be empty.

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

  • user[email]: The user’s email address (Required)
  • user[read_only]: Whether the user only has read access to the account (Required)
  • user[manage_members]: Whether the user can manage account membership (default: 0)
  • user[manage_billing]: Whether the user can manage account billing details (default: 0)
  • user[purge_logs]: Whether the user can purge (remove) logs
  • user[can_access_all_groups]: Whether the user has access to all log groups (default: 1)
  • user[group_ids]: Which log groups the user has access to (see Groups to retrieve group IDs)

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

  • user[email]: The user’s email address
  • user[read_only]: Whether the user only has read access to the account
  • user[manage_members]: Whether the user can manage account membership (default: 0)
  • user[manage_billing]: Whether the user can manage account billing details (default: 0)
  • user[purge_logs]: Whether the user can purge (remove) logs
  • user[can_access_all_groups]: Whether the user has access to all log groups
  • user[group_ids]: Which log groups the user has access to (see Groups to retrieve group IDs)

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

  • All values are shown in bytes other than log_data_transfer_used_percent.

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

  • start and end timestamps are in UTC, since archive divisions are based on UTC time.