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.

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

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

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) 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)

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

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 and end 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.