Skip to content

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.

How-to guide6 min read

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.

HTTP
GET /cms/v1/search?q=warm%20clothes%20for%20winter&locale=en&type=gear,journalPost&limit=5Authorization: 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 }  }}
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.

HTTP
GET /cms/v1/related?id=6650f1c2a9e4b1d2c3f40a32&type=gear&limit=4Authorization: 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

TypeScript
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 guide.

A search page in Next.js

app/search/page.tsxTypeScript
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. 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.

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.

Was this page helpful?

Read next