{"openapi":"3.1.0","info":{"title":"Savee Public API","version":"1.0.0","description":"Read-only REST API exposing a paid Savee user’s own saves, boards, and home feed.\nAuthenticate with a personal access token (`sv_live_…`) generated in your Savee settings.\n\n**Image format** — `media.thumbnail` and `media.original` for image saves are AVIF by default. Clients that cannot decode AVIF should send the request header `Avif-Fallback: 1` to receive JPG URLs instead. Video originals are always MP4."},"servers":[{"url":"https://api.savee.com"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sv_live_…","description":"Personal access token in the form `sv_live_<24 chars>`. Generate one at https://savee.com/developer/."}},"schemas":{"Me":{"type":"object","properties":{"id":{"type":"string","description":"User identifier. Stable across renames."},"username":{"type":"string","description":"Current username. May change if the user renames."},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"avatar_url":{"type":"string","format":"uri"},"plan":{"type":"object","properties":{"active":{"type":"boolean"},"tiers":{"type":"array","items":{"type":"string"}}},"required":["active","tiers"]}},"required":["id","username","name","url","avatar_url","plan"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"SaveMedia":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"]},"width":{"type":"integer","minimum":0},"height":{"type":"integer","minimum":0},"thumbnail":{"type":"string","format":"uri","description":"Grid-sized preview (~420px wide). AVIF by default; clients that cannot decode AVIF should send `Avif-Fallback: 1` to receive JPG. Applies to both image and video assets (videos return a JPG/AVIF poster frame)."},"original":{"type":"string","format":"uri","description":"Full-quality asset. Image: AVIF by default (JPG with `Avif-Fallback: 1`). Video: MP4."}},"required":["type","width","height","thumbnail","original"]},"User":{"type":"object","properties":{"id":{"type":"string","description":"User identifier. Stable across renames; safe to store as a foreign key on the caller’s side."},"username":{"type":"string","description":"Current username. May change if the user renames."},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"avatar_url":{"type":"string","format":"uri"}},"required":["id","username","name","url","avatar_url"],"description":"The user who created this save. Omitted on /v1/saves (the caller is implicitly the author); present on /v1/feed and /v1/boards/{id}/saves where the author may differ from the caller."},"Save":{"type":"object","properties":{"id":{"type":"string","description":"Save identifier. Stable across renames; safe to store as a foreign key on the caller’s side."},"url":{"type":"string","format":"uri","description":"Canonical page on savee.com for this save."},"name":{"type":"string"},"source_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"is_private":{"type":"boolean"},"total_saves":{"type":"integer","minimum":0},"media":{"$ref":"#/components/schemas/SaveMedia"},"user":{"$ref":"#/components/schemas/User"}},"required":["id","url","name","source_url","created_at","is_private","total_saves","media"]},"SavesPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Save"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"]},"Board":{"type":"object","properties":{"id":{"type":"string","description":"Board identifier. Stable across renames and slug changes; safe to store as a foreign key on the caller’s side."},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri","description":"Canonical page on savee.com for this board (uses the current slug)."},"is_private":{"type":"boolean"},"saves_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"og_image":{"type":["string","null"],"format":"uri"},"ownership_type":{"type":"string","enum":["team","user"],"description":"`user` if the board belongs to a person (the caller, or someone who's added the caller as a collaborator); `team` if it belongs to a Savee Teams workspace the caller is a member of."}},"required":["id","name","slug","url","is_private","saves_count","created_at","og_image","ownership_type"]},"BoardsList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Board"}}},"required":["data"]}},"parameters":{}},"paths":{"/v1/ping":{"get":{"summary":"Health check","tags":["System"],"responses":{"200":{"description":"Server is up.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}}}}}}},"/v1/me":{"get":{"summary":"Get the authenticated user","tags":["User"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Authenticated but the user has no active subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The Public API is not enabled for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/saves":{"get":{"summary":"List the authenticated user's saves","description":"Newest first. Includes private saves (it's the caller's own data). The `user` field on each save is omitted because the caller is implicitly the owner.","tags":["Saves"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size (default 30, max 100).","example":30},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned in `next_cursor` from the previous page."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of saves.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavesPage"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Authenticated but the user has no active subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The Public API is not enabled for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feed":{"get":{"summary":"List the authenticated user’s home feed","description":"Saves from users this user follows (and platform-curated content), newest first. Each save includes a `user` object describing the saver.","tags":["Saves"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size (default 30, max 100).","example":30},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned in `next_cursor` from the previous page."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of feed saves.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavesPage"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Authenticated but the user has no active subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The Public API is not enabled for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/boards":{"get":{"summary":"List the authenticated user's boards","description":"Returns every board the caller can see in a single response (not paginated): personal boards they own, boards they collaborate on, and boards from any Savee Teams workspace they're a member of. Use the `ownership_type` field on each board to tell user-owned boards apart from team boards. The order follows the caller's chosen boards-sort preference on savee.com.","tags":["Boards"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"All boards visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardsList"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Authenticated but the user has no active subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The Public API is not enabled for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/boards/{boardID}/saves":{"get":{"summary":"List saves on a specific board","description":"`boardID` is the board `id` returned by `/v1/boards`. Accessible by any user with a role on the board (owner, admin, editor, viewer) and by team members for team-owned boards. Returns 404 when the board does not exist or the caller has no role on it — the API does not confirm whether someone else’s board exists.","tags":["Boards","Saves"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The board id (the `id` returned by `/v1/boards`)."},"required":true,"description":"The board id (the `id` returned by `/v1/boards`).","name":"boardID","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size (default 30, max 100).","example":30},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned in `next_cursor` from the previous page."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of saves on the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavesPage"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Authenticated but the user has no active subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The Public API is not enabled for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Board not found or not accessible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}