> For the complete documentation index, see [llms.txt](https://docs.overflowcms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overflowcms.com/api-reference/search-and-related-items.md).

# Search & Related Items

## Search & Related Items

### Search & Related Items

**Pro plan and above** (`flags.aiSearch`). Semantic search over a collection's published items, and "related items" for a specific item — both backed by a shared vector index (Workers AI embeddings + Vectorize), matching by meaning rather than exact keyword.

{% hint style="info" %}
Items are (re-)embedded automatically on publish and removed from the index on unpublish/delete — there's nothing to configure or trigger yourself.
{% endhint %}

#### Search

```
GET /v1/:token/search
```

**Query parameters**

| Param        | Example              | Notes                                                                                           |
| ------------ | -------------------- | ----------------------------------------------------------------------------------------------- |
| `q`          | `?q=freelance+taxes` | Required. The search query text.                                                                |
| `collection` | `?collection=blog`   | Optional. Scopes results to one collection's slug; omit to search every collection on the site. |
| `limit`      | `?limit=10`          | Default 10, hard max 50 — clamped, not rejected.                                                |

**Response**

```json
{
  "results": [
    {
      "item": {
        "id": "...",
        "slug": "the-complete-guide-to-managing-freelance-finances",
        "collection": "blog",
        "publishedAt": "2026-07-12T17:12:11.290Z",
        "data": { "title": "...", "excerpt": "...", "body": "..." }
      },
      "score": 0.66
    }
  ]
}
```

Results are ordered by `score` descending (cosine similarity, roughly 0–1). Matches below a minimum relevance threshold are dropped rather than returned as noise — an off-topic or non-English query (the embedding model is English-only) returns `{ "results": [] }` instead of a page of barely-related items.

#### Related items

```
GET /v1/:token/collections/:slug/items/:itemSlug/related
```

Returns items similar to the one identified by `:slug` (the collection) and `:itemSlug`, reusing that item's own stored embedding rather than re-embedding anything at request time — this call never touches Workers AI.

**Query parameters**

| Param   | Example    | Notes                                           |
| ------- | ---------- | ----------------------------------------------- |
| `limit` | `?limit=4` | Default 5, hard max 20 — clamped, not rejected. |

**Response**

```json
{
  "items": [
    { "id": "...", "slug": "...", "collection": "blog", "publishedAt": "...", "data": { "...": "..." } }
  ]
}
```

The item itself is always excluded from its own results. As with search, weak matches (below the same relevance threshold) are dropped rather than padding the response.

#### Errors

Both endpoints use the standard error envelope — see Errors — including two codes specific to this feature: `403 plan_required` (the site's plan doesn't include `flags.aiSearch`) and, for `/search` only, `400 bad_request` (missing/blank `q`) and `502 embedding_failed` (the embedding model failed to embed the query).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.overflowcms.com/api-reference/search-and-related-items.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.