API Documentation

Base URL

https://pastebox.io/api/paste.php

Authentication

API key (recommended for scripts)

Registered users can generate API keys from your Profile → API Keys. A key authenticates the request as you — no session cookie or CSRF token needed. Send it in the Authorization header (or the X-API-Key header):

Authorization: Bearer pb_your_api_key

Keys are per-account and rate-limited per key. You can pause or delete a key at any time; an administrator can disable individual keys or the whole API.

Browser session (CSRF token)

Requests made from a logged-in browser session instead use a CSRF token, read from the tag on every page, sent as a header:

X-CSRF-Token: your_csrf_token

Read-only endpoints (fetching a paste and its raw content) require no key or account. For example, fetch any public paste as plain text:

curl -s -H "Authorization: Bearer pb_your_api_key" \
  -d '{"content":"hello","syntax":"text"}' \
  https://pastebox.io/api/paste.php?action=create

Create Paste

POST /api/paste.php?action=create

Parameters

Parameter	Type	Required	Description
content	string	Yes	The paste content
title	string	No	Paste title (default: "Untitled")
syntax	string	No	Syntax language slug (default: "plaintext")
expiration	string	No	Expiration: 5min, 10min, 1hour, 1day, 1week, 2weeks, 1month, 6months, 1year, never
visibility	string	No	public, unlisted, or private (default: "public")
slug	string	No	Custom URL slug (logged-in users only, and only when the admin has enabled custom URLs): 3–64 chars, lowercase letters/numbers/hyphens. Ignored for guests, when disabled, or if taken/invalid — a random slug is used instead.
password	string	No	Password to protect the paste
burn_after_read	boolean	No	Delete paste after first view
encrypt	boolean	No	Enable server-side encryption

Example Request

curl -X POST https://pastebox.io/api/paste.php?action=create \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_TOKEN" \
  -d '{
    "content": "console.log(\"Hello World\");",
    "title": "Hello World",
    "syntax": "javascript",
    "expiration": "1week",
    "visibility": "public"
  }'

Example Response

{
  "success": true,
  "message": "Paste created successfully.",
  "url": "https://pastebox.io/paste/abc123",
  "slug": "abc123"
}

Get Raw Paste

GET /api/paste.php?action=raw&slug={slug}

Returns the raw text content of a paste. For password-protected pastes, pass the password as a query parameter.

Example

curl https://pastebox.io/api/paste.php?action=raw&slug=abc123

Download Paste

GET /api/paste.php?action=download&slug={slug}

Downloads the paste as a file with the appropriate file extension based on syntax language.

Delete paste

POST /api/paste.php?action=delete

Delete a paste. Only available to the paste owner or administrators.

Example Request

curl -X POST https://pastebox.io/api/paste.php?action=delete \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_TOKEN" \
  -d '{"slug": "abc123"}'

Rate Limits

API-key requests: 1000 per hour per key (set by the site administrator; a 429 is returned when exceeded).
Guest paste creation (no key/session): 10 pastes per hour per IP. Logged-in users are not IP-rate-limited on creation.
Password unlock attempts: 10 per 10 minutes per paste.
Reports: 5 per hour per IP.
Read-only endpoints (view / raw / download) are not rate-limited.

When a limit is exceeded the request is rejected; wait before retrying.

Error Responses

All error responses follow this format:

{
  "success": false,
  "message": "Error description here."
}