API Documentation v1

Simple HTTP API for storing and retrieving content.

Read Content

GET /{key}

Retrieve stored content by its key. Always returns the raw stored content directly.

Response Headers

Header	Description
`Content-Type`	The MIME type of the stored content.
`Content-Encoding`	The encoding used (e.g. `gzip`). Bytebin will decompress gzip automatically if the client doesn't support it.
`Last-Modified`	Timestamp of when the content was last modified.
`Bytebin-Reads-Remaining`	Only present if a read limit was set. Shows remaining reads before auto-deletion.

200 OK

Content returned in body.

404 Not Found

Key does not exist, content has expired, or max reads exceeded.

GET /view/{key}

View stored content in the browser with syntax highlighting for code, inline display for images/video/audio, and download options for binary files. Fetches content from GET /{key} client-side.

200 OK

HTML viewer page returned.

404 Not Found

Invalid key format.

Health Check

GET /health

Simple health check endpoint for load balancers and monitoring. Returns a JSON status object.

200 OK

{"status": "ok"}

Write Content

POST /post

Upload new content. The request body is stored and a unique key is returned.

Request Headers

Header	Required	Description
`Content-Type`	Recommended	MIME type of the content. Defaults to `text/plain`.
`User-Agent`	Recommended	Identifies the client. Used for per-agent expiry overrides when configured.
`Content-Encoding`	No	Encoding applied to the body (e.g. `gzip`). If omitted, bytebin will compress server-side.
`Bytebin-Expiry`	No	Custom expiry time in minutes. Defaults to 30 days for text content, 7 days for binary files. Binary file uploads are capped at a maximum of 14 days.
`Bytebin-Max-Reads`	No	Maximum number of times the content can be read. Content is auto-deleted after this limit.
`Allow-Modification`	No	Set to `true` to allow updating the content via PUT. Returns a `Modification-Key` response header.

201 Created

            // Response body

            {"key": "aB3xK9q"}

Response Headers

Header	Description
`Location`	The key (or full URL for PUT requests) to access the content.
`Modification-Key`	Only present if `Allow-Modification: true` was set. Required for subsequent PUT updates.

Tip: For best performance, compress content client-side with gzip and include the Content-Encoding: gzip header. Bytebin compresses server-side when no encoding is specified, but client-side compression reduces upload time.

File expiry limits: Binary file uploads (non-text content types like images, video, audio, archives, etc.) default to 7-day expiry and are capped at a 14-day maximum. Text content types (text/*, application/json, application/xml, etc.) keep the standard 30-day default with no cap.

Update Content

PUT /{key}

Update existing content. Only works if the content was created with Allow-Modification: true.

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token: `Bearer <modification-key>`. The modification key is returned in the `Modification-Key` header when the content was originally created.
`Content-Type`	Recommended	MIME type of the updated content.
`Content-Encoding`	No	Encoding applied to the body.

200 OK

Content updated successfully.

404 Not Found

Key does not exist.

401 Unauthorized

Missing Authorization header or wrong scheme (must be Bearer).

403 Forbidden

Invalid modification key, or content was not created with Allow-Modification: true.

Examples

Upload text with 1-hour expiry

        curl -X POST http://localhost:8080/post \

          -H "Content-Type: text/plain" \

          -H "Bytebin-Expiry: 60" \

          -d "Hello, world!"

Upload with a 5-read limit

        curl -X POST http://localhost:8080/post \

          -H "Content-Type: text/plain" \

          -H "Bytebin-Max-Reads: 5" \

          -d "This message self-destructs after 5 reads."

Upload modifiable content

        curl -X POST http://localhost:8080/post \

          -H "Content-Type: application/json" \

          -H "Allow-Modification: true" \

          -d '{"status": "draft"}'

Upload a binary file

        curl -X POST http://localhost:8080/post \

          -H "Content-Type: image/png" \

          --data-binary @screenshot.png

Retrieve content

curl http://localhost:8080/aB3xK9q

Update modifiable content

        curl -X PUT http://localhost:8080/aB3xK9q \

          -H "Authorization: Bearer <modification-key>" \

          -H "Content-Type: application/json" \

          -d '{"status": "published"}'

View content in browser

        # Open in browser for syntax-highlighted viewer

        http://localhost:8080/view/aB3xK9q

Health check

curl http://localhost:8080/health