For developers
API reference
The JSON API behind this site, described from the OpenAPI document that serves /api/openapi.json, so this page changes whenever the API does. Everything below is a reference — there is no console, just commands that work when pasted.
Base URL https://paste.ixiun.com
A burn paste is destroyed the first time it is successfully read. Reading one with curl consumes it, exactly like opening it in a browser.
POST /api/pastes
Create a paste. The request is a JSON object; the answer is the paste's short link. Content is stored byte for byte — nothing is trimmed or changed.
Fields
| Field | Rules | Default |
|---|---|---|
content string required | The text of the paste. Must be non-empty and at most 1048576 bytes (1 MiB by default). Stored and returned byte for byte: nothing is trimmed or changed. | — |
slug string | A custom address, 3 to 64 characters of letters, digits and hyphens. Case does not matter; it is stored and returned in lower case. Left out, a random 7-character slug is made. These addresses are reserved and refused: api, raw, docs, assets, static, new, about. | — |
expires_in integer | Seconds from now before the paste expires, a whole number from 1 to 31536000 (one year), or null for never. Default 2592000 (30 days). An expired paste is gone the moment it expires. | 2592000 |
password string | A non-empty password. Left out or null, the paste is open. The reader must send it in the X-Paste-Password header. It is never stored; the content is encrypted at rest. | — |
burn boolean | true destroys the paste the first time it is successfully read. Default false. | false |
language string | A hint for syntax highlighting: 1 to 32 characters of lower-case letters, digits, +, #, . and -. Default plaintext. | plaintext |
What comes back (201)
| Field | Meaning |
|---|---|
slug string | The paste's address on this site. |
url string | The full link to the paste, built from base_url. |
expires_at string or null | When the paste expires, UTC as YYYY-MM-DDTHH:MM:SSZ, or null for never. |
burn boolean | Whether the paste burns after one read. |
has_password boolean | Whether the paste is password-protected. |
language string | The syntax-highlighting hint. |
Answers
- 201The paste was created.
- 400The request body is not a single JSON object.
- 409That address is already in use by a live paste. The error also carries "field", naming the field.
- 413The content is over the maximum allowed size. The error also carries "field", naming the field.
- 429This client has created too many pastes recently. The Retry-After header says how long to wait. The error also carries "field", naming the field.
A 429 rate-limit answer carries a Retry-After header in whole seconds.
Example
curl -X POST https://paste.ixiun.com/api/pastes \
-H 'Content-Type: application/json' \
-d '{"content": "Hello, world!", "language": "php"}'GET /api/pastes/{slug}
Read a paste by its slug. The slug is lower case; case is not significant. If the paste has a password it must be sent in the X-Paste-Password header, never the query string. A wrong or missing password never burns the paste.
Parameters
| Parameter | Meaning |
|---|---|
slug path required | The paste's slug. Lower case; case is not significant. |
X-Paste-Password header | The password when the paste is protected. Never a query parameter. A wrong or missing password never burns the paste. |
What comes back (200)
| Field | Meaning |
|---|---|
slug string | The paste's slug. |
content string | The paste's text, byte for byte as it was created. |
language string | The syntax-highlighting hint. |
created_at string | When the paste was created, UTC as YYYY-MM-DDTHH:MM:SSZ. |
expires_at string or null | When the paste expires, UTC, or null for never. |
burn boolean | Whether the paste burns after one read. |
has_password boolean | Whether the paste is password-protected. |
Answers
- 200The paste was read. For a burn paste, this read is the one that destroys it.
- 401The paste has a password and none was sent.
- 404No such paste: it never existed, or has already expired or been read. The error also carries "field", naming the field.
- 429This client has sent too many wrong passwords for this paste recently. The Retry-After header says how long to wait. The error also carries "field", naming the field.
A 429 rate-limit answer carries a Retry-After header in whole seconds.
Example — reading a protected paste
curl https://paste.ixiun.com/api/pastes/k7m2xq9 \ -H 'X-Paste-Password: hunter2'
Error codes
An error answer is a JSON object with an error holding a code and a
message written for a person.
Every error code the API can return:
invalid_jsoninvalid_fieldpassword_requiredpassword_incorrectnot_foundmethod_not_allowedslug_takentoo_largerate_limited
Limits
20 per hour
Creating pastes
Once a client has created this many pastes inside the window, further creates from that client are 429 until the window moves on. Other clients are unaffected. Limits are kept in the database.
10 per 15 minutes
Wrong passwords, per paste
Once a client has sent this many wrong passwords for one paste inside the window, every further attempt by that client on that paste is 429, even with the right password, until the window moves on. Other clients and other pastes are unaffected. A request with no password at all is not an attempt.
A 429 answer carries a Retry-After header in whole seconds.
Back to the create page — or the full machine-readable description at /api/openapi.json.