---
title: "List bookmarks"
method: GET
path: "/v1/bookmarks"
tags: ["Bookmarks"]
---

# List bookmarks

`GET /v1/bookmarks`

## Request

- Base URL: `https://stashr.me`
- URL: `https://stashr.me/v1/bookmarks`
- Auth: HTTP bearer

Browse bookmarks in reverse capture order using structured filters. Returns one page of items plus nextCursor; pass it back as cursor to continue and stop when it is null. view=summary returns bounded snippets without raw content blocks and is the right default for agent discovery.

## Query parameters

- `cursor` string
- `limit` integer
- `state` 'active' | 'archived' | 'all'
- `view` 'full' | 'summary'
- `q` string
- `untagged` boolean
- `authors` string[]
- `contentTypes` string[]
- `favorite` string[]
- `media` string[]
- `note` string[]
- `platforms` string[]
- `tags` string[]
- `authorMode` 'include' | 'exclude'
- `contentTypeMode` 'include' | 'exclude'
- `mediaMode` 'include' | 'exclude'
- `platformMode` 'include' | 'exclude'
- `tagMode` 'include_any' | 'include_all' | 'exclude_any' | 'exclude_all'
- `capturedAfter` string: Only bookmarks saved on/after this ISO-8601 date or datetime (inclusive)
- `capturedBefore` string: Only bookmarks saved before this ISO-8601 date or datetime (exclusive)

## Response `200`

One page of bookmarks (full or summary view)

- object
  - `data` union, required
    - BookmarkPage
      - `items` Bookmark[], required
        - `author` Author, nullable
          - `avatarUrl` string, nullable
          - `displayName` string, nullable
          - `profileUrl` string, nullable
          - `username` string, required
        - `capturedAt` string, date-time, required
        - `content` object[], required: Portable Text blocks holding the full body
        - `contentCreatedAt` string, date-time, nullable
        - `contentType` string, required: One of: repo, image, post, video, comment, article, page, snippet
        - `deletedAt` string, date-time, nullable
        - `id` string, uuid, required
        - `isFavorite` boolean
        - `media` Media[], required
          - `altText` string, nullable
          - `duration` number, nullable
          - `height` integer, nullable
          - `ref` string, required: Stable media ref usable with the media preview
          - `storedUrl` string, nullable
          - `thumbUrl` string, nullable: 800px webp derivative of storedUrl, when generated. Prefer it for previews/grids; storedUrl is the full-resolution archive.
          - `type` 'image' | 'video', required
          - `url` string, required
          - `width` integer, nullable
        - `note` string, nullable
        - `platform` 'github' | 'instagram' | 'reddit' | 'tiktok' | 'twitter' | 'web' | 'youtube', required: Platform id. X/Twitter is "twitter".
        - `platformId` string
        - `tags` Tag[], required
          - `color` string, required
          - `count` integer, required: Active bookmarks currently carrying this tag
          - `id` string, uuid, required
          - `name` string, required
        - `title` string, nullable: Present on titled content such as X articles
        - `url` string, uri, required
      - `nextCursor` string, nullable, required
      - `searchDegraded` string[]: Present when search retrieval quality was reduced: semantic_unavailable (embedding failed, lexical-only) or image_rank_unavailable (no captions, fell back to post ranking)
    - BookmarkSummaryPage
      - `degraded` string[]: Present when search retrieval quality was reduced; see BookmarkPage.searchDegraded
      - `items` BookmarkSummaryHit[], required
        - `archived` boolean, required
        - `author` string, nullable, required
        - `capturedAt` string, date-time, required
        - `contentCreatedAt` string, date-time, nullable, required
        - `contentType` string, required
        - `favorite` boolean, required
        - `id` string, uuid, required
        - `matchedMedia` object: Present on image-ranked search hits: the ranked image and its AI caption
          - `altText` string, nullable
          - `caption` string
          - `height` integer, nullable
          - `ref` string
          - `type` string
          - `url` string, nullable
          - `width` integer, nullable
        - `media` object[], required
          - `altText` string, nullable
          - `ref` string, required
          - `type` string, required
        - `mediaCount` integer, required
        - `platform` string, required
        - `tags` string[], required
        - `text` string, required: Bounded plain-text snippet (max 600 chars)
        - `title` string, nullable, required: Real title only; null when the source has none
        - `url` string, required
      - `nextCursor` string, nullable, required
      - `rankMode` 'post' | 'image', required: The ranking that actually ran
      - `requestedRankMode` 'post' | 'image': Present only when rankMode differs from what was requested

## Other responses

- `400`: Malformed request (error.code bad_request or invalid_json)
- `401`: Missing, invalid, or expired credentials (error.code unauthorized)
- `402`: A Pro plan or active trial is required (error.code payment_required)
- `403`: The credential lacks the required scope (error.code forbidden)
- `404`: The resource does not exist or belongs to another account (error.code not_found)
- `422`: Validation failed; error.details.issues lists the fields (error.code validation_error)
- `429`: Too many requests (error.code rate_limited); wait Retry-After seconds, also given as error.retryAfterMs
- `500`: Something failed on Stashr's side (error.code internal_error); retryable

---

[API](https://skmtc.dev/stashr/apis/stashr-api.md) · [All operations](https://skmtc.dev/stashr/apis/stashr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stashr/apis/stashr-api/revisions/bcab186e0646?raw)