Saves

GET

/v1/saves

List the authenticated user's saves

Newest first. Includes the caller's private saves, with one exception: if the caller has enabled Hide private board saves from profile feed in their Savee settings, saves that belong to a private board are left out here too. The user field on each save is omitted because the caller is implicitly the owner.

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: saves:read

Query Parameters

`limit`integer

Page size (default 30, max 100).

Example: 30Minimum: 1Maximum: 100

`cursor`string

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"

Status code	Description
`200`	A page of saves.
`400`	Invalid input.
`401`	Missing or invalid Bearer token.
`402`	Authenticated but the user has no active subscription.
`403`	The Public API is not available on this account.
`429`	Rate limit exceeded. Retry after the number of seconds in `Retry-After`.
`500`	Unexpected server error.

curl -X GET "https://api.savee.com/v1/saves?limit=30&cursor=eyJjIjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpIjoiNjdhYWRhMjAifQ"

{
  "data": [
    {
      "id": "67aada20d242ec0009400825",
      "short_id": "UXb_bvc",
      "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"
      },
      "detected_aesthetics": "Bold black-and-white typography overlays a textured forest silhouette. Minimalist, grunge, typography, dark, moody, energetic, asymmetric, layered, negative space.",
      "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
}

GET

/v1/saves/{saveID}

Get a single save

Look up one save by either of its identifiers.

saveID accepts the id returned by any listing endpoint (67aada20d242ec0009400825) or the save's short_id — the segment in its savee.com URL. So a link like https://savee.com/i/997d6DW/ becomes GET /v1/saves/997d6DW directly, with no lookup step in between. The two forms can't be confused: an id is 24 hex characters, a short_id is 7.

Visible to the caller are their own saves (including private ones) and any public save on Savee. A save that exists but isn't visible returns 404 rather than 403 — the API does not confirm whether someone else's private save exists. Unlike /v1/saves, the response always includes the user who created the save, since it may not be the caller.

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: saves:read

Path Parameters

`saveID`
Required
string

The save id, or its short_id from a savee.com /i/…/ URL.

Example: "997d6DW"

Status code	Description
`200`	The save.
`400`	Invalid input.
`401`	Missing or invalid Bearer token.
`402`	Authenticated but the user has no active subscription.
`403`	The Public API is not available on this account.
`404`	Save not found or not visible to the caller.
`429`	Rate limit exceeded. Retry after the number of seconds in `Retry-After`.
`500`	Unexpected server error.

curl -X GET "https://api.savee.com/v1/saves/997d6DW"

{
  "data": {
    "id": "67aada20d242ec0009400825",
    "short_id": "UXb_bvc",
    "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"
    },
    "detected_aesthetics": "Bold black-and-white typography overlays a textured forest silhouette. Minimalist, grunge, typography, dark, moody, energetic, asymmetric, layered, negative space.",
    "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"
    }
  }
}

GET

/v1/feed

List the authenticated user’s home feed

Saves from users this user follows (and platform-curated content), newest first. Each save includes a user object describing the saver.

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: saves:read

Query Parameters

`limit`integer

Page size (default 30, max 100).

Example: 30Minimum: 1Maximum: 100

`cursor`string

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"

Status code	Description
`200`	A page of feed saves.
`400`	Invalid input.
`401`	Missing or invalid Bearer token.
`402`	Authenticated but the user has no active subscription.
`403`	The Public API is not available on this account.
`429`	Rate limit exceeded. Retry after the number of seconds in `Retry-After`.
`500`	Unexpected server error.

curl -X GET "https://api.savee.com/v1/feed?limit=30&cursor=eyJjIjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpIjoiNjdhYWRhMjAifQ"

{
  "data": [
    {
      "id": "67aada20d242ec0009400825",
      "short_id": "UXb_bvc",
      "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"
      },
      "detected_aesthetics": "Bold black-and-white typography overlays a textured forest silhouette. Minimalist, grunge, typography, dark, moody, energetic, asymmetric, layered, negative space.",
      "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
}

GET

/v1/boards/{boardID}/saves

List saves on a specific board

boardID is either the board id or the short_id returned by /v1/boards; both are accepted. 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.

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: boards:read, saves:read

Path Parameters

`boardID`
Required
string

The board id, or its short_id — both are returned by /v1/boards.

Query Parameters

`limit`integer

Page size (default 30, max 100).

Example: 30Minimum: 1Maximum: 100

`cursor`string

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"

Status code	Description
`200`	A page of saves on the board.
`400`	Invalid input.
`401`	Missing or invalid Bearer token.
`402`	Authenticated but the user has no active subscription.
`403`	The Public API is not available on this account.
`404`	Board not found or not accessible to the caller.
`429`	Rate limit exceeded. Retry after the number of seconds in `Retry-After`.
`500`	Unexpected server error.

curl -X GET "https://api.savee.com/v1/boards/string/saves?limit=30&cursor=eyJjIjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpIjoiNjdhYWRhMjAifQ"

{
  "data": [
    {
      "id": "67aada20d242ec0009400825",
      "short_id": "UXb_bvc",
      "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"
      },
      "detected_aesthetics": "Bold black-and-white typography overlays a textured forest silhouette. Minimalist, grunge, typography, dark, moody, energetic, asymmetric, layered, negative space.",
      "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
}

AuthorizationRequiredBearer <token>

AuthorizationRequiredBearer <token>

limitinteger

cursorstring

Response

Typescript

AuthorizationRequiredBearer <token>

AuthorizationRequiredBearer <token>

saveIDRequiredstring

Response

Typescript

AuthorizationRequiredBearer <token>

AuthorizationRequiredBearer <token>

limitinteger

cursorstring

Response

Typescript

AuthorizationRequiredBearer <token>

AuthorizationRequiredBearer <token>

boardIDRequiredstring

limitinteger

cursorstring

Response

Typescript

On this page

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`limit`integer

`cursor`string

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`saveID`
Required
string

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`limit`integer

`cursor`string

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`boardID`
Required
string

`limit`integer

`cursor`string