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
Operation | Verb | Path | Required |
---|---|---|---|
List | GET | systems.json
|
|
Show | GET | systems/<id>.json
|
|
Register | POST | systems.json
|
see details |
Update | PUT | systems/<id>.json
|
|
Remove | DELETE | systems/<id>.json
|
|
Join Group | POST | systems/<id>/join.json
|
group_id
|
Leave Group | POST | systems/<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
last_event_at
may be a timestamp in the zone of the API token owner, or null.- The top-level
hostname
andip_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
andip_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
ordestination_port
: ID or number of the destination port the system will log to (see Manage Log Destinations for ID) (Required)system[description]
: freeform descriptionsystem[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 hostnamesystem[description]
: freeform descriptionsystem[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 systemsystem[ip_address]
: source IP address of the systemsystem[hostname]
: source hostname of the systemsystem[description]
: freeform descriptionsystem[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
Operation | Verb | Path | Required |
---|---|---|---|
List | GET | groups.json
|
|
Show | GET | groups/<id>.json
|
|
Create | POST | groups.json
|
name
|
Update | PUT | groups/<id>.json
|
|
Delete | DELETE | groups/<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 groupgroup[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 groupgroup[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
Operation | Verb | Path | Required |
---|---|---|---|
List | GET | searches.json
|
|
Show | GET | searches/<id>.json
|
|
Create | POST | searches.json
|
name, query
|
Update | PUT | searches/<id>.json
|
|
Delete | DELETE | searches/<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
}
]
Show 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"
}
}
}
Create search
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"
}
}
}
Update search
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"
}
}
}
Delete search
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
Operation | Verb | Path |
---|---|---|
List | GET | destinations.json
|
Show | GET | destinations/<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
Operation | Verb | Path | Required |
---|---|---|---|
List | GET | users.json
|
|
Invite | POST | users/invite.json
|
email, read_only
|
Update | PUT | users/<id>.json
|
|
Delete | DELETE | users/<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) logsuser[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 addressuser[read_only]
: Whether the user only has read access to the accountuser[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) logsuser[can_access_all_groups]
: Whether the user has access to all log groupsuser[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
Operation | Verb | Path |
---|---|---|
List | GET | accounts.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
Operation | Verb | Path |
---|---|---|
List | GET | archives.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
andend
timestamps are in UTC, since archive divisions are based on UTC time.
The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.