Skip to main content
The Search API lets you query your entire bookmark library with a single request. Bkmark performs full-text search across the title, description, and url fields of every bookmark. When an exact phrase match returns no results, the engine automatically falls back to fuzzy matching so typos and partial words still find what you’re looking for. On Pro and Team plans, AI semantic search activates automatically — it understands meaning and intent, not just keywords, so a query like "managing async state" surfaces articles about Redux, Zustand, React Query, and Promises even if those words don’t appear verbatim. All requests require a Bearer token in the Authorization header.
The Search endpoint returns the same response envelope as GET /api/v1/bookmarks, including cursor-based pagination. You can paginate through large result sets using the nextCursor field.

​
GET /api/v1/search

Search bookmarks by keyword or natural-language query.
​
q
string
required
The search query. Searched against bookmark title, description, and URL. On Pro/Team plans, also processed by the AI semantic search engine.
​
cursor
string
Pagination cursor. Pass the nextCursor value from a previous response to fetch the next page of results.
​
limit
number
default:"20"
Number of results to return per page. Accepted range: 1–100.
​
groupId
string
Restrict results to bookmarks that belong to this group UUID. Useful when you want to search within a specific collection.
​
tagId
string
Restrict results to bookmarks that carry this tag UUID. Combine with groupId to narrow results further.
Combine groupId and tagId to search within a highly specific slice of your library — for example, bookmarks tagged unread inside your Engineering group.
curl "https://api.bkmark.it/api/v1/search?q=typescript+utility+types&limit=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "data": [
    {
      "id": "3f7a1c2e-84b0-4d9e-a3f2-1c2e3f7a84b0",
      "url": "https://www.typescriptlang.org/docs/handbook/utility-types.html",
      "title": "Utility Types — TypeScript Handbook",
      "description": "Documentation for built-in utility types like Partial, Required, Readonly, Pick, and Omit.",
      "type": "link",
      "source": "extension",
      "isFavorite": true,
      "isArchived": false,
      "readAt": "2025-02-10T08:30:00.000Z",
      "tags": [
        { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "typescript", "color": "blue" },
        { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "reference", "color": "teal" }
      ],
      "groups": [
        { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Engineering" }
      ],
      "createdAt": "2025-01-15T11:00:00.000Z",
      "updatedAt": "2025-02-10T08:30:00.000Z"
    },
    {
      "id": "4a8b2d3f-95c1-5e0f-b4a3-2d3f4a8b95c1",
      "url": "https://github.com/sindresorhus/type-fest",
      "title": "sindresorhus/type-fest — A collection of essential TypeScript types",
      "description": "Hundreds of useful TypeScript utility types not included in the standard library.",
      "type": "link",
      "source": "api",
      "isFavorite": false,
      "isArchived": false,
      "readAt": null,
      "tags": [
        { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "typescript", "color": "blue" },
        { "id": "c3d4e5f6-a7b8-0123-cdef-123456789012", "name": "open-source", "color": "green" }
      ],
      "groups": [
        { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Engineering" }
      ],
      "createdAt": "2025-03-02T16:45:00.000Z",
      "updatedAt": "2025-03-02T16:45:00.000Z"
    }
  ],
  "nextCursor": "5b9c3e4a-a6d2-6f1a-c5b4-3e4a5b9c3e4a"
}
​
data
array
Array of matching bookmark objects, ordered by relevance. Each object is identical in shape to the bookmark objects returned by GET /api/v1/bookmarks.
​
nextCursor
string | null
Cursor for the next page of results. Pass this as the cursor query parameter in your next request. null when you have reached the last page.

​
Search behavior

Bkmark uses a tiered approach to match your query against the library:
The search query parameter on GET /api/v1/bookmarks runs the same engine as this endpoint. Use /search when search is your primary intent and you don’t need the additional filter parameters unique to the bookmarks list (such as isFavorite or isArchived). Both endpoints support groupId and tagId filtering.