API
Overview
Every endpoint in the Savee Public API v1, grouped by what it returns.
Base URL: https://api.savee.com/v1/
Every endpoint is a GET. All of them except /v1/ping and /v1/openapi.json
need an Authorization: Bearer … header — either a personal
access token (sv_live_…) or an
OAuth access token (sv_at_…) obtained on a user's behalf.
| Endpoint | Returns | Scope |
|---|---|---|
/v1/ping | Health check | — |
/v1/openapi.json | This API's OpenAPI 3.1 document | — |
/v1/me | The authenticated user and their plan | profile:read |
/v1/saves | The caller's saves, newest first (paginated) | saves:read |
/v1/saves/{saveID} | One save, by id or short_id | saves:read |
/v1/feed | The caller's home feed (paginated) | saves:read |
/v1/boards | Every board the caller can see (not paginated) | boards:read |
/v1/boards/{boardID} | One board, by id or short_id | boards:read |
/v1/boards/{boardID}/saves | Saves on one board (paginated) | boards:read + saves:read |
/v1/search | Savee's public library (paginated) | search:read |
Scopes apply to OAuth tokens. A personal access token represents you rather than a third party, so it carries all of them.
System
Health check and the OpenAPI document.
User
The authenticated user's profile and plan.
Saves
Your saves, your feed, and a board's saves.
Boards
The boards you own, collaborate on, or share with a team.
Search
Savee's public library. Metered far more tightly than everything else.
Conventions
- Paginated responses wrap results in
{ data, next_cursor, has_more }. See pagination. - Errors always look like
{ "error": { "code", "message" } }. See errors. - Image URLs are AVIF by default; send
Avif-Fallback: 1for JPG. See image formats. - Identifiers (
idon saves, boards and users) are stable across renames — safe to store on your side. - Short ids. Saves and boards also carry a
short_id, equally stable and accepted anywhere theidis. A save'sshort_idis the segment in its savee.com URL, sohttps://savee.com/i/997d6DW/resolves withGET /v1/saves/997d6DW. The two forms are told apart by shape — anidis 24 hex characters, ashort_idis 7 — so there's nothing to disambiguate.