Paste API Documentation

The Paste API allows you to programmatically create, retrieve, update, and delete pastes.

Authentication

All authenticated endpoints require an API key. You can generate and manage API keys from your profile page.

Authentication Methods

X-API-Key: your_api_key_here

?api_key=your_api_key_here

{"api_key": "your_api_key_here"}

Prefer a header: query strings end up in server and proxy logs.

Key Scopes

When you create a key you choose what it can do. A request outside the key's scopes gets 403.

Keys are stored hashed, so they cannot be shown again. If you lose one, regenerate it on your profile page; it keeps its name and scopes. Endpoints that take an id accept a slug or a number; when the site blocks numeric URLs, numbers only find your own pastes.

Guest Access

This site lets guests create pastes and upload images and videos without a key: leave the key out and the request is made as Guest. Guests can make 10 requests per minute per IP address. Guest pastes cannot be private, and guests cannot read, change or delete anything, so keep the links from the reply.

Rate Limits

Each key can make 60 requests per minute. Every reply says where you are:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1738411260

• X-RateLimit-Reset is the Unix time the minute ends
• Over the limit the API answers 429 with a Retry-After header in seconds
• Each key gets 10 wrong paste passwords per 10 minutes
• Uploads also count against the site's hourly upload limit and daily allowance

POST Create Paste

Create a new paste with the provided content and optional settings.

Endpoint

POST https://paste.boxlabs.uk/api.php?action=paste

Parameters

Text that is not valid UTF-8, an unknown visibility or an unknown expiry is refused with 400.

Example Request

curl -X POST "https://paste.boxlabs.uk/api.php?action=paste" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "print(\"Hello, World!\")",
    "title": "My Python Script",
    "syntax": "python",
    "visibility": "public"
  }'

Example Response

{
  "success": true,
  "paste": {
    "id": 123,
    "slug": "aBcDeFgH",
    "url": "https://paste.boxlabs.uk/aBcDeFgH",
    "title": "My Python Script",
    "syntax": "python",
    "visibility": "public",
    "expiry": "1D",
    "expires_at": "2026-02-04T14:30:00+00:00",
    "view_once": false,
    "password_protected": false,
    "encrypted": false,
    "encrypted_at_rest": true,
    "created_at": "2026-02-03 14:30:00"
  }
}

GET Get Paste

Retrieve an existing paste by its numeric ID or slug.

Endpoint

GET https://paste.boxlabs.uk/api.php?action=get&id={id_or_slug}

Parameters

Reading a view-once paste counts as its view, so it is deleted after the first reader and the reply has "deleted": true. encrypted is true when content is ciphertext from a paste encrypted in the browser; encrypted_at_rest is true for pastes the server stores encrypted and decrypts for you.

Example Request

curl "https://paste.boxlabs.uk/api.php?action=get&id=aBcDeFgH" \
  -H "X-API-Key: YOUR_API_KEY"

# Text only, from a password-protected paste
curl "https://paste.boxlabs.uk/api.php?action=get&id=aBcDeFgH&format=raw" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Paste-Password: hunter2"

Example Response

{
  "success": true,
  "paste": {
    "id": 123,
    "slug": "aBcDeFgH",
    "title": "My Python Script",
    "content": "print(\"Hello, World!\")",
    "syntax": "python",
    "visibility": "public",
    "expiry": "NULL",
    "expires_at": null,
    "view_once": false,
    "deleted": false,
    "password_protected": false,
    "encrypted": false,
    "encrypted_at_rest": true,
    "views": 42,
    "created_at": "2026-02-03 14:30:00",
    "author": "johndoe"
  }
}

PUT Update Paste

Modify an existing paste you own. Only supply the fields you want to change.

Endpoint

POST/PUT https://paste.boxlabs.uk/api.php?action=update&id={id_or_slug}

Parameters

Example Request

curl -X PUT "https://paste.boxlabs.uk/api.php?action=update&id=aBcDeFgH" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "content": "print(\"Updated content!\")"}'

DELETE Delete Paste

Permanently delete a paste you own.

Endpoint

DELETE https://paste.boxlabs.uk/api.php?action=delete&id={id_or_slug}

Example Request

curl -X DELETE "https://paste.boxlabs.uk/api.php?action=delete&id=aBcDeFgH" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "message": "Paste deleted successfully"
}

GET List Pastes

Retrieve a paginated list of pastes belonging to the authenticated user.

Endpoint

GET https://paste.boxlabs.uk/api.php?action=list

Parameters

Example Request

curl "https://paste.boxlabs.uk/api.php?action=list&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

GET Search Pastes

Search your own pastes by title or content.

Endpoint

GET https://paste.boxlabs.uk/api.php?action=search&q={query}

Parameters

GET User Info

Get basic information about the authenticated account.

Endpoint

GET https://paste.boxlabs.uk/api.php?action=user

Example Response

{
  "success": true,
  "user": {
    "username": "johndoe",
    "email": "john@example.com",
    "paste_count": 42,
    "api_key_count": 2
  }
}

POST Upload Image or Video

Upload a file to /img. It is stored encrypted with its link as the key, like uploads from the website, and the same limits apply. JPEG, PNG, GIF and WebP images and MP4, WebM, MOV, AVI and MKV videos are accepted.

Endpoint

POST https://paste.boxlabs.uk/api.php?action=upload

Parameters (multipart/form-data)

Example Request

curl -X POST "https://paste.boxlabs.uk/api.php?action=upload" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@photo.jpg"

Example Response (201)

{
  "success": true,
  "upload": {
    "key": "nD3SrAgZive8g4Y4JcsFV8",
    "url": "https://paste.example.com/img/nD3SrAgZive8g4Y4JcsFV8",
    "file": "https://paste.example.com/img/nD3SrAgZive8g4Y4JcsFV8.jpg",
    "kind": "image",
    "mime": "image/jpeg",
    "ext": "jpg",
    "name": "photo.jpg",
    "size": 183204,
    "expires": null
  }
}

file is the direct link and url the view page. The key is in both links and the server does not keep it, so save the reply if you may want to delete the upload later. Errors: 413 too large for the server, 422 wrong type or size, 429 hourly limit or daily allowance reached, 503 uploads turned off.

DELETE Delete Upload

Delete an upload made by your account. key is the key, or either link, from the upload reply.

Endpoint

DELETE https://paste.boxlabs.uk/api.php?action=upload_delete&key={key}

Example Request

curl -X DELETE "https://paste.boxlabs.uk/api.php?action=upload_delete&key=nD3SrAgZive8g4Y4JcsFV8" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "deleted": true
}

Error Codes

Error Response Format

{
  "success": false,
  "error": "Human-readable error message"
}

Code Examples

• Python
• Bash
• JavaScript
• PHP

import requests

API_URL = "https://paste.boxlabs.uk/api.php"
API_KEY = "your_api_key_here"

headers = {"X-API-Key": API_KEY}

# Create a paste
response = requests.post(
    f"{API_URL}?action=paste",
    headers=headers,
    json={
"content": "print('Hello, World!')",
"title": "My Python Paste",
"syntax": "python"
    }
)
result = response.json()
print(f"Paste URL: {result['paste']['url']}")

# Get a paste
response = requests.get(
    f"{API_URL}?action=get&id=aBcDeFgH",
    headers=headers
)
paste = response.json()['paste']
print(f"Content: {paste['content']}")

#!/bin/bash
API_URL="https://paste.boxlabs.uk/api.php"
API_KEY="your_api_key_here"

# Create a paste from file
paste_file() {
    curl -s -X POST "$API_URL?action=paste" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d "{\"content\": $(cat "$1" | jq -Rs .), \"title\": \"$1\", \"syntax\": \"text\"}"
}

# Create paste from stdin
echo "Hello, World!" | curl -s -X POST "$API_URL?action=paste" \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"content\": \"$(cat)\"}"

const API_URL = 'https://paste.boxlabs.uk/api.php';
const API_KEY = 'your_api_key_here';

// Create a paste
async function createPaste(content, title, syntax) {
    const response = await fetch(`${API_URL}?action=paste`, {
method: 'POST',
headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
},
body: JSON.stringify({ content, title, syntax })
    });
    return response.json();
}

// Get a paste
async function getPaste(id) {
    const response = await fetch(`${API_URL}?action=get&id=${id}`, {
headers: { 'X-API-Key': API_KEY }
    });
    return response.json();
}

// Usage
createPaste('console.log("Hello!");', 'My JS Paste', 'javascript')
    .then(result => console.log('Created:', result.paste.url));

<?php
$api_url = 'https://paste.boxlabs.uk/api.php';
$api_key = 'your_api_key_here';

// Create a paste
$data = [
    'content' => '<?php echo "Hello, World!"; ?>',
    'title' => 'My PHP Paste',
    'syntax' => 'php'
];

$ch = curl_init("$api_url?action=paste");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
"X-API-Key: $api_key",
"Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Paste URL: " . $response['paste']['url'];
?>