{"components":{"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Malformed request (for example, invalid JSON)"},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The API key lacks the required scope"},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The requested resource does not exist"},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication failed"},"ValidationError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Request validation failed; error.details lists the offending fields and valid values"}},"schemas":{"Author":{"nullable":true,"properties":{"avatarUrl":{"nullable":true,"type":"string"},"displayName":{"nullable":true,"type":"string"},"profileUrl":{"nullable":true,"type":"string"},"username":{"type":"string"}},"required":["username"],"type":"object"},"Bookmark":{"additionalProperties":true,"properties":{"author":{"$ref":"#/components/schemas/Author"},"capturedAt":{"format":"date-time","type":"string"},"content":{"description":"Portable Text blocks holding the full body","items":{"type":"object"},"type":"array"},"contentCreatedAt":{"format":"date-time","nullable":true,"type":"string"},"contentType":{"description":"One of: image, post, video, comment, article, snippet","type":"string"},"deletedAt":{"format":"date-time","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"isFavorite":{"type":"boolean"},"media":{"items":{"$ref":"#/components/schemas/Media"},"type":"array"},"note":{"nullable":true,"type":"string"},"platform":{"description":"Platform id. X/Twitter is \"twitter\".","enum":["instagram","reddit","tiktok","twitter","web","youtube"],"type":"string"},"platformId":{"type":"string"},"tags":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array"},"title":{"description":"Present on titled content such as X articles","nullable":true,"type":"string"},"url":{"format":"uri","type":"string"}},"required":["id","platform","contentType","url","tags","content","media","capturedAt"],"type":"object"},"ErrorEnvelope":{"properties":{"error":{"properties":{"code":{"description":"Stable machine-readable code, e.g. validation_error, not_found, forbidden","type":"string"},"details":{},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"requestId":{"type":"string"}},"required":["error"],"type":"object"},"Media":{"properties":{"altText":{"nullable":true,"type":"string"},"duration":{"nullable":true,"type":"number"},"height":{"nullable":true,"type":"integer"},"ref":{"description":"Stable media ref usable with the media preview","type":"string"},"storedUrl":{"nullable":true,"type":"string"},"type":{"enum":["image","video"],"type":"string"},"url":{"type":"string"},"width":{"nullable":true,"type":"integer"}},"required":["ref","type","url"],"type":"object"},"BookmarkFilters":{"properties":{"authorMode":{"default":"include","enum":["include","exclude"],"type":"string"},"authors":{"items":{"description":"An author username (\"naval\"), optionally platform-scoped (\"twitter:naval\")","type":"string"},"type":"array"},"contentTypeMode":{"default":"include","enum":["include","exclude"],"type":"string"},"contentTypes":{"items":{"description":"A content type (\"article\"), optionally platform-scoped (\"twitter:article\"). Valid types: image, post, video, comment, article, snippet","type":"string"},"type":"array"},"favorite":{"items":{"enum":["favorite","not-favorite"],"type":"string"},"type":"array"},"media":{"items":{"enum":["image","video","any-media","text-only"],"type":"string"},"type":"array"},"mediaMode":{"default":"include","enum":["include","exclude"],"type":"string"},"note":{"items":{"enum":["has-note","no-note"],"type":"string"},"type":"array"},"platformMode":{"default":"include","enum":["include","exclude"],"type":"string"},"platforms":{"items":{"description":"Platform id. X/Twitter is \"twitter\".","enum":["instagram","reddit","tiktok","twitter","web","youtube"],"type":"string"},"type":"array"},"tagMode":{"default":"include_any","enum":["include_any","include_all","exclude_any","exclude_all"],"type":"string"},"tags":{"items":{"description":"A tag name from /v1/tags","type":"string"},"type":"array"}},"type":"object"},"BookmarkPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Bookmark"},"type":"array"},"nextCursor":{"nullable":true,"type":"string"}},"required":["items","nextCursor"],"type":"object"},"Collection":{"properties":{"color":{"type":"string"},"filters":{"additionalProperties":true,"type":"object"},"icon":{"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name","filters","color","icon"],"type":"object"},"Tag":{"properties":{"color":{"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name","color"],"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"Stashr OAuth access token or API key","description":"Use an OAuth access token audience-bound to /v1, or a scoped stashr_ API key for non-interactive clients.","scheme":"bearer","type":"http"}}},"info":{"description":"Agent- and CLI-focused access to a user's Stashr library.","title":"Stashr API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/v1/bookmarks":{"get":{"description":"Browse bookmarks in reverse capture order using structured filters.","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"state","schema":{"default":"active","enum":["active","archived","all"],"type":"string"}},{"explode":true,"in":"query","name":"authors","schema":{"items":{"description":"An author username (\"naval\"), optionally platform-scoped (\"twitter:naval\")","type":"string"},"type":"array"},"style":"form"},{"explode":true,"in":"query","name":"contentTypes","schema":{"items":{"description":"A content type (\"article\"), optionally platform-scoped (\"twitter:article\"). Valid types: image, post, video, comment, article, snippet","type":"string"},"type":"array"},"style":"form"},{"explode":true,"in":"query","name":"favorite","schema":{"items":{"enum":["favorite","not-favorite"],"type":"string"},"type":"array"},"style":"form"},{"explode":true,"in":"query","name":"media","schema":{"items":{"enum":["image","video","any-media","text-only"],"type":"string"},"type":"array"},"style":"form"},{"explode":true,"in":"query","name":"note","schema":{"items":{"enum":["has-note","no-note"],"type":"string"},"type":"array"},"style":"form"},{"explode":true,"in":"query","name":"platforms","schema":{"items":{"description":"Platform id. X/Twitter is \"twitter\".","enum":["instagram","reddit","tiktok","twitter","web","youtube"],"type":"string"},"type":"array"},"style":"form"},{"explode":true,"in":"query","name":"tags","schema":{"items":{"description":"A tag name from /v1/tags","type":"string"},"type":"array"},"style":"form"},{"in":"query","name":"authorMode","schema":{"default":"include","enum":["include","exclude"],"type":"string"}},{"in":"query","name":"contentTypeMode","schema":{"default":"include","enum":["include","exclude"],"type":"string"}},{"in":"query","name":"mediaMode","schema":{"default":"include","enum":["include","exclude"],"type":"string"}},{"in":"query","name":"platformMode","schema":{"default":"include","enum":["include","exclude"],"type":"string"}},{"in":"query","name":"tagMode","schema":{"default":"include_any","enum":["include_any","include_all","exclude_any","exclude_all"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/BookmarkPage"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"List bookmarks"},"post":{"description":"Fetch a public URL and save its metadata. Repeated saves return the existing bookmark.","requestBody":{"content":{"application/json":{"schema":{"properties":{"url":{"format":"uri","type":"string"}},"required":["url"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"required":["data"],"type":"object"}}},"description":"Existing bookmark"},"201":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"required":["data"],"type":"object"}}},"description":"Bookmark created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"An active subscription or trial is required"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Save a URL"}},"/v1/bookmarks/archive":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"items":{"format":"uuid","type":"string"},"type":"array"}},"required":["ids"],"type":"object"}}},"required":true},"description":"Reversibly archive bookmarks (soft delete). Requires the write scope; restore undoes it.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Archive bookmarks"}},"/v1/bookmarks/restore":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"items":{"format":"uuid","type":"string"},"type":"array"}},"required":["ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Restore bookmarks"}},"/v1/bookmarks/{bookmarkId}":{"get":{"parameters":[{"in":"path","name":"bookmarkId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Bookmark"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Get a bookmark"},"patch":{"parameters":[{"in":"path","name":"bookmarkId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"isFavorite":{"type":"boolean"},"note":{"nullable":true,"type":"string"},"tags":{"properties":{"add":{"items":{"type":"string"},"type":"array"},"remove":{"items":{"type":"string"},"type":"array"},"set":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Update a bookmark"}},"/v1/bookmarks/{bookmarkId}/media":{"get":{"description":"Return an ownership-scoped, maximum-768px JPEG preview for one stored bookmark image.","parameters":[{"in":"path","name":"bookmarkId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"ref","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"image/jpeg":{"schema":{"format":"binary","type":"string"}}},"description":"Bounded image preview"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Get an image preview"}},"/v1/collections":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Collection"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"description":"Returns every collection; this endpoint is unpaginated.","summary":"List collections"},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"color":{"type":"string"},"filters":{"additionalProperties":true,"type":"object"},"icon":{"type":"string"},"name":{"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Create a collection"}},"/v1/collections/{collectionId}":{"delete":{"parameters":[{"in":"path","name":"collectionId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"confirm","required":true,"schema":{"enum":["true"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Delete a collection"},"patch":{"parameters":[{"in":"path","name":"collectionId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Update a collection"}},"/v1/me":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Get the authenticated account"}},"/v1/search":{"post":{"description":"Search whole bookmarks or rank individual images by their AI vision captions. Image-ranked pages include tileOrder entries with bookmarkId, ref, and caption.","requestBody":{"content":{"application/json":{"schema":{"properties":{"cursor":{"description":"nextCursor value from the previous page of the same search","type":"string"},"filters":{"$ref":"#/components/schemas/BookmarkFilters"},"limit":{"maximum":100,"minimum":1,"type":"integer"},"query":{"type":"string"},"rankMode":{"default":"post","enum":["post","image"],"type":"string"}},"required":["query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/BookmarkPage"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"summary":"Search bookmarks"}},"/v1/tags":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"}},"description":"Returns every tag; this endpoint is unpaginated.","summary":"List tags"}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://stashr.me"}]}