API Overview

All API endpoints are under /api/v1/. Responses are JSON.

Authentication

API keys are passed via the X-Api-Key header:

X-Api-Key: pb_<your-key>

Most endpoints work without authentication (anonymous mode) with stricter rate limits.

Mode	Rate Limit
Anonymous	5 requests/minute
Authenticated	60 requests/minute

Base URL

All examples assume your instance is at https://paste.example.com.

Errors

Errors return JSON with an error field:

{
  "error": "Not Found"
}

Validation errors include details:

{
  "error": "Validation Error",
  "details": [
    { "path": ["content"], "message": "Required" }
  ]
}

Health Checks

Endpoint	Description
GET /healthz	Liveness check, always returns {"status":"ok"}
GET /readyz	Readiness check, verifies database connectivity