BUD-10: Blob search

README.md

@@ -25,6 +25,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi
 - [BUD-06: Upload requirements](./buds/06.md)
 - [BUD-08: Nostr File Metadata Tags](./buds/08.md)
 - [BUD-09: Blob Report](./buds/09.md)
+- [BUD-10: Blob Search](./buds/10.md)
 
 ## Endpoints
 
@@ -47,6 +48,7 @@ Blossom Servers expose a few endpoints for managing blobs
 - `PUT /media` [BUD-05](./buds/05.md#put-media)
   - `Authentication`: Signed [nostr event](./buds/05.md#upload-authorization)
 - `PUT /report` [BUD-09](./buds/09.md)
+- `GET /search` [BUD-10](./buds/10.md)
 
 ## Event kinds
 

buds/10.md

@@ -0,0 +1,39 @@
+# BUD-10
+
+## Blob Search
+
+`draft` `optional`
+
+This BUD defines a new endpoint that let users to query blobs based on their metadata or meaning.
+
+### GET /search - searching for a blob
+
+#### Request
+
+This request can contain the following query params:
+
+1. Any fields defined in [BUD-02](./02.md) and [BUD-08](./08.md): `https://example.com/search?<field_name_as_per_08_or_02>=<value>`. This will check for an exact match. For values like timestamp or size that may need to be queried by range, value can be a strict value or a 2 index array that represents the range.
+
+2. `search`: `https://example.com/search?search="Happy pigs on a farm"`. This can be queried on blob description or based on blob content semantically.
+
+3. `limit`: number of results to return.
+
+4. `offset`: number of items to skip (for offset-based model)
+
+5. `cursor`: opaque pagination token (for cursor-based model)
+
+Expect `offset` and `cursor`, other params can be used together to make more complex queries.
+
+#### Response
+
+Response example:
+
+```jsonc
+{
+  "results": ["0x123456789abcdef", /* Blob sha256's that can be queried for actual blob or description only... */],
+  "limit": 20,
+  "offset": 40,            // for offset-based
+  "next_cursor": "...",    // for cursor-based
+  "total": 1234            // optional
+}
+```