Boards

GET

/v1/boards

List the authenticated user's boards

Returns every board the caller can see as a tree in a single response (not paginated): personal boards they own, boards they collaborate on, and boards from any Savee Teams workspace they're a member of. Only top-level boards appear at the root of data; a board's children are nested under its sub_boards array (single-level, so each sub-board is a leaf). Use the ownership_type field on each board to tell user-owned boards apart from team boards. The order at every level follows the caller's chosen boards-sort preference on savee.com.

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

Status code	Description
`200`	All boards visible to the caller, as a tree.
`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/boards"

{
  "data": [
    {
      "id": "69fbaf96d242ec48009df59a",
      "short_id": "Lp9wQ2s",
      "name": "Posters",
      "slug": "posters",
      "url": "https://savee.com/aliceb/posters/",
      "is_private": false,
      "saves_count": 128,
      "created_at": "2026-04-01T09:00:00.000Z",
      "og_image": "https://dm.savee.com/board-og/original/Lp9wQ2s.jpg",
      "ownership_type": "user",
      "sub_boards": [
        {
          "id": "string",
          "short_id": "string",
          "name": "string",
          "slug": "string",
          "url": "http://example.com",
          "is_private": true,
          "saves_count": 0,
          "created_at": "2019-08-24T14:15:22Z",
          "og_image": "http://example.com",
          "ownership_type": "team",
          "sub_boards": []
        }
      ]
    }
  ]
}

GET

/v1/boards/{boardID}

Get a single board

boardID is either the board id or the short_id returned by /v1/boards; both are accepted and both are stable across renames. Returns the board with its child boards nested under sub_boards — the same shape as a node in the /v1/boards tree — so there is no separate sub-boards endpoint. 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

Path Parameters

`boardID`
Required
string

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

Status code	Description
`200`	The board, with its sub-boards nested.
`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"

{
  "data": {
    "id": "69fbaf96d242ec48009df59a",
    "short_id": "Lp9wQ2s",
    "name": "Posters",
    "slug": "posters",
    "url": "https://savee.com/aliceb/posters/",
    "is_private": false,
    "saves_count": 128,
    "created_at": "2026-04-01T09:00:00.000Z",
    "og_image": "https://dm.savee.com/board-og/original/Lp9wQ2s.jpg",
    "ownership_type": "user",
    "sub_boards": [
      {
        "id": "string",
        "short_id": "string",
        "name": "string",
        "slug": "string",
        "url": "http://example.com",
        "is_private": true,
        "saves_count": 0,
        "created_at": "2019-08-24T14:15:22Z",
        "og_image": "http://example.com",
        "ownership_type": "team",
        "sub_boards": []
      }
    ]
  }
}

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>

Response

Typescript

AuthorizationRequiredBearer <token>

AuthorizationRequiredBearer <token>

boardIDRequiredstring

Response

Typescript

AuthorizationRequiredBearer <token>

AuthorizationRequiredBearer <token>

boardIDRequiredstring

limitinteger

cursorstring

Response

Typescript

On this page

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`boardID`
Required
string

`Authorization`
Required
Bearer <token>

`Authorization`
Required
Bearer <token>

`boardID`
Required
string

`limit`integer

`cursor`string