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, 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.

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.