📡 API Documentation

Overview

All API requests go to https://zpst.net/api.php with an action query parameter.

Responses are always JSON with an ok boolean field. Authenticated requests use the X-API-Key header.

CLI Client — zpst

A bash script that wraps the API. Requires curl and python3.

Install

# Download and install
curl -fsSL https://zpst.net/download-client.php -o ~/.local/bin/zpst
chmod +x ~/.local/bin/zpst

# Set your API key (optional, needed for private pastes and list)
mkdir -p ~/.config/pastephp
echo 'PASTEPHP_KEY=your_api_key_here' >> ~/.config/pastephp/config
echo 'PASTEPHP_URL=https://zpst.net' >> ~/.config/pastephp/config

Examples

# Create from text
zpst create "hello world"

# Create from file (title + language auto-detected)
zpst create main.py

# Create with options
zpst create notes.txt --title "My Notes" --lang markdown --expiry 86400 --visibility unlisted

# Pipe into it
echo "SELECT * FROM users;" | zpst create --lang sql

# Create and copy URL to clipboard
zpst create script.sh | xclip -selection clipboard

# View paste content
zpst view aB3xKq

# Save paste to file
zpst download aB3xKq output.py

# Delete (use delete_token shown at creation for guest pastes)
zpst delete aB3xKq
zpst delete aB3xKq your_delete_token

# List your pastes
zpst list

# Show paste metadata
zpst info aB3xKq

Authentication

Pass your API key in the X-API-Key header. Guest usage (no key) is allowed for creating and reading public/unlisted pastes if the site permits it.

curl -H "X-API-Key: your_api_key_here" \
  "https://zpst.net/api.php?action=list"

POST Create Paste

https://zpst.net/api.php?action=create

Accepts JSON body or form POST (application/x-www-form-urlencoded).

Body Parameters

Example

curl -X POST "https://zpst.net/api.php?action=create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_key" \
  -d '{
    "content": "print(\"hello world\")",
    "title": "Hello",
    "language": "python",
    "expiry": 3600,
    "visibility": "unlisted"
  }'

Response

{
  "ok": true,
  "slug": "aB3xKq",
  "url": "https://zpst.net/p/aB3xKq",
  "raw_url": "https://zpst.net/raw/aB3xKq",
  "language": "python",
  "visibility": "unlisted",
  "expires_at": "2024-01-01 13:00:00",
  "burn": false,
  "delete_token": "abc123..."
}

Guest pastes include a delete_token — save it to delete the paste later.

GET Get Paste

https://zpst.net/api.php?action=get&slug=<slug>

Returns paste metadata and full content. For password-protected pastes, pass the password via ?password= or the X-Paste-Password header.

curl "https://zpst.net/api.php?action=get&slug=aB3xKq"

# Password protected
curl "https://zpst.net/api.php?action=get&slug=aB3xKq&password=secret"

GET Raw Content

https://zpst.net/api.php?action=raw&slug=<slug>

Returns the paste content as text/plain. Useful for piping directly into other tools.

# Print to terminal
curl "https://zpst.net/api.php?action=raw&slug=aB3xKq"

# Pipe into a command
curl -s "https://zpst.net/api.php?action=raw&slug=aB3xKq" | python3

# Save to file
curl -s "https://zpst.net/api.php?action=raw&slug=aB3xKq" > script.py

GET Delete Paste

https://zpst.net/api.php?action=delete&slug=<slug>&token=<token>

Delete using your API key (owner/admin) or the delete_token returned when a guest paste was created.

# Authenticated delete
curl -H "X-API-Key: your_key" \
  "https://zpst.net/api.php?action=delete&slug=aB3xKq"

# Guest delete with token
curl "https://zpst.net/api.php?action=delete&slug=aB3xKq&token=your_delete_token"

GET List Pastes

https://zpst.net/api.php?action=list

Lists pastes belonging to the authenticated user. Requires an API key.

curl -H "X-API-Key: your_key" \
  "https://zpst.net/api.php?action=list&limit=10&offset=0"

Errors

All errors return "ok": false with an error string and a relevant HTTP status code.

{ "ok": false, "error": "Paste not found." }