API Reference

Returns the build version of the running server.

{
  "version": "1.4.0"
}

copycurl -s $BASE/api/v0/version

Generates a fresh AES key. The key is returned once and never persisted.

{
  "key": "b64-encoded-aes-key"
}

copycurl -s $BASE/api/v0/cipher/aes

Encrypts data with the given AES key.

{
  "data": "b64-cipher-text"
}

copycurl -s -X POST $BASE/api/v0/cipher/aes/encrypt \
  -H 'Content-Type: application/json' \
  -d '{"data":"hello","key":"<key>"}'

Decrypts data produced by the encrypt endpoint using the same key.

{
  "data": "hello"
}

copycurl -s -X POST $BASE/api/v0/cipher/aes/decrypt \
  -H 'Content-Type: application/json' \
  -d '{"data":"<cipher>","key":"<key>"}'

Generates a fresh 2048-bit RSA key pair. Both keys are returned once and never persisted.

{
  "publicKey": "b64-x509-public-key",
  "privateKey": "b64-pkcs8-private-key"
}

copycurl -s $BASE/api/v0/cipher/rsa/keypair

Encrypts data with an RSA publicKey. Only the holder of the matching private key can read the result.

{
  "data": "b64-cipher-text"
}

copycurl -s -X POST $BASE/api/v0/cipher/rsa/encrypt \
  -H 'Content-Type: application/json' \
  -d '{"data":"aGVsbG8=","publicKey":"<public-key>"}'

Decrypts data produced by the encrypt endpoint using the matching private key.

{
  "data": "aGVsbG8="
}

copycurl -s -X POST $BASE/api/v0/cipher/rsa/decrypt \
  -H 'Content-Type: application/json' \
  -d '{"data":"<cipher>","privateKey":"<private-key>"}'

Signs data with the private key using SHA256withRSA. The payload is hashed first, so there is no size limit — and note that a signature proves authorship without hiding anything: the data itself stays readable.

{
  "signature": "b64-signature"
}

copycurl -s -X POST $BASE/api/v0/cipher/rsa/sign \
  -H 'Content-Type: application/json' \
  -d '{"data":"aGVsbG8=","privateKey":"<private-key>"}'

Checks a signature against data with the public key. A signature that simply does not match is a normal 200 answer with valid: false — not an error.

{
  "valid": true
}

copycurl -s -X POST $BASE/api/v0/cipher/rsa/verify \
  -H 'Content-Type: application/json' \
  -d '{"data":"aGVsbG8=","signature":"<signature>","publicKey":"<public-key>"}'

Encrypts a payload of any size for the holder of the matching RSA private key.

{
  "data": "b64-aes-gcm-cipher-text",
  "encryptedKey": "b64-rsa-wrapped-aes-key"
}

copycurl -s -X POST $BASE/api/v0/cipher/hybrid/encrypt \
  -H 'Content-Type: application/json' \
  -d "{\"data\":\"$(base64 -w0 report.pdf)\",\"publicKey\":\"<public-key>\"}"

Unwraps the AES key with the private key and decrypts the payload. The GCM tag is checked, so tampered data fails instead of decoding to garbage.

{
  "data": "b64-original-payload"
}

copycurl -s -X POST $BASE/api/v0/cipher/hybrid/decrypt \
  -H 'Content-Type: application/json' \
  -d '{"data":"<cipher>","encryptedKey":"<wrapped-key>","privateKey":"<private-key>"}'

Hashes an in-memory payload.

{
  "algorithm": "sha256",
  "hash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
  "bytes": 5
}

copycurl -s -X POST $BASE/api/v0/hash \
  -H 'Content-Type: application/json' \
  -d '{"algorithm":"sha256","data":"hello"}'

copycurl -s -X POST $BASE/api/v0/hash \
  -H 'Content-Type: application/json' \
  -d '{"algorithm":"blake3","data":"aGVsbG8=","encoding":"base64"}'

copycurl -s -X POST $BASE/api/v0/hash \
  -H 'Content-Type: application/json' \
  -d '{"algorithm":"hmac-sha256","data":"hello","key":"secret"}'

Hashes an uploaded file as multipart/form-data. The upload is streamed through the digest rather than buffered, and nothing is stored — this endpoint only computes, unlike uploaded files.

{
  "algorithm": "sha256",
  "hash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
  "bytes": 5,
  "name": "notes.txt"
}

copycurl -s -X POST $BASE/api/v0/hash/file \
  -F '[email protected]' \
  -F 'algorithm=blake3'

Recomputes the digest of data and compares it with the one you expect. The comparison is constant-time, so repeated guesses cannot be timed to recover a secret HMAC. A digest that does not match is a normal 200 with valid: false — not an error.

{
  "valid": true,
  "algorithm": "sha256",
  "expected": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
  "actual":   "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
}

copycurl -s -X POST $BASE/api/v0/hash/verify \
  -H 'Content-Type: application/json' \
  -d '{"algorithm":"sha256","data":"hello",
       "hash":"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"}'

Renders data as a QR code. The response is the image itself, so it can be saved straight to a file. Send Accept: application/json (or add ?json=true) to get a data: URL in JSON instead — that is the form to drop into an <img src>.

Content-Type: image/png
<the png bytes>

{
  "format": "png",
  "contentType": "image/png",
  "size": 512,
  "image": "data:image/png;base64,iVBORw0KGgo…"
}

copycurl -s -X POST $BASE/api/v0/qr/generate \
  -H 'Content-Type: application/json' \
  -d '{"data":"https://ss.serbekun.com","size":512}' -o qr.png

copycurl -s -X POST $BASE/api/v0/qr/generate \
  -H 'Content-Type: application/json' \
  -d '{"data":"https://ss.serbekun.com","format":"svg",
       "errorCorrection":"H","foreground":"#123456","background":"#00000000"}' -o qr.svg

copycurl -s -X POST $BASE/api/v0/qr/generate \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d '{"data":"https://ss.serbekun.com"}'

Reads the code out of an image — a screenshot, a photo, a downloaded png. Codes printed light-on-dark are read too. An image that simply holds no code is a 200 with found: false, not an error. SVG cannot be read; rasterise it first.

{
  "found": true,
  "text": "https://ss.serbekun.com",
  "format": "QR_CODE"
}

copycurl -s -X POST $BASE/api/v0/qr/read -F '[email protected]'

copycurl -s -X POST $BASE/api/v0/qr/read \
  -H 'Content-Type: image/png' --data-binary '@qr.png'

Writes a payload as base64, hex or url — the format is the one in the path. encoding says how to read the input, so binary can be handed in as hex or base64 rather than as text.

{
  "data": "Zm9vYmFy",
  "bytes": 6,
  "from": "utf8",
  "to": "base64"
}

copycurl -s -X POST $BASE/api/v0/encoding/base64/encode \
  -H 'Content-Type: application/json' \
  -d '{"data":"foobar"}'

copycurl -s -X POST $BASE/api/v0/encoding/hex/encode \
  -H 'Content-Type: application/json' \
  -d '{"data":"Zm9vYmFy","encoding":"base64"}'

copycurl -s -X POST $BASE/api/v0/encoding/url/encode \
  -H 'Content-Type: application/json' \
  -d '{"data":"a b+c","form":true}'

Reads a payload written as base64, hex or url. outputEncoding says how to write the result — it defaults to utf8, and bytes that are not valid UTF-8 are refused rather than mangled into �, so binary needs hex or base64 here. Decoding is forgiving about how the input was pasted: whitespace, lowercase, missing padding, a 0x prefix and : separators in hex, and the url-safe alphabet on the base64 route.

{
  "data": "foobar",
  "bytes": 6,
  "from": "base64",
  "to": "utf8"
}

copycurl -s -X POST $BASE/api/v0/encoding/base64/decode \
  -H 'Content-Type: application/json' \
  -d '{"data":"Zm9vYmFy"}'

copycurl -s -X POST $BASE/api/v0/encoding/base64/decode \
  -H 'Content-Type: application/json' \
  -d '{"data":"//79","outputEncoding":"hex"}'

The general form: name both sides. The six routes above are this one with a side pinned by the path.

{
  "data": "MZXW6YTBOI======",
  "bytes": 6,
  "from": "base64",
  "to": "base32"
}

copycurl -s -X POST $BASE/api/v0/encoding/convert \
  -H 'Content-Type: application/json' \
  -d '{"data":"Zm9vYmFy","from":"base64","to":"base32"}'

Generates UUIDs. v4 is 122 random bits and reveals nothing; v7 puts a millisecond timestamp in the leading 48 bits, so ids sort by creation time — far kinder to a database index, at the cost of telling anyone who reads one when it was made.

{
  "type": "uuid",
  "count": 2,
  "values": ["7f4b…", "0c19…"],
  "format": "canonical",
  "version": "v4",
  "bits": 122
}

copycurl -s "$BASE/api/v0/id/uuid?count=5&version=v7&format=compact"

Generates ULIDs — 128 bits, a millisecond timestamp then 80 random, written as 26 characters of Crockford base32 (no I, L, O or U, so one cannot be misread aloud). They sort by time as plain text, and ids made inside the same millisecond still ascend, because the random half is stepped rather than redrawn.

{
  "type": "ulid",
  "count": 1,
  "values": ["01JD3K9Q7WZ8XN4M2B6R0YFVTA"],
  "format": "canonical",
  "bits": 80
}

copycurl -s "$BASE/api/v0/id/ulid?count=10"

Random strings drawn from an alphabet — api keys, session tokens, invite codes. base58 drops the characters that look alike (0OIl) and is the one to pick if a person will ever read a token off a screen; base64url packs the most entropy per character into something still safe in a url.

{
  "type": "token",
  "count": 1,
  "values": ["nQ2rXk…"],
  "alphabet": "base62",
  "length": 32,
  "bits": 190
}

copycurl -s "$BASE/api/v0/random/token?length=24&alphabet=base58"

copycurl -s "$BASE/api/v0/random/token?length=6&alphabet=digits"

Raw randomness written however you need it — a key, a salt, an iv. The bytes are the same in every format; utf8 is refused, because random bytes are not text.

{
  "type": "bytes",
  "count": 1,
  "values": ["9f86d081884c7d65…"],
  "format": "hex",
  "length": 32,
  "bits": 256
}

copycurl -s "$BASE/api/v0/random/bytes?length=32&format=base64"

Every kind above in one round trip — each item takes exactly the parameters its own endpoint does. A body that is a single item on its own is accepted too, without the items array around it. The 1000 cap is on the whole call, not on each item.

{
  "items": [
    {"type": "uuid", "count": 2, "values": ["…", "…"], "format": "canonical", "version": "v7", "bits": 74},
    {"type": "token", "count": 1, "values": ["…"], "alphabet": "base58", "length": 20, "bits": 117}
  ]
}

copycurl -s -X POST $BASE/api/v0/id/batch \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"type":"uuid","count":2,"version":"v7"},
                {"type":"token","length":20,"alphabet":"base58"}]}'

Says whether the body is JSON, and where it stops being JSON if it is not. A document that does not parse is a 200 with valid: false — telling you which line the comma is missing from is the whole job, not a failure of it.

The document, exactly as it is. Anything at all — it does not have to be valid.

{"valid": true, "bytes": 16}

{
  "valid": false,
  "error": "Unexpected character ('}' (code 125)): expected a valid value",
  "line": 4,
  "column": 2,
  "bytes": 20
}

copycurl -s -X POST $BASE/api/v0/json/validate --data-binary @file.json

Re-writes the document with indentation, and answers with the document — not with JSON about the document. Sorting the keys is what makes two files comparable line by line.

The document.

{
  "a": 1,
  "b": [
    1,
    2
  ]
}

copycurl -s -X POST "$BASE/api/v0/json/format?indent=4&sort=true" \
  --data-binary @file.json

Strips every byte that is not part of the value, and answers with the document.

{"a":1,"b":[1,2]}

copycurl -s -X POST $BASE/api/v0/json/minify --data-binary @file.json

Pulls values out of the document. A JSON Pointer (RFC 6901) names one place and finds at most one value — and is the same syntax a patch uses, so a pointer that finds a value is the pointer that would change it. A JSONPath can wildcard, slice and filter, and finds as many as match. Finding nothing is a 200 with count: 0, since "is there anything here" is a fair question.

{
  "expression": "$..book[?(@.price < 10)].title",
  "syntax": "jsonpath",
  "count": 1,
  "matches": ["Moby Dick"],
  "paths": ["$['store']['book'][0]['title']"]
}

copycurl -s -X POST "$BASE/api/v0/json/query?pointer=/store/book/0/title" \
  --data-binary @file.json

copycurl -s -X POST "$BASE/api/v0/json/query" \
  --data-urlencode 'path=$..book[?(@.price < 10)].title' -G --data-binary @file.json

Answers with an RFC 6902 JSON Patch: the operations that turn from into to. Only add, remove and replace are emitted — move and copy are optional in the RFC and only ever shorten a patch. Numbers compare by value, so 1 and 1.0 are not a change. Arrays of the same length are compared element by element, so a change deep inside one element is one nested operation; when the lengths differ, a longest-common-subsequence match works out what was really inserted or dropped, so adding one element to the front of a thousand is one operation, not a thousand.

{
  "equal": false,
  "operations": 3,
  "patch": [
    {"op": "remove", "path": "/gone"},
    {"op": "replace", "path": "/a", "value": 2},
    {"op": "add", "path": "/list/1", "value": 9}
  ]
}

copycurl -s -X POST $BASE/api/v0/json/diff \
  -H 'Content-Type: application/json' \
  -d '{"from":{"a":1,"gone":true},"to":{"a":2}}'

Creates a short url pointing at url.

{
  "id": "aB3xY",
  "token": "8f14e45f-…"
}

copycurl -s -X POST $BASE/api/v0/short-url \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

Creates a short url and renders the short link as a QR code in one round trip — the pair to print on a poster, where the original url would be both unscannable and unreadable. Takes everything post /api/v0/qr/generate takes, plus the fields of a plain creation.

{
  "id": "aB3xY",
  "token": "8f14e45f-…",
  "shortUrl": "https://ss.serbekun.com/api/v0/short-url/aB3xY",
  "format": "png",
  "contentType": "image/png",
  "size": 512,
  "qr": "data:image/png;base64,iVBORw0KGgo…"
}

copycurl -s -X POST $BASE/api/v0/short-url/qr \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/a/very/long/path","size":640}'

Resolves a short url and redirects to the target. This is the link you share.

copycurl -sI $BASE/api/v0/short-url/aB3xY

Deletes a short url. The token may be passed as a query param or in the JSON body.

copycurl -s -X DELETE "$BASE/api/v0/short-url/aB3xY?token=<token>"

Creates a new link repository. Note the trailing slash — it is part of the route.

{
  "repositoryId": "3f1c…-uuid",
  "token": "1a2b…-uuid",
  "name": "my links",
  "createdAt": "2026-07-22T10:15:30Z"
}

copycurl -s -X POST $BASE/api/v0/repository/links/ \
  -H 'Content-Type: application/json' \
  -d '{"name":"my links"}'

Returns the repository with all of its links. The token is never echoed back.

{
  "repositoryId": "3f1c…-uuid",
  "name": "my links",
  "createdAt": "2026-07-22T10:15:30Z",
  "links": [
    {
      "uuid": "9d0e…-uuid",
      "url": "https://example.com",
      "name": "example",
      "description": ""
    }
  ]
}

copycurl -s "$BASE/api/v0/repository/links/<id>?token=<token>"

Deletes a repository together with all links inside it.

copycurl -s -X DELETE "$BASE/api/v0/repository/links/<id>?token=<token>"

Adds a link to the repository.

{
  "uuid": "9d0e…-uuid",
  "url": "https://example.com",
  "name": "example",
  "description": ""
}

copycurl -s -X POST "$BASE/api/v0/repository/links/<id>/links?token=<token>" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","name":"example"}'

Replaces the stored link with the values from the body.

copycurl -s -X PUT "$BASE/api/v0/repository/links/<id>/links/<uuid>?token=<token>" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.org"}'

Removes a single link from the repository.

copycurl -s -X DELETE "$BASE/api/v0/repository/links/<id>/links/<uuid>?token=<token>"

Uploads a single file as multipart/form-data.

{
  "uuid": "7c2d…-uuid",
  "token": "4e5f…-uuid",
  "name": "report.pdf",
  "expiredTime": 1785000000000
}

copycurl -s -X POST $BASE/api/v0/uploaded-files \
  -F '[email protected]' \
  -F 'name=report.pdf' \
  -F 'ttl=3600'

Returns the configured upload limit, so clients can reject oversized files before sending them.

{
  "megabytes": 100,
  "bytes": 104857600
}

copycurl -s $BASE/api/v0/uploaded-files/max-size

Metadata of one file. The token is never included in the response.

{
  "uuid": "7c2d…-uuid",
  "name": "report.pdf",
  "expiredTime": 1785000000000
}

copycurl -s "$BASE/api/v0/uploaded-files/<uuid>?token=<token>"

Streams the file content as application/octet-stream with a Content-Disposition attachment header.

copycurl -sOJ "$BASE/api/v0/uploaded-files/<uuid>/download?token=<token>"

Deletes the file and its metadata. The token may be a query param or a JSON body field.

copycurl -s -X DELETE "$BASE/api/v0/uploaded-files/<uuid>?token=<token>"

Listing every uploaded file is deliberately not allowed — the route exists but always refuses. Files are reachable only by uuid plus token.

{
  "error": "Listing all files is not allowed"
}

Creates a burn link. Returns the public id, the ready-to-share url, and the delete token (shown only here).

{
  "id": "aB3xY9kLmN",
  "token": "8f14e45f-…",
  "url": "https://ss.serbekun.com/b/aB3xY9kLmN",
  "expiredTime": 0,
  "devices": ["iphone"],
  "browsers": ["firefox"],
  "ipWhitelist": ["203.0.113.0/24"],
  "ipBlacklist": []
}

copycurl -s -X POST $BASE/api/v0/burn \
  -H 'Content-Type: application/json' \
  -d '{"text":"the secret","ttl":3600,"devices":["iphone"],"browsers":["firefox"],"ipWhitelist":["203.0.113.0/24"]}'

Serves the reveal page with a button. It never reveals or burns anything, so it is safe to open (and safe for preview crawlers to fetch). A blocked visitor and a missing link both receive the same 404.

copycurl -s "$BASE/b/aB3xY9kLmN"

The only call that burns: it returns the secret and permanently removes the record. A caller whose device, browser or IP is not allowed is answered with the same 404 as a missing link, and the secret is not burned.

{
  "text": "the secret"
}

copycurl -s -X POST "$BASE/api/v0/burn/aB3xY9kLmN/reveal"

Deletes a burn link early. The token may be passed as a query param or in the JSON body.

copycurl -s -X DELETE "$BASE/api/v0/burn/aB3xY9kLmN?token=<token>"

Returns the raw yt-dlp metadata JSON for a video.

copycurl -s "$BASE/api/v0/youtube/info?url=https://youtu.be/<id>"

Downloads the video on the server and returns the MP4 bytes (video/mp4).

copycurl -s -o video.mp4 "$BASE/api/v0/youtube/download?url=https://youtu.be/<id>"

Returns the caller's ip as the server sees it. Behind a proxy the value comes from CF-Connecting-IP, then X-Forwarded-For, then the socket address — good enough to show users their own ip, not for auth or rate limiting.

{
  "ip": "203.0.113.7"
}

copycurl -s $BASE/api/v0/network/ip

The index page listing every service.

The site favicon (ss_icon.svg).

Lists the files available in a category.

copycurl -s $BASE/static/v0/json

Returns one static file with the content type of its category.

copycurl -s $BASE/static/v0/html/api_docs.html