30817:bud-blob-pinning

BUD: Blob pinning

Lets a client ask a Blossom server to keep a blob for itself or for other pubkeys, pin an already stored blob by its hash, and check its own pin.

Russell

published
2026-10-29
revised
2026-11-02

draft optional

A pin is a pubkey's request that a server keep a blob. This BUD lets a client pin a blob for itself or for other pubkeys, pin a blob the server already stores without uploading it, and read its own pin. It also lets a server serve a blob only to the pubkeys that pin it. It adds the pin verb to BUD-11.

PUT /upload and PUT /mirror

The upload token (BUD-11) of PUT /upload (BUD-02) and PUT /mirror (BUD-04) MAY include p tags, each naming a pubkey to pin the blob for.

  • Without p tags, the request pins the blob for the signer.
  • With p tags, it pins the blob for each p pubkey, and not for the signer.
  • Without a token, it pins the blob for no one.
  • If the server refuses one of the p pubkeys, it rejects the request with 403 Forbidden.

HEAD /upload (BUD-06) accepts the same p tags and answers as PUT /upload would.

{
  "kind": 24242,
  "pubkey": "<one-time pubkey>",
  "created_at": 1772019044,
  "tags": [
    ["t", "upload"],
    ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
    ["p", "<pubkey to pin for>"],
    ["expiration", "1772019344"]
  ],
  "content": "Upload Blob",
  "sig": "<signature>"
}

PUT /pin/sha256 - Pin Blob

Pins a blob the server already stores. The request has no body. The token MUST have t set to pin and an x tag matching <sha256>. It MAY include p tags, with the same meaning as on upload.

Status Code Meaning
200 OK The blob is pinned. The body contains its Blob Descriptor.
401 Unauthorized Authorization is missing or invalid. See BUD-11.
403 Forbidden The server refuses one of the p pubkeys.
404 Not Found The server does not store the blob.

GET /pin/sha256 - Get Pin

Returns the signer's own pin on a blob. The token MUST have t set to pin and an x tag matching <sha256>.

{
  "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
  "pinned": 1772019044
}

pinned is the unix timestamp at which the pin was created. Pinning the blob again does not change it. The response never reveals other pins.

Status Code Meaning
200 OK The signer pins the blob. The body describes the pin.
401 Unauthorized Authorization is missing or invalid. See BUD-11.
404 Not Found The signer does not pin the blob.

DELETE /sha256 - Delete Blob

DELETE /<sha256> (BUD-12) removes the signer's pin and no other, so a pubkey that does not pin a blob cannot delete it. When the last pin is removed, the server MAY delete the blob.

Private server

A server MAY serve a blob only to the pubkeys that pin it, and act toward any other pubkey as if it did not store the blob. Clients then request blobs with a get token (BUD-11).

Discussion

Connect a key to comment.