Password Pusher API v2

BETA

Comprehensive REST API documentation for integrating Password Pusher into your applications

Beta Notice: API v2 is currently in beta. While we've made every effort to ensure stability, there may be breaking changes before the final release. We welcome your feedback!

Pushes

Pushes enable secure, one-way transmission of sensitive data to recipients. Create a push with a secret URL containing text, files, QR codes, or URLs, then share it with anyone—all without exposing sensitive data in email, chat, or logs.

Perfect for employee onboarding, sending account credentials, transmitting confidential documents, or sharing any sensitive information. Pushes automatically expire after a specified duration or number of views, and full lifecycle tracking is available in the audit logs of each push.

POST /api/v2/pushes

Creates a new push with the provided payload.

Request Body (JSON)

{
  "push": {
    "payload": "secret_password_123",
    "expire_after_duration": 6,
    "expire_after_views": 5,
    "passphrase": "optional_passphrase",
    "name": "Database Credentials",
    "note": "Internal note",
    "deletable_by_viewer": true,
    "retrieval_step": true,
    "kind": "text"
  },
  "account_id": 123
}

Request Body with Files (multipart/form-data)

curl -X POST https://us.pwpush.com/api/v2/pushes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "push[payload]=secret_password_123" \
  -F "push[expire_after_duration]=6" \
  -F "push[expire_after_views]=5" \
  -F "push[name]=Database Credentials" \
  -F "push[files][]=@/path/to/file1.pdf" \
  -F "push[files][]=@/path/to/file2.txt"

Note: When attaching files, use multipart/form-data format and set kind: "file". Multiple files can be attached using push[files][].

Parameters

Parameter	Type	Description
`payload` required	string	The secret text to share
`expire_after_duration` optional	integer (0-17)	Duration enum (0-17)
`expire_after_views` optional	integer (1-100)	Number of views before expiration
`passphrase` optional	string	Require passphrase to view
`name` optional	string	A name for the push
`note` optional	string	Internal note (only visible to creator)
`deletable_by_viewer` optional	boolean	Allow viewers to delete the push
`retrieval_step` optional	boolean	Require an extra step to retrieve
`kind` optional	string	Type: "text", "file", "url", or "qr" (defaults to "text")
`notify_emails_to` optional	string	Email addresses to be notified when a push is created (comma-separated)
`notify_emails_to_locale` optional	string	Locale (language) to send email notification(s) in
`account_id` optional	integer	The account ID to associate the push with (for users with multiple accounts)

Duration Values for `expire_after_duration`

0: 15 minutes

1: 30 minutes

2: 45 minutes

3: 1 hour

4: 6 hours

5: 12 hours

6: 1 day

7: 2 days

8: 3 days

9: 4 days

10: 5 days

11: 6 days

12: 1 week

13: 2 weeks

14: 3 weeks

15: 1 month

16: 2 months

17: 3 months

Example Request

curl -X POST https://us.pwpush.com/api/v2/pushes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "push": {
      "payload": "MySecretPassword123",
      "expire_after_duration": 6,
      "expire_after_views": 3
    }
  }'

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://us.pwpush.com/api/v2/pushes')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  push: {
    payload: 'MySecretPassword123',
    expire_after_duration: 6,
    expire_after_views: 3
  }
}.to_json

response = http.request(request)
puts response.body

import requests
import json

url = 'https://us.pwpush.com/api/v2/pushes'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'push': {
        'payload': 'MySecretPassword123',
        'expire_after_duration': 6,
        'expire_after_views': 3
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

$headers = @{
    'Authorization' = 'Bearer YOUR_API_TOKEN'
    'Content-Type' = 'application/json'
}

$body = @{
    push = @{
        payload = 'MySecretPassword123'
        expire_after_duration = 6
        expire_after_views = 3
    }
} | ConvertTo-Json -Depth 10

$response = Invoke-RestMethod -Uri 'https://us.pwpush.com/api/v2/pushes' `
    -Method Post `
    -Headers $headers `
    -Body $body

$response | ConvertTo-Json

GET /api/v2/pushes/:url_token

Retrieves the secret payload of a push. This increments the view count and may expire the push.

Example Request

curl -X GET https://us.pwpush.com/api/v2/pushes/fkwjfvhall92

Example Request with Passphrase

curl -X GET "https://us.pwpush.com/api/v2/pushes/fkwjfvhall92?passphrase=your_passphrase"

Example Response

{
  "url_token": "fkwjfvhall92",
  "payload": "MySecretPassword123",
  "views_remaining": 2,
  "expire_after_views": 3,
  "expired": false,
  "expired_on": null,
  "deletable_by_viewer": false,
  "retrieval_step": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "json_url": "https://us.pwpush.com/p/fkwjfvhall92.json",
  "html_url": "https://us.pwpush.com/p/fkwjfvhall92"
}

Note: If the push has a passphrase, include it as a query parameter: ?passphrase=your_passphrase. Retrieving a push counts as a view and may expire the push if it reaches its view limit.

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

Returns the fully qualified secret URL of a push without retrieving the payload.

Example Request

curl -X GET https://us.pwpush.com/api/v2/pushes/fkwjfvhall92/preview

Example Response

{
  "url": "https://us.pwpush.com/p/fkwjfvhall92"
}

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

Returns the audit log for a push. Requires authentication and ownership.

Query Parameters: page (optional): Page number for pagination. Returns up to 50 audit log entries per page.

Example Request

curl -X GET https://us.pwpush.com/api/v2/pushes/fkwjfvhall92/audit \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "logs": [
    {
      "ip": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "referrer": null,
      "kind": "creation",
      "created_at": "2023-10-27T10:00:00.000Z",
      "updated_at": "2023-10-27T10:00:00.000Z"
    },
    {
      "ip": "192.168.1.101",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
      "referrer": "https://example.com",
      "kind": "view",
      "created_at": "2023-10-27T10:05:00.000Z",
      "updated_at": "2023-10-27T10:05:00.000Z"
    }
  ]
}

Note: The kind field indicates the type of action logged. Common values include: creation, view, expire, failed_passphrase, and failed_view.

DELETE /api/v2/pushes/:url_token

Immediately expires a push and permanently deletes all sensitive data, including the payload and any attached files. This action is irreversible and cannot be undone. Requires authentication and ownership, or the push must have been created with deletable_by_viewer: true.

Example Request

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

Example Response

{
  "expire_after_duration": 7,
  "expire_after_views": 5,
  "expired": true,
  "url_token": "fkwjfvhall92",
  "deletable_by_viewer": false,
  "retrieval_step": false,
  "expired_on": "2023-10-27T10:15:00.000Z",
  "passphrase": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:15:00.000Z",
  "expire_after_days": 7,
  "days_remaining": null,
  "views_remaining": 0,
  "deleted": true,
  "json_url": "https://us.pwpush.com/p/fkwjfvhall92.json",
  "html_url": "https://us.pwpush.com/p/fkwjfvhall92",
  "account_id": 1,
  "note": null,
  "name": null
}

GET /api/v2/pushes/active

Returns a paginated list of your active (non-expired) pushes. Requires authentication.

GET /api/v2/pushes/expired

Returns a paginated list of your expired pushes. Requires authentication.

Query Parameters: page (optional): Page number for pagination. Returns up to 50 pushes per page.

Example Request (Active)

curl -X GET https://us.pwpush.com/api/v2/pushes/active \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Request (Expired)

curl -X GET https://us.pwpush.com/api/v2/pushes/expired \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

[
  {
    "expire_after_duration": 7,
    "expire_after_views": 5,
    "expired": false,
    "url_token": "abc123xyz789",
    "deletable_by_viewer": false,
    "retrieval_step": false,
    "expired_on": null,
    "passphrase": null,
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "expire_after_days": 7,
    "days_remaining": 7,
    "views_remaining": 5,
    "deleted": false,
    "json_url": "https://us.pwpush.com/p/abc123xyz789.json",
    "html_url": "https://us.pwpush.com/p/abc123xyz789",
    "account_id": 1,
    "note": null,
    "name": null
  },
  {
    "expire_after_duration": 1,
    "expire_after_views": 3,
    "expired": false,
    "url_token": "def456uvw012",
    "deletable_by_viewer": true,
    "retrieval_step": false,
    "expired_on": null,
    "passphrase": null,
    "created_at": "2023-10-26T15:30:00.000Z",
    "updated_at": "2023-10-26T15:30:00.000Z",
    "expire_after_days": 1,
    "days_remaining": 0,
    "views_remaining": 2,
    "deleted": false,
    "json_url": "https://us.pwpush.com/p/def456uvw012.json",
    "html_url": "https://us.pwpush.com/p/def456uvw012",
    "account_id": 1,
    "note": null,
    "name": null
  }
]

Last updated: December 01, 2025

Password Pusher API v2

Pushes

Create a Push

Request Body (JSON)

Request Body with Files (multipart/form-data)

Parameters

Duration Values for `expire_after_duration`

Example Request

Retrieve a Push

Example Request

Example Request with Passphrase

Example Response

Preview a Push

Example Request

Example Response

Get Push Audit Log

Example Request

Example Response

Expire a Push

Example Request

Example Response

Push Collections

Example Request (Active)

Example Request (Expired)

Example Response

Password Pusher API v2

Pushes

Create a Push

Request Body (JSON)

Request Body with Files (multipart/form-data)

Parameters

Duration Values for expire_after_duration

Example Request

Retrieve a Push

Example Request

Example Request with Passphrase

Example Response

Preview a Push

Example Request

Example Response

Get Push Audit Log

Example Request

Example Response

Expire a Push

Example Request

Example Response

Push Collections

Example Request (Active)

Example Request (Expired)

Example Response

Duration Values for `expire_after_duration`