# Search by meaning

> Add site search, related entries and duplicate checks to your website with Gravity, through the delivery API, the SDK or MCP, with hybrid meaning and keyword search across languages.

Source: https://docs.bifrostorbit.com/cms/developers/search/

Gravity finds content by what it means as well as by its words. A visitor who searches for "warm clothes for winter" on northwilds.com finds the Vinter insulated boot and the guide to layering for winter, though neither says "warm clothes", and a search in German finds pages written in English. Use it for:

- **Site search:** a search box on your website.
- **Related content:** "You may also like" under a trip or a product.
- **Answers grounded in your content:** fetch the passages closest to a question before an AI model answers it.
- **Duplicates:** editors see entries that say almost the same thing, and agents can check before they draft.

Gravity is included in every plan.

## Switch it on

An Administrator or Owner switches Gravity on for each environment under **Configuration › Settings › Gravity**. The space's entries are then indexed in the background, which takes a few minutes for a few thousand entries; **Settings** shows how many are indexed and how many are waiting. From then on every change is searchable within a minute of saving or publishing, and unpublished or deleted entries stop appearing at once.

Until Gravity is on, the endpoints below still answer, with keyword results.

## Search

```http
GET /cms/v1/search?q=warm%20clothes%20for%20winter&locale=en&type=gear,journalPost&limit=5
Authorization: Bearer cms_pk_…
```

```json
{
  "data": {
    "items": [
      {
        "id": "6650f1c2a9e4b1d2c3f40a31",
        "url": "/journal/layering-for-winter",
        "slug": "layering-for-winter",
        "name": "Layering for winter: stay warm without sweating",
        "contentType": "journalPost",
        "locale": "en",
        "score": 0.0328,
        "snippet": "How to layer for winter hiking and snowshoeing so you stay warm without sweating…",
        "fallbackApplied": false
      },
      {
        "id": "6650f1c2a9e4b1d2c3f40a32",
        "url": "/gear/vinter-insulated-boot",
        "slug": "vinter-insulated-boot",
        "name": "Vinter insulated boot",
        "contentType": "gear",
        "locale": "en",
        "score": 0.0306,
        "snippet": "A warm, waterproof winter boot for snowshoeing and cold walks down to minus 25°C…",
        "fallbackApplied": false
      }
    ],
    "total": 2,
    "hasMore": false,
    "gravity": { "mode": "hybrid", "fallback": false }
  }
}
```

| Parameter | |
| --- | --- |
| `q` | What to look for, 2 to 200 characters. Required. |
| `mode` | `hybrid` (the default) searches by meaning and by words and merges the two lists. `semantic` searches by meaning only, `keyword` by words only. |
| `locale` | The language to answer in, such as `de`, or several separated by commas. The region's default language unless you say. |
| `strict` | `true` answers only in the languages asked for, without the language fallback. |
| `region` | The region to search in. Search never crosses regions. |
| `type` | Content type keys, separated by commas, such as `gear,journalPost`. |
| `tag` | Entries whose `tags` field holds one of these, separated by commas. |
| `path` | Entries at this address or below it, such as `/gear`. |
| `limit`, `offset` | 1 to 50 entries, 10 unless you say, after skipping `offset` (up to 200). |
| `draft` | `true` searches drafts. Needs a secret key, from a server. |

Each entry appears once. A query in any language matches entries in every language the request covers, and each entry comes back in the language you asked for when it has a version there; `fallbackApplied` says when another language answered. So "warme Kleidung für den Winter" with `locale=de` answers with "Zwiebelprinzip im Winter", the German version of the layering guide, and with `locale=en` it answers with the English one.

`score` orders the entries within one answer. Its scale depends on the mode, so don't compare scores between answers or show them to visitors. `snippet` is a short passage of the entry's text, around the words asked for when they appear in it.

Banners, popups, shared sections and global content such as the footer are never in the results. Neither is anything a website couldn't read with the same key: drafts need `draft=true` and a secret key, entries in the bin never appear, and a landing page appears only while its campaign is live.

## Related entries

```http
GET /cms/v1/related?id=6650f1c2a9e4b1d2c3f40a32&type=gear&limit=4
Authorization: Bearer cms_pk_…
```

Answers in the same shape with the entries closest in meaning to the one you name, leaving out its translations. It answers in the language you ask for, or the entry's own, and takes `type`, `tag`, `path`, `region`, `locale`, `strict`, `limit` (1 to 20, 5 unless you say) and `draft`. Under the Fjell GTX boot on northwilds.com it answers with the Skarv mid boot, the Lyng trail shoe and the Vinter insulated boot.

## With the SDK

```ts
import { createCmsClient } from '@bifrost-orbit-cms/sdk'

const cms = createCmsClient({ baseUrl: process.env.CMS_API_URL!, apiKey: process.env.CMS_PUBLIC_KEY!, defaultRegion: 'europe' })

const { items, gravity } = await cms.search('tent for two people', { locale: 'en', type: 'gear', limit: 5 })
const alsoLike = await cms.related(trip.id, { type: 'trip', limit: 3 })
```

`search` and `related` take the parameters above as options (`type` and `tag` also as arrays, and `locales: ['de', 'en']` for several languages) and come with version 0.14 of the SDK. See the [SDK](https://docs.bifrostorbit.com/cms/developers/sdk/) guide.

## A search page in Next.js

```tsx
// app/search/page.tsx
import Link from 'next/link'
import { cms } from '@/lib/cms'

export default async function SearchPage({ searchParams }: { searchParams: Promise<{ q?: string }> }) {
  const { q = '' } = await searchParams
  const results = q.trim().length >= 2 ? await cms.search(q, { locale: 'en', limit: 20 }) : null
  return (
    <main>
      <form action="/search/">
        <input name="q" defaultValue={q} placeholder="Search trips and gear" />
      </form>
      {results?.items.map((item) => (
        <article key={item.id}>
          <h2>{item.url ? <Link href={`${item.url}/`}>{item.name}</Link> : item.name}</h2>
          {item.snippet ? <p>{item.snippet}</p> : null}
        </article>
      ))}
    </main>
  )
}
```

Searches from a browser can call the endpoint straight away with the public key in the address (`apiKey=cms_pk_…`), as the SDK does in browser code.

## When Gravity can't answer

Your search keeps working. If Gravity is off for the environment, can't be reached or is too busy, the answer has keyword results and says so:

```json
{ "gravity": { "mode": "keyword", "fallback": true, "reason": "unavailable" } }
```

`reason` is `off`, `unavailable`, `busy` or, for `related` only, `not_indexed` when the entry hasn't been indexed yet. Answers that fell back are cached for 15 seconds instead of 60, so meaning comes back quickly.

## Caching and limits

Search answers are cached like lists: `public, s-maxage=60, stale-while-revalidate=300` for published content, and never for drafts. They are dropped from CMS Orbit's own cache and our CDN when the index changes after a publish. They count towards the same rate limits as every other request; see the [Delivery API](https://docs.bifrostorbit.com/cms/developers/delivery-api/). The SDK tags them `cms:list` and `cms:search`, so `createRevalidateHandler` refreshes them on publish. The mirror never answers searches.

## For AI agents

Over MCP, `search_content` searches by meaning and by words together, and `find_similar` lists possible duplicates and related entries for one entry. See [MCP tools](https://docs.bifrostorbit.com/cms/developers/mcp-tools/).

## Where it runs

Gravity runs entirely on our own servers in the EU, like the rest of CMS Orbit: an open multilingual model turns text into numbers, and a vector database on the same servers searches them. No text is sent to another company to do this.
