REST API Access to Pepperdata Resources

A REST API is a means of accessing resources by using a browser or a utility like cURL to send HTTP-based requests to a server and receive responses. In this case, Pepperdata provides the server, and the REST API gives you programmatic access to resources that are also available through the Pepperdata dashboard.

For example, if you have a job that runs for a long time, in the job’s launch script or program, you can programmatically create an alarm that fires only for this job. This method is a good alternative when you cannot use the dashboard to directly create an alarm because the job in question is no longer running, and therefore its job Id is no longer valid.

To access a Pepperdata resource using the REST API, construct a URL using a base URL and an endpoint. For example, the URL consists of the base URL and the endpoint /jobdetails.

The base URL is specific to the Pepperdata installation. It is generally of the form REALM/api, where REALM is a URL associated with the realm whose resources you intend to access.

The endpoint providing access to a specific resource is the same for all installations. This guide documents the endpoints.

All returned data is in JSON format unless otherwise specified.


The best way to use the Pepperdata REST API is to adapt or imitate the sample scripts that appear in this guide. For example, this script shows how to create an alarm programmatically.


Accessing the Pepperdata REST API requires including an API key with your requests.

To obtain an API key, go to, and click Create API Key. Follow the instructions there to save your key and to set the environment variables that the sample scripts in this guide rely on.

You can reuse this key until you delete it or it is revoked. Use it in the header with name PDAPI and value (where environment variables are set as above)


For example, with the cURL utility,

curl --tlsv1.2 -H 'Authorization: PDAPI <API-key-id>:<API-key-token>' -X POST -H \

. . .

The /alarms documentation provides examples.


All Pepperdata HTTP communications use HTTPS, so all data is encrypted while in transit and automatically decrypted at its destination. Some installations choose to use an additional layer of encryption, so the text is still encrypted when viewed at the destination. When you use the Pepperdata REST API to access data from such encrypted clusters, the returned job names, user names, and other sensitive strings are encrypted. Encrypted strings start with -.. and end with ._.

The Python decryption script shows how to use your encryption key to decrypt an encrypted string.