pastesite API and CLI

Developer guide · updated October 2026 · 8 min read

The pastesite API lets you create and read pastes from a terminal, script, or CI job. It is the same API the website uses. Browser paste creation is protected by Cloudflare Turnstile; for scripts, create a personal API key instead.

1. Create an API key

1. Sign in and open your dashboard.
2. Find the API keys section and click Create key.
3. Give it a label, choose its permissions and expiry, then copy the key when it appears. It is shown only once.

Keys act as your account, so scope them narrowly. A new key defaults to create and read; add manage only if a script needs to edit or delete pastes. The dashboard offers an expiry of 30 days, 90 days, one year, or never, and the API accepts any whole number from 1 to 3,650 days. An expired key stops working and is deleted the first time it is presented.

Do not commit keys to a repository or paste them into a public chat. Revoke a single key, or use Revoke all after a suspected leak.

2. Create a paste with curl

curl -s https://pastesite.com/api/pastes \
  -H "Authorization: Bearer ps_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "hello from the terminal",
    "title": "Terminal test",
    "language": "plaintext",
    "visibility": "unlisted"
  }'

The response includes the paste ID and shareable links:

{
  "ok": true,
  "paste": {
    "id": "x7Km2Qp9aL",
    "title": "Terminal test",
    "language": "plaintext",
    "visibility": "unlisted",
    "created_at": "2026-10-17T08:30:00.000Z",
    "views": 0,
    "url": "https://pastesite.com/#/p/x7Km2Qp9aL",
    "rawUrl": "https://pastesite.com/raw/x7Km2Qp9aL"
  }
}

Extract the link with jq:

curl -s https://pastesite.com/api/pastes \
  -H "Authorization: Bearer ps_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content":"hello","language":"plaintext","visibility":"unlisted"}' \
  | jq -r '.paste.url'

3. Pipe command output into a paste

content is a normal JSON string. Use jq -Rs to wrap stdin as a string:

./deploy.sh 2>&1 \
  | jq -Rs '{content: ., title: "deploy log", language: "bash", visibility: "unlisted"}' \
  | curl -s https://pastesite.com/api/pastes \
      -H "Authorization: Bearer ps_your_api_key" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq -r '.paste.url'

4. Read a paste as plain text

Use the friendly raw URL for pipes and downloads:

curl -s https://pastesite.com/raw/x7Km2Qp9aL

It returns text/plain with no HTML. A password-protected paste needs the password in a header (preferred) or query string:

curl -s https://pastesite.com/raw/x7Km2Qp9aL \
  -H "x-paste-password: your-password"

Burn-after-read pastes are deleted after the first successful read — whether that read came from the browser or this endpoint. Expired pastes return a 410; unknown IDs return 404.

Endpoints

Admin routes additionally require the caller's address to be listed in the server's ADMIN_EMAILS variable; the same allowlist decides the isAdmin flag on GET /api/me/profile. API keys cannot manage other API keys — that needs a browser session.

Fields for creating a paste

Rate limits and errors

Limits are per network address and apply to API-key requests too:

• 10 pastes created per 10 minutes (30 attempts per 10 minutes, so failed captchas cannot be spammed)
• 300 paste reads per 10 minutes across paste views and /raw/<id>
• 8 password attempts per paste per 15 minutes
• 5 abuse reports per hour

Repeated reads from the same network count as one view for 24 hours, so view counts and the trending list cannot be pumped from one machine. Errors are JSON for API routes and plain text for raw routes:

• 400 — invalid input (empty content, bad or reserved slug, expiry out of range, an unsupported screenshot data URL)
• 401 — missing/invalid API key, or a missing paste password
• 403 — the key lacks the required permission, you are not the owner, or the route needs admin access
• 404 — paste not found
• 409 — that custom URL or username is already taken
• 410 — paste expired
• 429 — rate limit reached

Security notes

• API keys are stored as SHA-256 hashes — salted with API_KEY_PEPPER when the server sets it — and the plaintext key is shown once.
• Use one key per machine or script so you can revoke it independently.
• Do not put keys in URLs, screenshots, or public pastes.
• Password-protected pastes are access-controlled, not end-to-end encrypted.
• Raw reads count as a view and can burn a burn-after-read paste.

Frequently asked questions

How do I create an API key?

Sign in, open your dashboard, find the API keys section, and click Create key. Copy the key when it appears — it is shown only once. Revoke it from the same section if it leaks.

Can I create a paste with curl?

Yes. Send a POST request to /api/pastes with an Authorization: Bearer ps_... header and a JSON body containing content. The response includes a shareable url and rawUrl.

Does the raw endpoint work without JavaScript?

Yes. GET /raw/<id> returns text/plain from the server, so curl, wget, and shell pipes work without a browser.

Can I limit what an API key can do?

Yes. Keys carry permissions: create, read, and manage. New keys can create pastes and read your own data; add manage only when a script needs to edit or delete. Keys can expire after 30 days, 90 days, a year, or never, and you can revoke all keys at once if one leaks.

Do API keys bypass the captcha?

Yes. API keys are issued to signed-in accounts and replace the browser Turnstile challenge for scripted creation. Paste creation is still rate-limited by IP.

Why do I get a 401 from /raw/<id>?

The paste is password-protected. Send the password in an x-paste-password header (preferred) or as a ?password= query parameter.

Related: Why pastesite? · The best pastebin sites · FAQ · Create a paste.