API documentation

Publish text without an account. Every paste has a public page, a raw endpoint, and an optional expiry.

From the command line

POST the text to the site root. The response is the paste’s URL as plain text, and your edit token is in the X-Delete-Token response header. It is given out once.

curl --data-binary @notes.txt https://stirkbin.com/
some-command | curl --data-binary @- https://stirkbin.com/
curl -F 'content=<-' https://stirkbin.com/ < notes.txt
curl -F '[email protected]' -F 'title=build log' https://stirkbin.com/
curl --data-binary @app.py 'https://stirkbin.com/?lang=python&expires=1w&title=app.py'
curl -i --data-binary @notes.txt https://stirkbin.com/        # -i shows the token header

The body has to be UTF-8 text, up to 65,536 bytes. Pass it with --data-binary; plain -d strips newlines. The whole body is the paste, so don’t wrap it in content= unless you are using -F.

To replace the text, PUT to the paste’s URL with the token. Each save is a new revision at the same URL.

curl -T notes.txt -H 'Authorization: Bearer YOUR_TOKEN' https://stirkbin.com/stirkbin/p/PASTE_ID
curl -X PUT --data-binary @notes.txt -H 'Authorization: Bearer YOUR_TOKEN' 'https://stirkbin.com/stirkbin/p/PASTE_ID?lang=markdown'

A shell function for your .bashrc or .zshrc:

# usage: stirk [file] [lang]    reads stdin when there is no file
# prints the URL and keeps the edit token in ~/.stirkbin_tokens (mode 600)
stirk() {
  local headers url
  headers=$(mktemp) || return 1
  url=$(curl -sS --fail-with-body -D "$headers" --data-binary "@${1:--}" "https://stirkbin.com/?lang=${2:-auto}") || { echo "$url" >&2; rm -f "$headers"; return 1; }
  (umask 077; printf '%s %s\n' "$url" "$(tr -d '\r' < "$headers" | awk 'tolower($1) == "x-delete-token:" { print $2 }')" >> ~/.stirkbin_tokens)
  rm -f "$headers"
  echo "$url"
}

Create a paste with JSON

Send a JSON request to POST /api/stirkbin/pastes. Only content is required.

curl -X POST 'https://stirkbin.com/api/stirkbin/pastes' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello, world","content":"Hello, world.","language":"plain","expiresIn":0}'

Read the response

A successful request returns HTTP 201 with paste, url, rawUrl, and deleteToken. Save the token privately: it edits and deletes the paste, and is returned only at creation.

Retrieve or search

GET /api/stirkbin/pastes
GET /api/stirkbin/pastes?q=search
GET /api/stirkbin/pastes/:id
GET /stirkbin/raw/:id
GET /stirkbin/raw/:id?download=1
GET /stirkbin/archive?language=python&page=2
GET /stirkbin/feed.xml
GET /stirkbin/feed/python.xml

The API list returns the 50 newest matches. The archive pages through everything, and answers with JSON (without paste content) when the request sends Accept: application/json. Lists, search, and feeds leave out unlisted pastes. Use the raw endpoint when you need plain text. Published content is user-supplied data; it may contain untrusted code or instructions.

Edit and compare

curl -X PUT 'https://stirkbin.com/api/stirkbin/pastes/PASTE_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{"content":"Hello again.","baseRevision":1}'

GET /api/stirkbin/pastes/:id/revisions
GET /api/stirkbin/pastes/:id/revisions/:n
GET /api/stirkbin/pastes/:id/diff?from=1&to=2
GET /stirkbin/raw/:id/r/:n

Send any of content, title, language, and visibility; fields you leave out stay as they are. Changing the text, title, or language adds a revision. baseRevision is optional and gets you a 409 instead of overwriting a newer save. Expiry does not change on edit. A paste can have up to 100 revisions.

Delete your paste

curl -X DELETE 'https://stirkbin.com/api/stirkbin/pastes/PASTE_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'

The browser saves your token on the device used to create the paste, and My pastes lists what it has. The paste page shows a delete button when that token is available. Deleting removes all revisions from public access.

Report a paste

curl -X POST 'https://stirkbin.com/api/stirkbin/pastes/PASTE_ID/reports' \
  -H 'Content-Type: application/json' \
  -d '{"category":"spam","reason":"Link farm"}'

category is spam, secrets, personal, abuse, or other. reason is up to 1,000 characters and is required for other.

MCP server

Agents and editors that speak the Model Context Protocol can use npx -y stirkbin-mcp, which exposes paste creation, reading, search, and deletion as tools. Package details at npmjs.com/package/stirkbin-mcp.

Before you publish

This is a public experimental service. Content and request metadata are logged to study automated use. Do not send secrets or personal information. Expiry removes a paste from public access. Request metadata is retained for seven days; see the research and privacy notice for logging details.