{"id":"cb268c4fd3f215391a6fd75ee7c23e0df95450bc13ab69cf6fedaaddce6fb47d","pubkey":"1336a17e161d0e8af2b68ee95ad2a479fc38bef96a17d6127ea02a40d28dd97e","created_at":1775492308,"kind":30817,"tags":[["d","bud-12"],["title","BUD-12: Blob management endpoints"],["summary","Defines the management endpoints: listing what a pubkey uploaded, and deleting a blob by its hash."],["s","draft"],["t","blossom"],["t","bud"],["alt","A specification: BUD-12: Blob management endpoints"],["client","openspecs-import"],["published_at","1775492308"],["proxy","https://github.com/hzrd149/blossom/blob/b5bd2801d1763aa635fc8fea7a76597e0eb18990/buds/12.md","web"],["x","0016eeb43ab7654e0b1c97088ade5b06771702a913887e4f01e242a42553780f"]],"content":"# BUD-12\n\n## Blob management endpoints\n\n`draft` `optional`\n\n_All pubkeys MUST be in hex format_\n\nDefines the `/list/<pubkey>` and `DELETE /<sha256>` endpoints.\n\nThe [Blob Descriptor](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95cryxk74nh#blob-descriptor) type is defined in [BUD-02](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95cryxk74nh).\n\n## GET /list/pubkey - List Blobs (Unrecommended)\n\n**Note:** The `/list` endpoint is optional and unrecommended. It is not necessary for all servers to implement the `/list` endpoint. Servers MAY implement this endpoint, but are not required to do so.\n\nThe `/list/<pubkey>` endpoint MUST return a JSON array of [Blob Descriptor](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95cryxk74nh#blob-descriptor) objects that were uploaded by the specified pubkey.\n\nThe endpoint MUST support `cursor` and `limit` query parameters for cursor based pagination. The `cursor` parameter MUST be the `sha256` hash of the last blob in the previous page, or omitted to request the first page. The `limit` parameter specifies the maximum number of results to return. The returned array of blob descriptors MUST be sorted by the `uploaded` date in descending order and MUST NOT include the blob at the cursor.\n\nThe endpoint MAY support `since` and `until` query parameters to filter the list of blobs by their `uploaded` date. These parameters are deprecated for pagination purposes as they do not preserve server resources.\n\n### Status codes\n\nServers SHOULD use the following status codes for `GET /list/<pubkey>` responses:\n\n| Status Code               | Meaning                                                                                                                   |\n| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| `200 OK`                  | The list request succeeded and the response body contains an array of [Blob Descriptor](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95cryxk74nh#blob-descriptor) objects. |\n| `400 Bad Request`         | The query parameters are malformed.                                                                                       |\n| `401 Unauthorized`        | Authorization is required and missing or invalid. See [BUD-11](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95cnzuvmwmm#endpoint-authorization-requirements).              |\n| `402 Payment Required`    | Payment is required before listing blobs. See [BUD-07](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95crwt8m678).                                                          |\n| `403 Forbidden`           | The request is understood but not allowed by server policy.                                                               |\n| `429 Too Many Requests`   | The client has exceeded a rate limit or quota.                                                                            |\n| `503 Service Unavailable` | The listing service is temporarily unavailable.                                                                           |\n\nIf included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.\n\n## DELETE /sha256 - Delete Blob\n\nServers MUST accept `DELETE` requests to the `/<sha256>` endpoint.\n\n### Status codes\n\nServers SHOULD use the following status codes for `DELETE /<sha256>` responses:\n\n| Status Code               | Meaning                                                                                                      |\n| ------------------------- | ------------------------------------------------------------------------------------------------------------ |\n| `200 OK`                  | The blob was deleted successfully and the response may include a body.                                       |\n| `204 No Content`          | The blob was deleted successfully and the response body is empty.                                            |\n| `401 Unauthorized`        | Authorization is required and missing or invalid. See [BUD-11](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95cnzuvmwmm#endpoint-authorization-requirements). |\n| `402 Payment Required`    | Payment is required before deleting the blob. See [BUD-07](nostr:naddr1qvzqqqrcvypzqyek59lpv8gw3tetdrhfttf2g70u8zl0j6sh6cf8agp2grfgmkt7qqrxyaty95crwt8m678).                                         |\n| `403 Forbidden`           | The request is understood but not allowed by server policy.                                                  |\n| `404 Not Found`           | The blob does not exist or is not available for deletion.                                                    |\n| `429 Too Many Requests`   | The client has exceeded a rate limit or quota.                                                               |\n| `503 Service Unavailable` | The deletion service is temporarily unavailable.                                                             |\n\nIf included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.\n\nMultiple `x` tags in the authorization token MUST NOT be interpreted as the user requesting to delete multiple blobs.\n","sig":"99c53ec45799ec1d4d72d43e4ccfae00929fad447ff4432f7acd058db6aae701f496fbd396e7f4a80224b08aa4bae00ac99bacef57ffdbd88fb322a3ddbd4cee"}