VOIDPASTE

REST API documentation

REST API for VoidPaste. Production base: https://voidpaste.com — versioned routes under /api/v1.

Base URL

  • Base: https://voidpaste.com (web + API same origin)
  • Versioned routes: /api/v1/…
  • Health: GET /health, GET /ready
  • Raw alias: GET /raw/{public_id} (same as /api/v1/pastes/{id}/raw)
  • Download alias: GET /download/{public_id}

Authentication

  • Session cookies — register/login set HttpOnly vp_session; use credentials: "include" from the web origin. Cookie-authenticated mutations also need X-CSRF-Token matching the vp_csrf cookie (GET /api/v1/auth/csrf). Bearer API keys skip CSRF.
  • API keys — Authorization: Bearer vp_live_… (or vp_test_…). Scopes are enforced: pastes:read for reads, pastes:write for mutations (* = all). Key management requires a session cookie.
  • Paste passwords: header X-Paste-Password (preferred); query ?password= also accepted for raw tooling.
  • Email verify: web page /verify-email?token=… posts to POST /api/v1/auth/verify-email. Mail From: [email protected].

Errors

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "request_id": "01JABC..."
  }
}

Limits

VoidPaste is free. Each paste is limited to 1 MB (1,048,576 bytes). Rate limits apply. There are no paid tiers. Optional Idempotency-Key on POST /api/v1/pastes replays the JSON response for 24h (Redis).

Privacy modes

  • public — anyone; may be discoverable later
  • unlisted — secret URL (default when omitted)
  • private — owner only (requires auth)
  • password — requires password field (otherwise 400 if a password is sent with another visibility)
  • Client-encrypted — client_encrypted: true; server stores ciphertext only; fragment key stays in the share URL

Pastes

MethodPathNotes
POST/api/v1/pastesCreate (anon or auth). Response: { paste, warnings }
GET/api/v1/pastes/{id}{ paste, burned }
GET/api/v1/pastes/{id}/rawtext/plain
GET/api/v1/pastes/{id}/downloadattachment
PATCH/api/v1/pastes/{id}Owner edit
DELETE/api/v1/pastes/{id}Owner soft-delete
GET/api/v1/me/pastesAuthenticated list
GET/api/v1/pastes/{id}/versionsOwner versions

Expiration presets: never, 10m, 1h, 1d, 1w, 1M (~30 days). Also relative durations and RFC3339. Burn-after-reading and max views are race-safe: the first successful GET that burns returns { paste, burned: true }; later opens get gone/not found.

Auth

  • POST /api/v1/auth/register
  • POST /api/v1/auth/verify-email
  • POST /api/v1/auth/login
  • POST /api/v1/auth/logout
  • POST /api/v1/auth/logout-all
  • POST /api/v1/auth/password-reset/request
  • POST /api/v1/auth/password-reset/confirm
  • GET /api/v1/auth/me
  • GET /api/v1/auth/providers

API keys & collections

  • POST /api/v1/api-keys — secret returned once
  • GET /api/v1/api-keys
  • DELETE /api/v1/api-keys/{id}
  • Collections: /api/v1/collections (auth)
  • Reports: POST /api/v1/reports

Example

curl -X POST "https://voidpaste.com/api/v1/pastes" \
  -H "Authorization: Bearer vp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"content":"hello","visibility":"unlisted","expiration":"1d"}'

Full OpenAPI: repo docs/api/openapi.yaml. Also see CLI.