Savee Developers
APIReference

Search

GET
/v1/search

Search Savee's public library

Full-text search across Savee's public library — not the caller's own saves. Results include the user who saved each item, since they come from across the platform.

Search is metered separately from the rest of the API and far more tightly: 20 searches per 5 minutes and 200 per week, reported as the search-burst and search-weekly policies in the RateLimit header. Pace against the weekly figure. Requires the search:read scope.

Authorization

Authorization
Required
Bearer <token>

Personal access token (sv_live_…) — represents you and carries every scope, so no scope is required for this call. Best for your own scripts and internal tools. Generate one at https://savee.com/developers/.

In: header

Authorization
Required
Bearer <token>

OAuth access token (sv_at_…) — obtained on one of your users’ behalf and limited to the scopes they approved. Use this when you’re building a product other people sign into with Savee. See https://docs.savee.com/api/oauth.

Missing the scope below returns 403 with a WWW-Authenticate: Bearer error="insufficient_scope" header naming it.

In: header

Scope: search:read

Query Parameters

limitinteger

Page size (default 30, max 100).

Example: 30Minimum: 1Maximum: 100

cursorstring

Opaque cursor returned in next_cursor from the previous page. Pass it through verbatim — the encoding is an implementation detail and may change.

Example: "eyJjIjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpIjoiNjdhYWRhMjAifQ"

query
Required
string

What to search for. Must be at least 2 characters.

Example: "brutalist poster"Minimum length: 2
Status codeDescription
200A page of matching saves.
400Invalid input.
401Missing or invalid Bearer token.
402Authenticated but the user has no active subscription.
403The Public API is not available on this account.
429Rate limit exceeded. Retry after the number of seconds in Retry-After.
500Unexpected server error.
curl -X GET "https://api.savee.com/v1/search?limit=30&cursor=eyJjIjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpIjoiNjdhYWRhMjAifQ&query=brutalist+poster"

{
  "data": [
    {
      "id": "67aada20d242ec0009400825",
      "url": "https://savee.com/i/UXb_bvc/",
      "name": "Brutalist poster",
      "source_url": "https://example.com/poster",
      "created_at": "2026-05-08T12:00:00.000Z",
      "is_private": false,
      "total_saves": 42,
      "media": {
        "type": "image",
        "width": 1600,
        "height": 2400,
        "thumbnail": "https://dm.savee.com/asset_image/w420/6r4nDqE.avif",
        "original": "https://dm.savee.com/asset_image/original/6r4nDqE.avif"
      },
      "colors": [
        {
          "color": "#1A1A1A",
          "amount": 0.62
        }
      ],
      "user": {
        "id": "63e1a4c2d242ec00094007f1",
        "username": "aliceb",
        "name": "Alice Bauer",
        "url": "https://savee.com/aliceb/",
        "avatar_url": "https://dm.savee.com/user-avatar/original/8kQ2mZp.jpg"
      }
    }
  ],
  "next_cursor": "eyJjIjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpIjoiNjdhYWRhMjAifQ",
  "has_more": true
}

Previous

Boards

Next

Overview

On this page