Prowl
Prowl
Log in Create account
Privacy
On this page
API version
OpenAPI spec: yaml ↓ / json ↓
base · api.prowl.app

API

You can explore the methods below, or grab the OpenAPI spec in the sidebar to generate a client or instruct an LLM on constructing requests.

API limits

Per IP address
1,000 / hour
Rolling window
With a provider key
Higher cap
Issued below
POST
/2/add

Add and send a notification

Sends a notification to one or more API keys.

Headers
idempotency-key
string

Printable ASCII only. Generate a random value, reuse it on retries to prevent duplicate notifications.

Request body

application/json
priority
string

Defaults to normal

  • very_low
  • moderate
  • normal
  • high
  • emergency
description
string

Up to 10000 bytes.

application Required
string

Up to 256 bytes. Used as a grouping key in the UI.

url
string (uri)

A URL field (e.g. https://...)

event Required
string

Headline for a notification, up to 1024 bytes.

providerkey
string

Your provider key, if you are using one.

apikeys Required
array of ApiKey

One or more 40 character hex API keys.

Responses

200
Notification added application/json
notifications
array of AddResult Required

One entry per input apikey, in request order.

items
error
string

Only present if status is error.

  • invalid_api_key
  • server_error
status
string Required

Whether delivery to the key was successful.

  • sent
  • error
apikey
string Required

The key provided in the request.

400
Validation failed application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

401
Authentication failed application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

415
Invalid content-type application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

429
Throttled application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

500
Server error application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

Try It

Parameters
Headers
⁨Body⁩ · ⁨application/json⁩
Request preview 
POST /2/add
content-type: application/json

{
  "apikeys": [
    "abcdef0123456789abcdef0123456789abcdef01"
  ],
  "application": "deploy.sh",
  "description": "web @ a17f2c · 38s · green",
  "event": "shipped",
  "priority": "high",
  "url": "https://github.com/zacwest/prowl/pull/42"
}
Response
Waiting for response
POST
/2/retrieve/apikey

Exchange a retrieve token for an API key

Call this after the user approves the retrieve request.

Request body

application/json
token Required
string

The token created from the previous request.

providerkey Required
string

Your provider key, if you are using one.

Responses

200
API key created application/json
apikey
string Required

The key provided in the request.

400
Validation failed or not approved application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

401
Unknown providerkey application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

429
Throttled application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

500
Server error application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

Try It

Parameters
⁨Body⁩ · ⁨application/json⁩
Request preview 
POST /2/retrieve/apikey
content-type: application/json

{
  "token": "0123456789abcdef0123456789abcdef01234567"
}
Response
Waiting for response
POST
/2/retrieve/token

Mint a token to retrieve an API key

Create a token and get the callback URL, then send the user to the URL to approve.

Request body

application/json
providerkey Required
string

Your provider key, if you are using one.

Responses

200
Token created application/json
token
string Required

The token to use for the next step.

approval_url
string (uri) Required

A URL field (e.g. https://...)

400
Validation failed application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

401
Unknown providerkey application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

429
Throttled application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

500
Server error application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

Try It

Parameters
⁨Body⁩ · ⁨application/json⁩
Request preview 
POST /2/retrieve/token
content-type: application/json

{}
Response
Waiting for response
POST
/2/verify

Verify an API key

Verify whether an API key is valid. Use this when the user is inputting it, you don't need to issue it before adding a notification.

Request body

application/json
apikey Required
string

The key provided in the request.

providerkey
string

Your provider key, if you are using one.

Responses

200
Valid key application/json
valid
boolean Required

Whether the key was valid.

400
Validation failed application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

401
Invalid key application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

429
Throttled application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

500
Server error application/json
code
string Required

The reason for the failure.

  • access_denied
  • authorization_pending
  • destination_limit_reached
  • expired_token
  • interactive_login_required
  • invalid_api_key
  • invalid_credentials
  • invalid_grant
  • invalid_idempotency_key
  • invalid_parameters
  • invalid_provider_key
  • invalid_token
  • not_found
  • pause_not_clearable
  • server_error
  • throttled
  • unsupported_media_type
status
integer Required

The HTTP status code.

instance
string Required

Request path which caused the error.

title
string Required

Human-readable representation of the code.

detail
string Required

Human-readable explanation of the error.

invalid_params
array of InvalidParam

Per-field validation when code is invalid_parameters.

items
name
string Required

Dotted field name (e.g. apikeys.7).

reason
string Required

Human-readable reason for the field error.

pointer
string Required

RFC 6901 JSON Pointer (e.g. '/apikeys/7').

Try It

Parameters
⁨Body⁩ · ⁨application/json⁩
Request preview 
POST /2/verify
content-type: application/json

{
  "apikey": "abcdef0123456789abcdef0123456789abcdef01"
}
Response
Waiting for response

Provider keys

Mint API keys for a user

Use a provider key to send users through the retrieve flow to get an API key to send them notifications.

Log in to view and manage your provider keys.

Log in