> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bkmark.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Search API Reference — Full-Text Search with Bkmark

> Full-text and AI semantic search across your bookmarks. Supports filtering by group and tag, cursor pagination, and automatic Pro/Team AI upgrades.

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.

<Note>
  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.
</Note>

***

## GET /api/v1/search

Search bookmarks by keyword or natural-language query.

<ParamField query="q" type="string" required>
  The search query. Searched against bookmark title, description, and URL. On Pro/Team plans, also processed by the AI semantic search engine.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor. Pass the `nextCursor` value from a previous response to fetch the next page of results.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of results to return per page. Accepted range: 1–100.
</ParamField>

<ParamField query="groupId" type="string">
  Restrict results to bookmarks that belong to this group UUID. Useful when you want to search within a specific collection.
</ParamField>

<ParamField query="tagId" type="string">
  Restrict results to bookmarks that carry this tag UUID. Combine with `groupId` to narrow results further.
</ParamField>

<Tip>
  Combine `groupId` and `tagId` to search within a highly specific slice of your library — for example, bookmarks tagged `unread` inside your `Engineering` group.
</Tip>

```bash theme={null}
curl "https://api.bkmark.it/api/v1/search?q=typescript+utility+types&limit=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

```json theme={null}
{
  "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"
}
```

<ResponseField name="data" type="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`.

  <Expandable title="Bookmark object fields">
    <ResponseField name="id" type="string">UUID of the bookmark.</ResponseField>
    <ResponseField name="url" type="string">The bookmarked URL.</ResponseField>
    <ResponseField name="title" type="string">Title of the bookmark.</ResponseField>
    <ResponseField name="description" type="string | null">Short description or excerpt.</ResponseField>
    <ResponseField name="type" type="string">One of `link`, `note`, `code`, `image`.</ResponseField>
    <ResponseField name="source" type="string">Surface that created the bookmark: `web`, `extension`, `api`, `import`, or `slack`.</ResponseField>
    <ResponseField name="isFavorite" type="boolean">Whether the bookmark is favorited.</ResponseField>
    <ResponseField name="isArchived" type="boolean">Whether the bookmark is archived.</ResponseField>
    <ResponseField name="readAt" type="string | null">ISO 8601 timestamp when the bookmark was marked as read, or `null` if unread.</ResponseField>
    <ResponseField name="tags" type="array">Tags applied to the bookmark, each with `id`, `name`, and `color`.</ResponseField>
    <ResponseField name="groups" type="array">Groups the bookmark belongs to, each with `id` and `name`.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="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.
</ResponseField>

***

## Search behavior

Bkmark uses a tiered approach to match your query against the library:

<Expandable title="How the search engine works">
  **1. Full-text search (all plans)**

  Bkmark performs full-text search against the combined `title`, `description`, and `url` fields of every bookmark. Results are ranked by relevance to your query.

  **2. Fuzzy fallback (all plans)**

  If the full-text search returns zero results, Bkmark automatically retries with fuzzy matching. This catches typos, alternate spellings, and partial words — so `"typscript"` still finds TypeScript resources.

  **3. AI semantic search (Pro and Team plans)**

  On Pro and Team plans, your query is also processed by an AI semantic search engine that understands conceptual meaning rather than exact keywords. Results from both the text engine and the semantic engine are merged and re-ranked by combined score before being returned.

  You don't need to configure anything — the upgrade happens automatically based on your plan.
</Expandable>

<Note>
  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.
</Note>