Password Pusher API v2

Authentication

Authenticate requests with a Bearer token in the Authorization header.

Create an API token in your account settings at /users/token.

Authorization: Bearer YOUR_API_TOKEN

• Public endpoints: GET /api/v2/version, GET /api/v2/pushes/:url_token, GET /api/v2/pushes/:url_token/preview
• Authenticated endpoints: GET /api/v2/pushes/:url_token/audit, GET /api/v2/pushes/active, GET /api/v2/pushes/expired
• Anonymous access setting: When anonymous pushes are disabled, API endpoints require authentication.

Base URL

All endpoints are relative to your installation host:

https://oss.pwpush.com/api/v2

Version Endpoint

GET /api/v2/version

Returns API version, application details, and a features hash describing which capabilities are enabled on this instance.

cURL example:

curl -X GET https://oss.pwpush.com/api/v2/version

{
  "application_version": "2.9.3",
  "api_version": "2.1",
  "edition": "oss",
  "features": {
    "anonymous_access": true,
    "api_token_authentication": true,
    "accounts": {
      "enabled": false
    },
    "pushes": {
      "enabled": true,
      "email_auto_dispatch": false,
      "file_attachments": {
        "enabled": false,
        "requires_authentication": true
      },
      "url_pushes": {
        "enabled": true
      },
      "qr_code_pushes": {
        "enabled": true
      }
    },
    "requests": {
      "enabled": false
    }
  }
}

POST /api/v2/pushes

Create a new push.

Body format: { "push": { ... } }

{
  "push": {
    "payload": "my-secret",
    "expire_after_days": 1,
    "expire_after_views": 5,
    "passphrase": "optional-passphrase",
    "deletable_by_viewer": true,
    "retrieval_step": true,
    "notify_emails_to": "email1@example.com, email2@example.com",
    "notify_emails_to_locale": "fr"
  }
}

cURL example (JSON body):

curl -X POST https://oss.pwpush.com/api/v2/pushes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "push": {
      "payload": "my-secret",
      "expire_after_days": 1,
      "expire_after_views": 5
    }
  }'

GET /api/v2/pushes/:url_token

Retrieve a push payload by token. This counts as a view and may expire the push when limits are reached.

Query parameters: passphrase (optional, required when the push is passphrase-protected)

cURL example:

curl -X GET https://oss.pwpush.com/api/v2/pushes/YOUR_URL_TOKEN

GET /api/v2/pushes/:url_token/preview

Returns the fully-qualified secret URL for a push without retrieving its payload.

cURL example:

curl -X GET https://oss.pwpush.com/api/v2/pushes/YOUR_URL_TOKEN/preview

GET /api/v2/pushes/:url_token/audit

Return audit log entries for a push. Authentication and ownership are required.

Query parameters: page (optional, integer, default 1, valid range 1 to 200)

cURL example:

curl -X GET "https://oss.pwpush.com/api/v2/pushes/YOUR_URL_TOKEN/audit?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DELETE /api/v2/pushes/:url_token

Expire a push immediately. Allowed for owners (when authenticated) or for recipients when the push was created with deletable_by_viewer enabled.

cURL example:

curl -X DELETE https://oss.pwpush.com/api/v2/pushes/YOUR_URL_TOKEN \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /api/v2/pushes/active

List active pushes for the authenticated user.

Query parameters: page (optional, integer, default 1, valid range 1 to 200)

cURL example:

curl -X GET "https://oss.pwpush.com/api/v2/pushes/active?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /api/v2/pushes/expired

List expired pushes for the authenticated user.

Query parameters: page (optional, integer, default 1, valid range 1 to 200)

cURL example:

curl -X GET "https://oss.pwpush.com/api/v2/pushes/expired?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

POST /api/v2/pushes/:url_token/notify_emails

Send an email to notify the push creation to the specified recipients.

Authentication and ownership are required. Only the push owner may send email notifications.

This endpoint is only available when email auto-dispatch is enabled and SMTP is configured. When disabled, the route is not registered and requests return 404 Not Found.

Body format: { "notify_emails_to": "...", "notify_emails_to_locale": "..." }

cURL example:

curl -X POST "https://oss.pwpush.com/api/v2/pushes/YOUR_URL_TOKEN/notify_emails" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notify_emails_to": "email1@example.com, email2@example.com",
    "notify_emails_to_locale": "fr"
  }'

Success response (201):

{
  "message": "Recipient(s) are added to the queue to be sent."
}

Validation error response (422):

Field-level errors are returned as a JSON object keyed by parameter name:

{
  "notify_emails_to": ["are not available"],
  "notify_emails_to_locale": ["is not available"]
}

Supported Locales

The following locales are supported for API requests that accept a locale parameter:

HTTP Status Codes

• 200 - Successful request
• 201 - Push created or email notification queued
• 400 - Invalid request parameters
• 401 - Authentication required or invalid token
• 403 - Forbidden for current user
• 404 - Resource not found (includes unavailable notify_emails route when email auto-dispatch is disabled)
• 422 - Validation error
• 429 - Too many email notification requests (notify_emails endpoint only)