API Documentation

// REST API Reference

Manage your pastes programmatically over a JSON REST API at https://pastey.example/api. Every endpoint requires authentication.

Authentication

The API is authenticated with personal API keys. Generate one from Settings → API Keys and send it with every request. Two headers are supported:

Authorization: Bearer pk_<your key> // primary X-API-Key: pk_<your key> // fallback

API keys are scoped for safety: they are rejected with 403 on /api/keys and /api/admin/*, so a leaked key can neither mint new keys nor reach admin functionality. Keys can be revoked at any time from Settings.

Quick Start

// list your pastes

$ curl -H "Authorization: Bearer pk_YOUR_KEY" \
  https://pastey.example/api/users/me

// Pastes

POST /api/pastes API key

Create a paste on your account.

JSON body

content string (required) The paste content. Must not be empty.

title string Paste title. Defaults to "Untitled".

lang string Syntax highlighting language. Defaults to "plaintext".

expiry enum One of: 10m, 1h, 1d, 1w, 1mo, never. Defaults to never.

visibility enum One of: public, unlisted, private. Defaults to public.

custom_slug string Custom URL (3–50 chars, letters/numbers/-/_).

Example response

{
  "id": "aB3d",
  "title": "hello.ts",
  "content": "console.log('hi')",
  "lang": "typescript",
  "expiry": "1d",
  "visibility": "public",
  "author_name": "alice",
  "views": 0,
  "created_at": "2026-07-27T10:00:00.000Z",
  "expires_at": "2026-07-28T10:00:00.000Z"
}

GET /api/pastes/:id API key

Fetch a paste by ID. Private pastes are only visible to their owner. Expired pastes return 404.

GET /api/pastes/:id/raw API key

Fetch the raw paste content as text/plain — ideal for piping into scripts.

PUT /api/pastes/:id API key

Update a paste you own. Accepts the same body fields as create.

DELETE /api/pastes/:id API key

Delete a paste you own (admins may delete any paste).

Example response

{ "message": "paste deleted successfully" }

// Users

GET /api/users/me API key

List all of your pastes, including unlisted and private ones.

Example response

{ "pastes": [ ... ], "total": 12 }

GET /api/users/:username API key

List a user's public pastes. When requesting your own username, all pastes are included.

Example response

{ "pastes": [ ... ], "total": 4 }

// API Keys

These endpoints require a browser session or JWT — API keys cannot manage other API keys.

GET /api/keys Session only

List your API keys. Only the prefix is returned; the full key is never stored.

Example response

{
  "keys": [
    {
      "id": "6f1c...",
      "name": "ci-deploy",
      "prefix": "pk_a1b2c3d",
      "created_at": "2026-07-27T10:00:00.000Z",
      "last_used_at": null
    }
  ]
}

POST /api/keys Session only

Create an API key (max 10 per user). The raw key is returned exactly once — store it securely.

JSON body

name string (required) A label for the key, up to 50 characters.

Example response

{
  "id": "6f1c...",
  "name": "ci-deploy",
  "prefix": "pk_a1b2c3d",
  "created_at": "2026-07-27T10:00:00.000Z",
  "last_used_at": null,
  "key": "pk_<64 hex chars — shown only once>"
}

DELETE /api/keys/:id Session only

Revoke an API key immediately.

Example response

{ "message": "API key revoked" }

// Errors

All errors share a single JSON shape:

{ "error": "human readable message" }

400 Bad request — missing or invalid fields

401 Authentication required or token/key invalid

403 Forbidden — insufficient permissions, or API key used on a restricted endpoint

404 Resource not found (or paste expired)

409 Conflict — e.g. custom URL already taken

500 Internal server error