API Documentation v1

Simple HTTP API for storing and retrieving content.

Read Content

GET /{key}

Retrieve stored content by its key. The content is returned as-is in the response body with the original content type.

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.

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`.
`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 if not specified.
`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.

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	The modification key returned 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.

403 Forbidden

Invalid or missing modification key.

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"}'

Retrieve content

curl http://localhost:8080/aB3xK9q

Fork of lucko/bytebin