Dbrij Search Documentation

Search your users can feel: typo tolerant, faceted and ranked, answered in milliseconds through one API call. You push JSON documents into an index and query them. Your documents, your fields, your relevance.

There are three things to know before anything else. An index is a named collection of documents with its own search rules. A document is any JSON object with an id, and sending the same id again replaces it. A search only key can read an index and do nothing else, which is what makes it safe to ship in a browser.

Every response is wrapped as { "success": true, "data": … }, the same envelope the rest of the Dbrij API uses. The examples below show the payload inside data.

Three calls from nothing to a working search.

curl -X POST https://api.dbrij.com/api/search/indexes \
  -H "Authorization: Bearer $DBRIJ_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "products", "settings": { "filterableFields": ["brand", "price"], "sortableFields": ["price"] } }'

curl -X POST https://api.dbrij.com/api/search/indexes/products/documents \
  -H "Authorization: Bearer $DBRIJ_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "documents": [
        { "id": "1", "title": "Running shoes", "brand": "Nomad", "price": 45000 },
        { "id": "2", "title": "Trail runners", "brand": "Ardent", "price": 62000 }
      ] }'

Check what came back, not just the status. A write reports itself honestly and your importer should read it, because "the request worked" and "your documents are in" are different claims:

const res = await fetch(`${BASE}/search/indexes/products/documents`, { method: 'POST', headers, body });
const result = await res.json();

// 201 all landed · 207 some did not · 422 none did.
if (result.failed > 0) {
  // Every entry says which document and the engine's reason, cause included.
  console.error(`${result.failed} of ${result.failed + result.indexed} rejected`, result.errors);
  throw new Error('Sync incomplete');
}

const res = await fetch(`${BASE}/search/indexes/products/query`, {
  method: 'POST',
  headers: {
    // A search only key. It can read this index and nothing else, which is
    // why it is fine for your users to see it.
    Authorization: 'Bearer dbrij_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ q: input.value, facets: ['brand'], highlight: true }),
});
const { data } = await res.json();
render(data.hits);

Call it on every keystroke. A query is milliseconds of work, and search that waits for a button press stops feeling like search.

Pass a key as Authorization: Bearer dbrij_live_…. Keys are made in the dashboard under API keys and come in two kinds, and the difference is the most important thing on this page.

We store a hash of every key, so the full value is shown once at creation and is genuinely unrecoverable afterwards. Revoking takes effect within seconds. If an admin key ever reaches a public repository, revoke it first and investigate second.

One index, many tenants: scoped tokens. A search only key can read its whole index, which is not isolation when one index holds many customers\' rows, because anyone can open devtools and drop your filter. A scoped token fixes that: your backend mints it from a search key, the filter travels inside it, signed, and the browser gets the token instead of the key. The server verifies the signature and ANDs the embedded filter into every query; the client cannot loosen it.

import { createHash, createHmac } from 'node:crypto';

function scopedToken(rawKey, keyId, { filter, indexes, expiresInSeconds }) {
  const payload = Buffer.from(JSON.stringify({
    k: keyId,                                     // the search key's id (shown in the dashboard)
    f: filter,                                    // e.g. tenantId = "t_42", ANDed into every query
    ix: indexes,                                  // e.g. ['products'], the only indexes it may touch
    exp: Math.floor(Date.now() / 1000) + expiresInSeconds,
  })).toString('base64url');
  const secret = createHash('sha256').update(rawKey).digest('hex');
  const sig = createHmac('sha256', secret).update(payload).digest('base64url');
  return `dbsst_${payload}.${sig}`;
}

// Hand the token to the browser; it calls /query with
//   Authorization: Bearer dbsst_…
// exactly as it would with a key.

The signing secret is the sha256 of your raw key: your server can derive it, Dbrij stores exactly that hash, and the person holding the token has neither. A scoped token can only ever query, whatever the parent key could do, and revoking the parent key kills every token minted from it at once.

Search in a browser without writing the plumbing: a script tag for any website, widgets, React components and a typed client, all with click tracking built in, so learned ranking, taste, experiments and recommendations learn from day one. Use a search only key or a scoped token, never an admin key.

<div id="search"></div>
<script src="https://search.dbrij.com/search.js" async
  data-key="dbrij_live_your_search_key"
  data-index="products"
  data-target="#search"
  data-facets="brand,category"></script>

With data-target the whole experience draws inside that element: the box, refinements, results and pages, starting from ?q= in the page address. Give data-input with your own search box instead and search opens in a panel over the page as people type; pressing / opens it too. Add data-answers="true" for an answer above the results, data-understand="true" to read plain language into filters, and data-theme="dark" or auto for dark colours.

npm install @dbrij/search

import { SearchClient, mountSearch, mountAutocomplete } from '@dbrij/search';

const client = new SearchClient({ key: 'dbrij_live_your_search_key' });

mountSearch('#search', client, { index: 'products', facets: ['brand'], answers: true });

mountAutocomplete('#site-search', client, {
  index: 'products',
  onSelect: ({ query, objectId }) => {
    location.href = objectId ? `/products/${objectId}` : `/search?q=${encodeURIComponent(query ?? '')}`;
  },
});

import { SearchProvider, SearchBox, RefinementList, Hits, Pagination } from '@dbrij/search/react';

<SearchProvider client={client} index="products" facets={['brand']}>
  <SearchBox />
  <RefinementList field="brand" label="Brand" />
  <Hits render={(hit, track) => <a href={`/products/${hit.id}`} onClick={track}>{hit.document.title}</a>} />
  <Pagination />
</SearchProvider>

Clicks and conversions track themselves. The widgets and components send each click with the search that produced it. A purchase later on, even on another page, is credited to that search for an hour:

client.insights.converted({ index: 'products', objectIds: ['sku-1'], kind: 'purchase', value: 4500, currency: 'NGN' });

Drawing results yourself? Put data-dbrij-object-id, data-dbrij-position, data-dbrij-index and data-dbrij-query-id on each one and call trackClicks(container, client) once. Events are batched, sent within a second, flushed when the page closes, and never throw into your page.

One person, one token. The client gives each visitor an anonymous userToken and keeps it, so typing sessions, personal taste and experiments see one person. When they sign in, call client.setAuthenticatedUserToken(yourUserId) and their earlier activity joins their profile.

Safe with any record. Record text is always escaped, highlights keep only their <mark> tags, and links that are not web addresses are dropped, so a record cannot run script on your page.

Name an index after what it holds: products, articles, customers. Create one per kind of thing rather than one big index with a type field, because relevance settings are per index and mixing kinds means tuning for both at once.

curl -X POST https://api.dbrij.com/api/search/indexes \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "products", "settings": { "searchableFields": ["title", "description"], "filterableFields": ["category", "price"] } }'

{ "name": "products", "settings": { "searchableFields": ["title", "description"], "filterableFields": ["category", "price"] } }

{
  "success": true,
  "data": { "id": "3f…", "name": "products", "documentCount": 0, "status": "ready" }
}

curl -X GET https://api.dbrij.com/api/search/indexes \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [{ "name": "products", "documentCount": 1240, "sizeBytes": 918273, "status": "ready" }]
}

curl -X PUT https://api.dbrij.com/api/search/indexes/:name/settings \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "synonyms": [{ "terms": ["trousers", "pants"] }] } }'

{ "settings": { "synonyms": [{ "terms": ["trousers", "pants"] }] } }

{
  "success": true,
  "data": { "name": "products", "settings": { "synonyms": [{ "terms": ["trousers", "pants"] }] } }
}

curl -X DELETE https://api.dbrij.com/api/search/indexes/:name \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "ok": true }
}

A document is any JSON object with an id. Fields are typed as they arrive, and every string is stored twice: once broken into words for searching, once whole for filtering and faceting. That is what lets one field answer both "find shoes when I type shoe" and "category is exactly shoes".

curl -X POST https://api.dbrij.com/api/search/indexes/:name/documents \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "documents": [{ "id": "sku-1", "title": "Running shoes", "price": 45000, "brand": "Nomad" }] }'

{ "documents": [{ "id": "sku-1", "title": "Running shoes", "price": 45000, "brand": "Nomad" }] }

{
  "success": true,
  "data": { "indexed": 1, "failed": 0, "errors": [] }
}

curl -X POST https://api.dbrij.com/api/search/indexes/:name/documents/update \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "documents": [{ "id": "sku-1", "price": 42000, "inStock": false }] }'

{ "documents": [{ "id": "sku-1", "price": 42000, "inStock": false }] }

{
  "success": true,
  "data": { "updated": 1, "failed": 0, "errors": [] }
}

curl -X POST https://api.dbrij.com/api/search/indexes/:name/documents/delete \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filter": "author.id = 'usr_42'" }'

{ "filter": "author.id = 'usr_42'" }

{
  "success": true,
  "data": { "deleted": 17 }
}

curl -X POST https://api.dbrij.com/api/search/indexes/:name/clear \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "ok": true }
}

Keeping in sync. Push on write: when a record changes in your database, push that one document. Ids make it an update, so there is nothing to reconcile. A nightly full push is a reasonable safety net on top, and never a substitute.

curl -X POST https://api.dbrij.com/api/search/indexes/:name/query \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "q": "runing shoes", "filter": "price < 50000", "facets": ["brand"], "highlight": true }'

{ "q": "runing shoes", "filter": "price < 50000", "facets": ["brand"], "highlight": true }

{
  "success": true,
  "data": {
    "hits": [{ "id": "sku-1", "document": { "title": "Running shoes", "price": 45000 }, "score": 8.21, "highlights": { "title": ["<em>Running</em> shoes"] } }],
    "total": 1,
    "page": 1,
    "perPage": 20,
    "totalPages": 1,
    "tookMs": 4,
    "query": "runing shoes",
    "facets": { "brand": { "Nomad": 1 } },
    "cursor": "WzguMjEsInNrdS0xIl0",
    "queryId": "9b2f7c1e-4d3a-4f7e-9a51-2c8e0b6d1a77",
    "appliedRules": [{ "id": "r-1", "name": "Shoe week" }],
    "userData": [{ "banner": "Shoe week: 20% off", "link": "/sale" }],
    "categories": [{ "value": "Footwear", "confidence": 0.86 }]
  }
}

curl -X POST https://api.dbrij.com/api/search/indexes/:name/suggest \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "q": "run", "limit": 5 }'

{ "q": "run", "limit": 5 }

{
  "success": true,
  "data": { "suggestions": [{ "id": "sku-1", "document": { "title": "Running shoes" }, "score": 4.1 }], "tookMs": 2 }
}

curl -X POST https://api.dbrij.com/api/search/multi-search \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "queries": [{ "index": "products", "q": "invoice" }, { "index": "articles", "q": "invoice" }] }'

{ "queries": [{ "index": "products", "q": "invoice" }, { "index": "articles", "q": "invoice" }] }

{
  "success": true,
  "data": { "results": [{ "index": "products", "hits": [], "total": 0 }, { "index": "articles", "hits": [{ "id": "a1" }], "total": 1 }] }
}

Paging deep. Page numbers are fine for a results page; for export or infinite scroll use the cursor that comes back on every response and pass it to the next call. It walks the whole index in order without the drift and cost page offsets have at depth.

Typos are forgiven by default. One wrong letter on short words, two on longer ones. Turn it off per query with typoTolerance: false when you are searching identifiers, where "sku-1234" and "sku-1235" are different things rather than a near miss.

Highlights come back per field as an array of snippets with matches wrapped in <em> (a long field can produce several snippets). Render them as text unless you trust every document in the index, since the surrounding content is yours, not ours.

A filter narrows what can match, before relevance is considered. It may only name fields listed in the index's filterableFields: anything else is refused by name, which keeps a filter string that came from a URL from reaching further than you meant it to.

Length. A filter may be up to 20,000 characters, which holds a list of roughly a thousand values. That is deliberate room for the common case of narrowing to one neighbourhood or one tenant with IN [...]. Splitting one logical search across several queries to get under a limit costs you metered searches and gives you scores from different queries, which are not comparable.

Catalogues that are still filling in. A geo filter excludes documents with no coordinates yet, which is rarely what you want while you are still importing. Say so explicitly: _geoRadius(location, 6.45, 3.39, 5000) OR location NOT EXISTS.

Dates. Send dates as ISO 8601 strings (2026-08-24T10:00:00Z) and they are stored as real times, so ranges do what you mean: publishedAt >= "2026-07-01" is the last month, not an alphabet comparison.

Arrays and nested objects. An array field matches when any element matches, so tags = "sale" finds a document whose tags are ["new", "sale"], and faceting on it counts every element. Reach into nested objects with dots: author.country = "NG". Declare the dotted path itself in filterableFields.

Near me. Declare the field in geoFields, store it as { "lat": 6.45, "lon": 3.39 }, then filter with _geoRadius and sort by distance with "sort": ["_geoDistance(location, 6.45, 3.39):asc"]. To blend distance into relevance instead of sorting by it outright, send the searcher's position as aroundLatLng on the query and set geoRanking on the index, see Relevance.

{
  "q": "shoes",
  "filter": "inStock = true AND price < 50000",
  "facets": ["brand", "category"],
  "sort": ["price:asc"],
  "perPage": 24
}

Facets come back as counts per value, computed over everything the filter allowed. That is what lets you show "Nomad (12)" beside a checkbox and have the number be true.

Picks go in refinements, not the filter. Put what a shopper ticked in refinements. The results narrow exactly as they would with the same picks in the filter, but a refined field is counted as if its own picks were not made, so after choosing Nomad the brand list still shows Ardent with its count, ready to add. Every other filter and pick still applies to that count. It is one search, billed once.

{
  "q": "shoes",
  "filter": "inStock = true",
  "refinements": { "brand": ["Nomad", "Ardent"], "size": [42] },
  "facets": ["brand", "size"]
}

Settings live on the index. Change them in the dashboard or through the settings endpoint.

Matching: where the words have to be. By default a document matches when some single searchable field contains every word. That suits prose and is wrong for records assembled from parts. If your items carry itemName, storeName and zone, then "jollof rice ikeja" returns nothing when the dish is in the name and the place is in the zone, even though the document plainly holds every word. Set matchFields: "cross" and the searchable fields are pooled for matching while your weights still decide the order. Thing plus place is how people search a catalogue, so most marketplaces want this on.

Matching: how many words have to land. matchingStrategy: "all" is precise and returns nothing when a long query has no perfect document. "most" keeps a two word query strict and lets a five word one through on four, so a stray word returns the near misses instead of an empty page. Set either on the index or per query.

One caveat. Typo tolerance and matchFields: "cross" cannot both apply to one query: the engine will not fuzzy match across pooled fields. Cross wins and typo tolerance is skipped for that query, rather than the query being refused.

Field weights. Searchable fields take a weight with a caret: "title^3" counts a title match three times as hard as a body match. Order plus weights is usually all the tuning a catalogue needs before customRanking earns its keep.

The workflow that actually improves search. Read the "found nothing" list in Analytics. Each row is somebody who wanted something and did not get it. Most of them are one synonym away, or one field that should have been searchable.

Synonym mining does that reading for you. The dashboard's Relevance page suggests synonyms mined from your own missed queries (each candidate shows how many searches it would have rescued), and accepting one applies it to the index in a click. Start there before writing synonyms by hand.

Keyword search matches what somebody typed. Semantic search matches what they meant, which is the difference between "something for a headache" finding nothing and finding paracetamol. Neither is better: keyword is exact and cheap and gets product codes right; semantic is forgiving and gets intent right. Hybrid runs both and fuses the two lists, and is what most search boxes want.

Turn it on per index, in the dashboard's index settings or through the settings endpoint. Enabling it (or changing the model) rebuilds the index in the background while queries keep serving on the old rules. It is off by default and needs a paid plan, because a vector index is resident memory.

curl -X PUT https://api.dbrij.com/api/search/indexes/products/settings \
  -H "Authorization: Bearer $DBRIJ_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "semantic": { "enabled": true, "model": "voyage-4-lite", "fields": [], "weight": 0.5 } } }'

Choosing per query. Send mode on the query call: "keyword" (default), "semantic", or "hybrid". A common pattern is hybrid for the main search box and keyword for identifier lookups where "sku-1234" must never fuzzy match "sku-1235".

{ "q": "something for a headache", "mode": "hybrid", "perPage": 10 }

Fusion. In hybrid mode the keyword list and the semantic list become one ranking. The default, rrf (reciprocal rank fusion), only reads the position a document reached in each list, so there is nothing to calibrate: a hit near the top of either list rises, a hit near the top of both wins. linear adds the scores instead and is offered for anyone who has measured their corpus and disagrees.

Semantic and hybrid queries on an index that has semantic disabled, or on the Free plan, return a 400 that says so. Everything else about the call (filters, facets, scoped tokens, metering) works exactly as in keyword mode.

Every search returns a queryId. When the person clicks a result, adds it to a cart or buys it, send an event with that queryId. Events are what learned ranking, personal taste, categories and experiments learn from, and what engagement analytics count.

curl -X POST https://api.dbrij.com/api/search/events \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": [
  { "type": "click", "name": "Product clicked", "index": "products", "userToken": "anon-71c2", "queryId": "9b2f7c1e-4d3a-4f7e-9a51-2c8e0b6d1a77", "objectIds": ["sku-1"] },
  { "type": "conversion", "name": "Purchased", "index": "products", "userToken": "anon-71c2", "queryId": "9b2f7c1e-4d3a-4f7e-9a51-2c8e0b6d1a77", "objectIds": ["sku-1"], "kind": "purchase", "value": 45000, "currency": "NGN" }
] }'

{ "events": [
  { "type": "click", "name": "Product clicked", "index": "products", "userToken": "anon-71c2", "queryId": "9b2f7c1e-4d3a-4f7e-9a51-2c8e0b6d1a77", "objectIds": ["sku-1"] },
  { "type": "conversion", "name": "Purchased", "index": "products", "userToken": "anon-71c2", "queryId": "9b2f7c1e-4d3a-4f7e-9a51-2c8e0b6d1a77", "objectIds": ["sku-1"], "kind": "purchase", "value": 45000, "currency": "NGN" }
] }

{
  "success": true,
  "data": { "accepted": 2, "rejected": [] }
}

Checked against the search. A click that names a queryId must be a record that search actually showed, or it is refused with that reason, so a buggy page cannot quietly train your ranking wrong. Its position is taken from the search itself.

Private by design. The userToken is yours to choose and should never be a name, an email or a phone number. Each person counts once per record per search when ranking is learned, so one enthusiast cannot move a result. Erase a person at any time with the profile endpoint under Learned ranking and taste.

curl -X GET https://api.dbrij.com/api/search/events/health?days=7 \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "accepted": 18240, "rejected": 12, "attributedClickShare": 0.97, "reasons": [{ "reason": "a clicked record was not in that search’s results.", "count": 12 }], "lastEventAt": "2026-10-27T09:14:02Z" }
}

curl -X GET https://api.dbrij.com/api/search/analytics/engagement?days=30 \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "trackedSearches": 48210, "clickThroughRate": 0.41, "conversionRate": 0.06, "averageClickPosition": 2.3, "noClickQueries": [{ "query": "charger", "searches": 310, "withResults": 310 }], "topClickedQueries": [{ "query": "running shoes", "searches": 1204, "clicks": 802, "ctr": 0.58 }], "revenue": [{ "currency": "NGN", "total": 9120000 }] }
}

Four settings on an index, each read when a search runs, so turning one on or changing it never rebuilds anything. All of them learn from events and update every hour.

reRanking { enabled, windowDays: 7 | 30 | 90, maxMove: 1 to 20, promoteFilter }. Results people choose for a search rise and ones nobody picks sink. A click at position 8 counts for more than a click at position 1 (people click the top because it is the top), small numbers are smoothed toward the search’s average instead of trusted, nothing moves more than maxMove places, and only records matching promoteFilter may rise. It only reorders what the search found; it never adds a record. Ask with explain: true to see from and to on each hit that moved.

personalization { enabled, facets: [{ field, weight }], impact: 0 to 100, eventWeights }. Each person’s results lean toward the values they choose (a brand, a category), from the events carrying their userToken. At impact 100 a favourite gets at most double the score. Taste halves every 30 days without new events and is forgotten after 90.

categorization { enabled, field, boostAt, filterAt }. What a search is about, learned from the category of what people chose after it, returned as categories with a confidence. At boostAt the category is boosted; at filterAt (optional) results are filtered to it. A person’s own filter on that field always wins. A search needs choices spread over at least three records before it is categorized.

suggestions { banned, minSearches, minLetters } keep junk out of query suggestions.

curl -X POST https://api.dbrij.com/api/search/indexes/:name/query-suggestions \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "q": "run" }'

{ "q": "run" }

{
  "success": true,
  "data": [{ "query": "running shoes", "searches": 1204 }, { "query": "running watch", "searches": 233 }]
}

curl -X GET https://api.dbrij.com/api/search/indexes/:name/profiles/:userToken \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "userToken": "anon-71c2", "lastEventAt": "2026-10-27T09:14:02Z", "affinities": { "brand": { "Nomad": 1, "Trek": 0.42 } } }
}

curl -X DELETE https://api.dbrij.com/api/search/profiles/:userToken \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "erased": true }
}

Rules steer what a search shows: pin a record to a place, hide one, boost or bury by a filter, add a filter, rewrite the query, or hand your app a banner. Every response names the rules that fired in appliedRules, so nothing about the order is a mystery.

Which rule wins. The most precise: an exact match beats starts with, which beats ends with, which beats contains; then the longer pattern; then a rule aimed at a context; then the most recently changed. Only the best rewrite is used. Two pins asking for one place: the better rule keeps it and the other moves down. A record both pinned and hidden is hidden. Pins respect the search’s filters, including a scoped key’s.

The order of work in a search: rules (rewrite, filters, boosts, hides), then learned ranking, then pins.

curl -X POST https://api.dbrij.com/api/search/indexes/:name/rules \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shoe week", "conditions": [{ "pattern": "shoes", "anchoring": "contains" }], "consequence": { "pins": [{ "id": "sku-9", "position": 1 }], "boosts": [{ "filter": "brand = \"Nomad\"", "strength": "moderate", "direction": "boost" }], "userData": { "banner": "Shoe week: 20% off" } }, "validUntil": "2026-11-30T23:59:59Z" }'

{ "name": "Shoe week", "conditions": [{ "pattern": "shoes", "anchoring": "contains" }], "consequence": { "pins": [{ "id": "sku-9", "position": 1 }], "boosts": [{ "filter": "brand = \"Nomad\"", "strength": "moderate", "direction": "boost" }], "userData": { "banner": "Shoe week: 20% off" } }, "validUntil": "2026-11-30T23:59:59Z" }

{
  "success": true,
  "data": { "id": "r-1", "index": "products", "name": "Shoe week", "enabled": true, "conditions": [ … ], "consequence": { … } }
}

curl -X GET https://api.dbrij.com/api/search/indexes/:name/rules \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [{ "id": "r-1", "name": "Shoe week", "enabled": true }]
}

curl -X PUT https://api.dbrij.com/api/search/indexes/:name/rules/:ruleId \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

curl -X DELETE https://api.dbrij.com/api/search/indexes/:name/rules/:ruleId \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

Try a change on part of your real traffic before everyone gets it. Each search that carries a userToken stays in one variant for that person; searches without one are assigned one by one. The response says which variant ran in abTest, and the clicks and conversions sent with its queryId decide the result.

Two answers are given side by side: the probability a variant is really better (Bayesian, which is what a person deciding wants to know) and a two sided p value (for anyone who has to report one), plus the searches each variant still needs. Stop early on a strong verdict if you like; stopping on a weak one is how experiments lie.

curl -X POST https://api.dbrij.com/api/search/ab-tests \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Learned ranking on", "index": "products", "metric": "clickThroughRate", "days": 14, "variants": [{ "name": "A", "trafficPercent": 50, "overrides": {} }, { "name": "B", "trafficPercent": 50, "overrides": { "reRanking": true } }] }'

{ "name": "Learned ranking on", "index": "products", "metric": "clickThroughRate", "days": 14, "variants": [{ "name": "A", "trafficPercent": 50, "overrides": {} }, { "name": "B", "trafficPercent": 50, "overrides": { "reRanking": true } }] }

curl -X GET https://api.dbrij.com/api/search/ab-tests \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [{ "name": "Learned ranking on", "status": "running", "results": [{ "name": "A", "searches": 9120, "clickThroughRate": 0.40 }, { "name": "B", "searches": 9184, "clickThroughRate": 0.44, "probabilityBetter": 0.99, "pValue": 0.0003, "lift": 0.10 }], "samplesNeeded": 8900, "verdict": "B beats A on click through rate (up 10%), with a 99% chance of being really better." }]
}

curl -X POST https://api.dbrij.com/api/search/ab-tests/:testId/stop \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

Point a crawler at a site and it keeps an index of its pages, daily, weekly or when you run it. It identifies as DbrijSearchBot, obeys robots.txt (a group naming it wins over *), reads at most two pages at a time with a pause between them, and skips pages marked noindex.

Safe recrawls. Pages the last crawl made that this one no longer finds are removed, unless that would remove more than a tenth of them: a site that is down, or a robots.txt that started refusing everything, must not empty your index. That crawl stops and says so instead.

Pages are read as your server sends them, without running JavaScript. A page that only appears after scripts run should be pushed with the documents API instead. Each page is one record and counts toward your plan.

curl -X POST https://api.dbrij.com/api/search/crawlers \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Docs", "index": "docs", "startUrls": ["https://docs.example.com"], "exclude": ["*/archive/*"], "schedule": "daily" }'

{ "name": "Docs", "index": "docs", "startUrls": ["https://docs.example.com"], "exclude": ["*/archive/*"], "schedule": "daily" }

curl -X POST https://api.dbrij.com/api/search/crawlers/:crawlerId/run \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

curl -X GET https://api.dbrij.com/api/search/crawlers \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

curl -X GET https://api.dbrij.com/api/search/crawlers/:crawlerId/runs \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

curl -X PUT https://api.dbrij.com/api/search/crawlers/:crawlerId \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

curl -X DELETE https://api.dbrij.com/api/search/crawlers/:crawlerId \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

Two ways the index reads people the way they write, both off until you turn them on under the index’s Learning tab (or with the answers and understanding settings), because both spend the account’s AI credits.

answers { enabled, fields, instructions, quality: fast | best, maxSources: 1 to 10 }. fields are what is read from each record (empty reads them all); instructions are your words on how to answer.

curl -X POST https://api.dbrij.com/api/search/indexes/:name/answer \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "q": "How long do I have to return something?" }'

{ "q": "How long do I have to return something?" }

{
  "success": true,
  "data": {
    "answer": "You have 30 days from delivery to return an item, unworn and with its tags [1]. Refunds land within 5 working days of the return arriving [2].",
    "answered": true,
    "sources": [{ "id": "help-returns", "ref": 1, "cited": true, "document": { "title": "Returns" } }, { "id": "help-refunds", "ref": 2, "cited": true, "document": { "title": "Refunds" } }],
    "queryId": "9b2f7c1e-4d3a-4f7e-9a51-2c8e0b6d1a77",
    "cached": false,
    "tookMs": 1840
  }
}

understanding { enabled }. Send understand: true on a search with three words or more, and it is read into words, a filter and a sort against the index’s own fields and a sample of their values. Everything read is checked before it is used: a filter that does not parse or names a field the index does not filter on is dropped, and so is a sort on a field that is not sortable. The read filter is ANDed onto yours, so it can only narrow, and your own sort always wins. The response says what was read in understood. Each new phrasing costs one model call and is remembered for a day; if anything goes wrong the search runs as typed.

From the same records and the same events as search, with nothing to set up. Related works from day one; the others fill in as events arrive and are recomputed every hour.

• related: records like this one, by meaning when the index has semantic search on (the record’s nearest neighbours), else by its words.
• boughtTogether: records that at least two different people converted on together, within a day of each other, over the last 90 days.
• trending: records at least three people chose this week, ranked by how much faster than last week, weighed by how many.
• trendingValues: the same, rolled up by a field’s values (the rising brands or categories).

curl -X POST https://api.dbrij.com/api/search/indexes/:name/recommend \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "boughtTogether", "objectId": "sku-1", "filter": "inStock = true" }'

{ "model": "boughtTogether", "objectId": "sku-1", "filter": "inStock = true" }

{
  "success": true,
  "data": { "model": "boughtTogether", "hits": [{ "id": "sku-7", "document": { "title": "Running socks" }, "score": 14 }] }
}

Every query is logged with whether it found anything. The "found nothing" list is the single most actionable thing in search: each row is somebody who wanted something, did not get it, and might have left over it.

curl -X GET https://api.dbrij.com/api/search/analytics?days=30 \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": {
    "totalSearches": 48210,
    "noResultSearches": 1861,
    "avgTookMs": 6,
    "topQueries": [{ "query": "running shoes", "count": 1204, "noResultRate": 0, "avgTookMs": 4 }],
    "missedQueries": [{ "query": "panadol", "count": 320, "noResultRate": 1, "avgTookMs": 3 }]
  }
}

This endpoint needs search:manage, so call it with an admin key from your server. A search only key gets a 403 here by design: analytics describe everything your users search for, which is not something a key that ships in a browser should be able to read.

Retention follows your plan (7 to 90 days). Suggestions are not logged: five keystrokes are one intent, and logging each would drown the signal this list exists for.

Keep your own tests out of it. Send "analytics": false on smoke tests, health checks and anything you run from a script. A diagnostic is not a person looking for something, and the "found nothing" list is only worth reading while every row on it is real. The query is still billed either way: the engine still did the work.

Documents are a hard ceiling and searches are metered. A document costs memory for as long as it exists, while a query costs milliseconds, so going past your document limit is refused rather than billed, and searches past the allowance bill per thousand at renewal. The free plan has no overage at all: it stops serving instead of running up a bill you did not agree to.

Typing is one search. Search as you type sends a request on every keystroke; you are billed for the search, not the keystrokes. Requests from the same person on the same index within 30 seconds of each other, whose words extend, shorten or repeat the last ones, count as the one search they started, along with its pages and refinements. Suggestions count the same way. A session lasts at most two minutes and 50 requests. The person is your userToken when you send one, else the browser, so send a userToken from a server that searches on behalf of many people.

A document counts once for every 2 KB it takes in the index, so a long article can count as several. A typical product or listing counts as one.

Bulk ingestion. Up to 1,000 documents per call; chunk bigger loads and run chunks in sequence. Writes count against your requests a minute like everything else, and the response tells you per document what was indexed and what failed, so a crashed import is safe to re-run from the top.

A plan is what you hold, not only what you add. The document and index ceilings apply to what the workspace is holding right now, not just to the next push. Move to a smaller plan while holding more than it allows and you get a week: everything keeps working, the owner gets an email, the billing page says what is over and which plan fits. After the week, queries answer 402 until the workspace is back inside its plan, either by moving up or by removing what is over. Free plans also cap searches at 100 a day.

Never trust the status code alone on a write. A write has three outcomes and each has its own code: 201 every document landed, 207 some did not, 422 none did. Read indexed and failed as well, and only record a sync as complete when failed is zero. A loop that checks res.ok and moves on will happily report a finished import over an empty index.

Handling 429 in a search box. Debounce by 100ms or so before searching on keystroke, and on a 429 keep the last good results on screen rather than clearing them. An empty list reads as "nothing found", which is a worse lie than a slightly stale one.