Documentation forPapertrail

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:

Copy 
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

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

Sample response

Copy 
[
  {
    "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

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

Sample response

Copy 
{
  "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
Copy 
$ 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
Copy 
{
  "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
Copy 
$ 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
Copy 
{
  "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
Copy 
$ 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
Copy 
{
  "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

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

Sample response

Copy 
{"message":"System deleted"}

Join group

Adds a system to a group.

POST data items

  • group_id: group to join

Sample request

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

Sample response

Copy 
{"message":"System updated"}

Leave group

Removes a system from a group.

POST data items

  • group_id: group to leave

Sample request

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

Sample response

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

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

Sample response

Copy 
[
  {
    "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

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

Sample response

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

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

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

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

Sample response

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

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

Sample response

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

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

Sample response

Copy 
[
  {
    "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

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

Sample response

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

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

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

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

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

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

Sample response

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

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

Sample response

Copy 
[
  {
    "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

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

Sample response

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

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

Sample response

Copy 
[
  {
    "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

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

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

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

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

Sample response

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

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

Sample response

Copy 
[
  {
    "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.