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://pwpush.involas.cloud/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://pwpush.involas.cloud/api/v2/version

{
  "application_version": "2.9.0",
  "api_version": "2.1",
  "edition": "oss",
  "features": {
    "anonymous_access": false,
    "api_token_authentication": true,
    "accounts": {
      "enabled": false
    },
    "pushes": {
      "enabled": true,
      "email_auto_dispatch": false,
      "file_attachments": {
        "enabled": true,
        "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_by_email": {
      "recipients": "email1@example.com, email2@example.com",
      "locale": "fr"
    }
  }
}

cURL example (JSON body):

curl -X POST https://pwpush.involas.cloud/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://pwpush.involas.cloud/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://pwpush.involas.cloud/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://pwpush.involas.cloud/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://pwpush.involas.cloud/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://pwpush.involas.cloud/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://pwpush.involas.cloud/api/v2/pushes/expired?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

POST /api/v2/pushes/:url_token/notify_by_email

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

cURL example:

curl -X POST "https://pwpush.involas.cloud/api/v2/pushes/YOUR_URL_TOKEN/notify_by_email" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": "email1@example.com, email2@example.com",
    "locale": "fr"
  }'

Supported Locales

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

HTTP Status Codes

• 200 - Successful request
• 201 - Push created
• 400 - Invalid request parameters
• 401 - Authentication required or invalid token
• 403 - Forbidden for current user
• 404 - Resource not found
• 422 - Validation error