BUD-02

Blob upload and management

draft optional

All pubkeys MUST be in hex format

Defines the /upload and DELETE /<sha256> endpoints

Blob Descriptor

A blob descriptor is a JSON object containing url, sha256, size, type, and uploaded fields

url A publicly accessible URL to the BUD-01 GET /<sha256> endpoint with a file extension
sha256 The sha256 hash of the blob
size The size of the blob in bytes
type The MIME type of the blob (falling back to application/octet-stream if unknown)
uploaded The unix timestamp of when the blob was uploaded to the server

Servers MUST include a file extension in the URL in the url field to allow clients to easily embed the URL in social posts or other content

Servers MAY include additional fields in the descriptor like magnet, infohash, or ipfs depending on other protocols they support.

Example:

{
  "url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
  "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
  "size": 184292,
  "type": "application/pdf",
  "uploaded": 1725105921
}

PUT /upload - Upload Blob

The PUT /upload endpoint MUST accept binary data in the request body.
The server MUST NOT modify the blob in any way and MUST compute the sha256 hash over the exact bytes received. This requirement ensures that users can re-upload blobs to other servers without discrepancies.

Clients SHOULD include Content-Type and Content-Length headers specifying the MIME type and size of the data. Clients MAY provide an X-SHA-256 header containing the lowercase hex-encoded sha256 of the request body. A server MAY use this value to enforce rejection policies or perform authorization checks prior to persisting the blob.

On success, the endpoint MUST respond with a 2xx status code with a Blob Descriptor in the response body.
On failure, the endpoint MUST return an appropriate 4xx status code and an error message explaining the reason for the rejection.

File extension normalization (Optional)

When storing blobs, servers MAY normalise the file extension to a standard format (e.g. .pdf, .png, etc.) based on the MIME type of the blob. This can be especially useful when the GET /<sha256> endpoint is redirected to an external URL (see the proxying and redirection section from BUD-01), as external servers may rely on the file extension to serve the blob correctly.

Upload Authorization (Optional)

Servers MAY require authorization when uploading blobs, as defined by BUD-11.

DELETE /sha256 - Delete Blob

Servers MUST accept DELETE requests to the /<sha256> endpoint

Servers MAY reject a delete request for any reason and SHOULD respond with the appropriate HTTP 4xx status code and an error message explaining the reason for the rejection

Delete Authorization

Servers MAY require authorization when deleting blobs as defined by BUD-11. Multiple x tags in the authorization token MUST NOT be interpreted as the user requesting to delete multiple blobs.

3.2 KiB Raw Permalink Blame History