Quick start

This walks through a personal access token, which is what you want when you're building something for yourself.

1. Generate a token

Go to Savee → Settings → Developers and, under API Access, click Generate token. Copy the raw sv_live_… value immediately — Savee stores only a hash, so the raw value is shown exactly once.

Treat it like a password: don't commit it, don't paste it into client-side code, rotate it if it leaks.

2. Make a request

curl https://api.savee.com/v1/me \
  -H "Authorization: Bearer sv_live_…"

Response:

{
	"id": "63e1a4c2d242ec00094007f1",
	"username": "you",
	"name": "Your Name",
	"url": "https://savee.com/you/",
	"avatar_url": "https://dm.savee.com/user-avatar/original/…jpg",
	"plan": { "active": true, "tiers": ["pro"] }
}

/v1/me is the cheapest way to check that a token works.

3. List your saves

curl 'https://api.savee.com/v1/saves?limit=5' \
  -H "Authorization: Bearer sv_live_…"

Each save includes a stable id, a short_id, the canonical url on savee.com, the source_url the user originally saved from, created_at, is_private, total_saves (how many users on the platform have saved this asset), the dominant colors, and a media block with the image / video URLs.

4. Look up one save

Every save has two identifiers, and both work anywhere a saveID is accepted:

• id — 67aada20d242ec0009400825, 24 hex characters.
• short_id — 997d6DW, 7 characters. This is the segment in the save's savee.com URL: https://savee.com/i/997d6DW/.

So a link someone pasted you becomes an API call directly, with no lookup step in between:

curl https://api.savee.com/v1/saves/997d6DW \
  -H "Authorization: Bearer sv_live_…"

{
	"data": {
		"id": "67aada20d242ec0009400825",
		"short_id": "997d6DW",
		"url": "https://savee.com/i/997d6DW/",
		"name": "Brutalist poster",
		"source_url": "https://example.com/poster",
		"user": { "username": "aliceb", "…": "…" },
		"media": { "…": "…" }
	}
}

You can read your own saves — private ones included — and any public save on Savee. A save that exists but isn't visible to you returns 404, not 403: the API doesn't confirm whether someone else's private save exists.

Boards work the same way — /v1/boards/{boardID} takes either the board's id or its short_id.

Image formats

media.thumbnail and media.original are AVIF by default for image saves. That's fine in browsers, and a common surprise everywhere else — plenty of server-side image libraries still can't decode it.

If your client can't handle AVIF, send Avif-Fallback: 1 and the same fields come back as JPG URLs:

curl 'https://api.savee.com/v1/saves?limit=5' \
  -H "Authorization: Bearer sv_live_…" \
  -H "Avif-Fallback: 1"

The header affects URLs only — it doesn't change which saves are returned. Video saves are unaffected: media.original is always MP4, and media.thumbnail is a poster frame that follows the same AVIF/JPG rule.

Pagination

The save-listing endpoints (/v1/saves, /v1/feed, /v1/boards/{id}/saves) take limit (default 30, max 100) and cursor. The response includes next_cursor and has_more; pass next_cursor back as the next page's cursor until has_more is false.

curl 'https://api.savee.com/v1/saves?limit=50&cursor=eyJjIjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpIjoiNjdhYWRhMjAifQ' \
  -H "Authorization: Bearer sv_live_…"

Cursors are opaque — don't try to parse or construct them. Always pass next_cursor through verbatim; the format may change in a future v1.x release without notice.

/v1/boards is the exception: it returns every board the caller can see in a single response (typically dozens, rarely a few hundred), so there's nothing to paginate.

Next

• Authentication — token lifecycle and how access is gated.
• Errors — every status code and error code you can get back.
• Rate limits — how much you can call, and how to back off.