Password Pusher Logo
Bit By Bit One Time Secret Go Ahead. Email Another Password.

Password Pusher API v2

Complete JSON API documentation for creating, retrieving and managing pushes in the open-source edition.

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://secret.bitxbit.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://secret.bitxbit.com/api/v2/version
{
  "application_version": "2.6.5",
  "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": true,
        "requires_authentication": true
      },
      "url_pushes": {
        "enabled": true
      },
      "qr_code_pushes": {
        "enabled": true
      }
    },
    "requests": {
      "enabled": false
    }
  }
}

Features Hash

  • anonymous_access - Whether anonymous API usage is allowed (Settings.allow_anonymous)
  • api_token_authentication - Bearer token authentication support
  • accounts.enabled - Accounts API availability (not available in OSS)
  • pushes.enabled - Push creation and management via API
  • pushes.file_attachments.enabled - File attachments on pushes (Settings.enable_file_pushes)
  • pushes.url_pushes.enabled - URL push type (Settings.enable_url_pushes)
  • pushes.qr_code_pushes.enabled - QR code push type (Settings.enable_qr_pushes)
  • requests.enabled - Requests API availability (not available in OSS)

Push Endpoints

POST /api/v2/pushes

Create a new push.

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

Parameter Type Required Description
payloadstringYesSecret text payload for text, URL or QR pushes.
filesarrayNoFiles to attach. When present, the push type becomes file unless kind is explicitly provided.
kindstringNoPush type: text, file, url, or qr. Defaults to text when not provided.
expire_after_daysintegerNoExpiration window in days. If omitted, instance defaults are used.
expire_after_viewsintegerNoMaximum allowed retrieval count. If omitted, instance defaults are used.
deletable_by_viewerbooleanNoAllows the recipient to expire the push.
retrieval_stepbooleanNoAdds an extra retrieval confirmation step.
passphrasestringNoRequires this passphrase to retrieve the payload.
namestringNoOptional label shown to the owner.
notestringNoOptional owner-only note.
 
{
  "push": {
    "payload": "my-secret",
    "expire_after_days": 1,
    "expire_after_views": 5,
    "passphrase": "optional-passphrase",
    "deletable_by_viewer": true,
    "retrieval_step": true
  }
}

cURL example (JSON body):

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

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

For legacy API v1 documentation, see /api.