BeanPaste - A Tiny Way to Share Text

API v1

Create and read pastes from scripts and tools. Provision a token, then send it as Authorization: Bearer <token> to create and list pastes. A token lists only the pastes it created.

Pastes are public by default: anyone can view a public paste's web page at its web_url, or read it at its api_url without a token. A private paste has no web page, so it has no web_url and can only be read at its api_url with the token that created it. Every paste has an api_url, and a url that's its web_url if it has one, or else its api_url.

Only a hash of each token is stored, so keep yours safe: a lost token can't be recovered.

Quick start

TOKEN=$(curl -s -X POST http://beanpaste.fun/api/v1/tokens | jq -r .token)

curl -s -X POST http://beanpaste.fun/api/v1/pastes \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content": "hello"}'

curl -s http://beanpaste.fun/api/v1/pastes -H "Authorization: Bearer $TOKEN"

`POST /api/v1/tokens`

Provision a new token. Needs no auth and no body.

201 {"token": "E7R6WMBZBJEYVZ4VXMZRHR42H5"}

`POST /api/v1/pastes`

Create a paste. Send a JSON body with:

content: the text to paste. Required.
expires_at: when the paste expires, as an RFC 3339 timestamp in the future, such as 2030-01-01T00:00:00Z. It needs a time and timezone; a date alone is rejected. Once it passes, the paste can't be read or listed. Optional.
private: true to keep the paste off the web, so only this token can read it. Optional, defaults to false.

The request body can be up to 1 MB.

201 {"api_url": "http://beanpaste.fun/api/v1/pastes/Q7N1Ak", "id": "Q7N1Ak", "private": false, "url": "http://beanpaste.fun/p/Q7N1Ak", "web_url": "http://beanpaste.fun/p/Q7N1Ak"}
201 {"api_url": "http://beanpaste.fun/api/v1/pastes/Zk9dTw", "id": "Zk9dTw", "private": true, "url": "http://beanpaste.fun/api/v1/pastes/Zk9dTw"}

`GET /api/v1/pastes`

List the token's unexpired pastes, newest first.

200 [
  {"api_url": "http://beanpaste.fun/api/v1/pastes/Zk9dTw", "id": "Zk9dTw", "private": true, "url": "http://beanpaste.fun/api/v1/pastes/Zk9dTw"},
  {"api_url": "http://beanpaste.fun/api/v1/pastes/Q7N1Ak", "id": "Q7N1Ak", "private": false, "url": "http://beanpaste.fun/p/Q7N1Ak", "web_url": "http://beanpaste.fun/p/Q7N1Ak"}
]

`GET /api/v1/pastes/:id`

Read one paste. A public paste needs no token; a private one needs the token that created it. A token you do send must be valid, even for a public paste. Returns 404 if the paste doesn't exist, has expired, or is private and wasn't created with the token sent.

200 {"api_url": "http://beanpaste.fun/api/v1/pastes/Q7N1Ak", "content": "hello", "id": "Q7N1Ak", "private": false, "url": "http://beanpaste.fun/p/Q7N1Ak", "web_url": "http://beanpaste.fun/p/Q7N1Ak"}

Errors

Errors are JSON, such as {"error": "content is required"}, with one of these statuses:

400: the body is missing, isn't valid JSON or has a field of the wrong type; content is empty; or expires_at isn't an RFC 3339 timestamp in the future.
401: the token wasn't provisioned here, or is missing on a request that needs one.
404: the paste doesn't exist, has expired, or is private and wasn't created with the token sent.
413: the request body is over 1 MB. This error is plain text, not JSON.

Working with an LLM? Point it at /llms.txt.