This describes Prowl's third-party API. Users can find their API keys on the API keys page.

Changes

Limits

IP addresses are limited to 1000 API calls per hour which begins from the start of the first call. You can create a provider key at the API keys page, which will grant you a larger limit.

If you are writing an application where the provider key will be user-visible in the source or object files, you should only use the provider key for methods that require the provider key, none of which cost API calls.

Methods

SSL is strongly recommended. All commands are sent to: https://api.prowlapp.com/publicapi/method For example, add is: https://api.prowlapp.com/publicapi/add Square brackets next to parameters are maximum lengths in bytes. Parameters are required unless otherwise specified.

You should send all arguments in UTF-8 encoding. Some level of conversion is done if you provide other encoding, but it may not succeed.

add (POST)

Add a notification for a particular user.

You must provide either event or description or both.

Input

apikey [unlimited] API keys separated by commas. Each API key is a 40-byte hexadecimal string.

When using multiple API keys, you will only get a failure response if all API keys are not valid.
providerkey [40]
Optional		 Your provider API key. Only necessary if you have been whitelisted.
priority
Optional		 Default value of 0 if not provided. An integer value ranging [-2, 2] representing:
  1. Very Low
  2. Moderate
  3. Normal
  4. High
  5. Emergency
Emergency priority messages may bypass quiet hours according to the user's settings.
url [512]
Optional		 The URL which should be attached to the notification.

This will trigger a redirect when launched, and is viewable in the notification list.
application [256] The name of your application or the application generating the event.
event [1024] The name of the event or subject of the notification.
description [10000] A description of the event, generally terse.

Success output

No modification from generic format.

verify (GET)

Verify an API key is valid.

For the sake of adding a notification do not call verify first; it costs you an API call. You should only use verify to confirm an API key is valid in situations like a user entering an API key into your program. If it's not valid while posting the notification, you will get the appropriate error.

Input

apikey [40] The user's API key. A 40-byte hexadecimal string.
providerkey [40]
Optional		 Your provider API key. Only necessary if you have been whitelisted.

Success output

No modification from generic format.

retrieve/token (GET) [no call cost]

Get a registration token for use in retrieve/apikey and the associated URL for the user to approve the request.

This is the first step in fetching an API key for a user. The token retrieved expires after 24 hours.

Input

providerkey [40] Your provider API key. Required.

Success output

<?xml version="1.0" encoding="UTF-8"?>
<prowl>
	<success code="200" remaining="REMAINING" resetdate="TIMESTAMP"
		/>
	<retrieve token="TOKEN" url="URL" />
</prowl>

Fields in the response are as follows:

When the user completes the retrieve operation, they will be presented a link back to your application if you set one. The query string "token" will be set in the return URL with the TOKEN above.

retrieve/apikey (GET) [no call cost]

Get an API key from a registration token retrieved in retrieve/token. The user must have approved your request first, or you will get an error response.

This is the second/final step in fetching an API key for a user.

Input

providerkey [40] Your provider API key. Required.
token [40] The token returned from retrieve/token. Required.

Success output

<?xml version="1.0" encoding="UTF-8"?>
<prowl>
	<success code="200" remaining="REMAINING" resetdate="TIMESTAMP"
		/>
	<retrieve apikey="APIKEY" />
</prowl>

Fields in the response are as follows:

At any point, the user can delete the API key. Be prepared to prompt the user to retrieve a new API key if they do.

If the user already had an API key requested using your provider key, you will get the same API key back if it still exists.

Generic return format

You should always use an XML parser. While the structure itself won't change, the format or attributes might in a way that breaks direct string parsing.

Errors

An error will return the following format, as well as an HTTP status code equal to ERRORCODE.

<?xml version="1.0" encoding="UTF-8"?>
<prowl>
	<error code="ERRORCODE">ERRORMESSAGE</error>
</prowl>
ERRORCODE can be one of the following:

Success

A success will return the following format, as well as the HTTP status code 200. Some methods add additional output, which will be detailed in their example response. This is the generic success information. 

<?xml version="1.0" encoding="UTF-8"?>
<prowl>
	<success code="200" remaining="REMAINING" resetdate="TIMESTAMP"
		/>
</prowl>

Fields in the response are as follows:

Libraries

There are different libraries and scripts available which use the API in an array of languages.

Privacy Policy