Server SDK

@findlane/server uploads and updates catalogs, changes settings, and searches with a workspace API key. It runs in Node.js 18+, Bun, Deno, and edge runtimes.

Install

npm install @findlane/server

Create a client

import { SearchServerClient } from "@findlane/server"

const client = new SearchServerClient({
  workspaceId: process.env.FINDLANE_WORKSPACE_ID!,
  apiKey: process.env.FINDLANE_API_KEY!,
})

const products = client.index<Product>("products")

client.index<T>(name) returns the methods for one index. T types your records, which each need a string objectID. Every method returns a promise and takes an optional AbortSignal; the search methods take it as { signal } too.

Search

options (requestOptions for recommendations) takes signal and visitor.

Lists

index.lists reads and sets up the index's lists (0.17.0). Reading isn't counted as searches.

Searching for a visitor

When your server searches for someone, such as a shopper loading a server-rendered search page, pass the visitor (SDK 0.8.0):

const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent: req.get("user-agent") } })

The index's settings under Limits and bots on its Public access page then apply to that visitor, as they do to browser search, counted per visitor under your key:

• Searches a minute per visitor applies to each visitor.
• Crawlers get cached results first and a limit of their own, or are blocked, as you chose. Crawlers that say they're Googlebot, Bingbot, Applebot or OpenAI's are checked against the addresses those companies publish, and the verified ones' searches are free.
• Scripts and automation has its own limit, or is blocked.

Data-center networks can't be told apart for visitors you forward, so that setting applies to browser search only. Without visitor, a search counts as your server's own: only the key's searches a minute apply.

Subindexes

index("products").subindex("categories") is the index's subindex, an index of its own named products.categories: write and search it as any index. listSubindexes() lists an index's. A search takes subindexes to search them too, counted as one search (0.25.0).

Events

Orders and other events, for the index's Events page and Bought together (0.9.0). The key needs the events or write scope.

await products.events.send([{ type: "purchase", orderID: "1001", items: [{ objectID: "sku-123", quantity: 1 }] }])

Each request is retried on network errors and 408, 429, 502, 503, and 504, up to five times, waiting out the rate limit. An order counts once, however often it's sent.

While the index runs an A/B test, the events your server sends count toward a group only when they carry the shopper's. Keep the abTest of the search answer their browser got, with their cart, and send it with their order:

await products.events.send([{ type: "purchase", orderID: "1001", items: [{ objectID: "sku-123", quantity: 1 }] }],
  { abTest: cart.abTest }) // { id, variant }, from the search answer

Analytics

An index's analytics, for showing them in your own admin (0.15.0). The key needs the analytics scope, which no other scope includes, and works only from your server: requests from web pages are refused.

const week = await products.analytics.searches({ from: "2026-10-01", to: "2026-10-07" })
const empty = await products.analytics.queries({ list: "noResults", range: "30d", limit: 20 })
console.log(week.totals.searches, week.totals.noResultRate, empty.queries[0]?.query)

const panel = await products.analytics.product("sku-123", { range: "30d" })
console.log(panel.totals.views, panel.totals.orders, panel.searchedFor[0]?.query)

The options are range (24h, 7d, 30d or 90d; 7 days by default), or from and to as dates or times in UTC, plus source (all, browser or server), interval (hour or day) for the reports with a series, and signal. A date as to includes the whole day. Analytics go back 90 days, and products, productCounts and revenue to 9 October 2026, for up to 13 months. When a report's sampled is true, its counts are estimates; products, productCounts and revenue are exact. See Analytics for the responses.

Records

Writes return a receipt: { acceptedRevision, indexedRevision, recordCount }, and since 0.39.0 how many records the write added, changed, left unchanged and removed. See Records for how to use them.

replaceAllStaged takes an array or an async iterable of records, and these options:

upsertOne and deleteOne take { expectedVersion, idempotencyKey?, signal? }. The lower-level beginReplacement, uploadReplacementBatch, and commitReplacement are also available for running the stage steps yourself.

Updates

What has come into the index (0.39.0), as its Updates page in the dashboard shows it, for a sync's status in your own admin. The key needs the analytics scope, and works only from your server.

const { status, sources } = await products.writes.get({ range: "7d" })
console.log(status.lastData?.lastAt, status.lastChange?.lastAt, sources[0]?.source.label)

const { rows } = await products.writes.log({ problems: true })
for (const row of rows) console.log(row.at, row.source.label, row.reason, row.exampleId)

See Updates for the responses.

Settings

See Search settings for the fields and how changes apply.

compareSettings takes the settings replaceSettings does, or only those that change, and {} runs the tests with the current settings. It returns a SettingsComparison: a summary of the queries whose top 10 changed or that find more or fewer results, every test with before and after (whether it passes with each), and up to 50 changes, each with its totals and the results that left, joined, or moved within its top 10. A change to what the index stores, such as a new facet field, throws a FindlaneError with status 409: save it first. See Preview changes and search tests.

Merchandising

Arrange category pages and searches from your own app, as the dashboard's Merchandising page does (0.23.0). A target is { field, value } for a category page or { q } for a search's exact words.

const index = client.index("products")
await index.merchandising.set({ field: "category", value: "Jackets" }, {
  order: ["sku-311", "sku-120"],
  hidden: ["sku-098"],
  banner: { image: (await index.images.uploadFromUrl("https://example.com/sale.webp")).url, link: "/sale" },
  active: { from: "2026-11-27T00:00:00Z", until: "2026-11-30T23:59:00Z" },
})
const { banners } = await index.analytics.banners({ range: "30d" })

See the merchandising API for the fields and limits.

Product feeds

Connect an index to a store's product feed and follow its runs (0.24.0):

const index = client.index("products")
const check = await index.feed.check({ url: "https://shop.example/feed.xml" })
console.log(check.records, check.reasons)
await index.feed.set({ url: "https://shop.example/feed.xml", schedule: "hourly" })
const [run] = await index.feed.runs()

See the product feeds API for the fields.

Indexing status

Writes are searchable when they return, so waitUntilIndexed returns at once. It's there so code written for search services that index later keeps working.

Signed keys

For a logged-in person's browser searches, sign a short-lived key with a signing key from the API keys page (0.29.0). It makes no request:

import { signSearchKey } from "@findlane/server"

const signedKey = await signSearchKey(process.env.FINDLANE_SIGNING_KEY!, {
  validUntil: new Date(Date.now() + 60 * 60 * 1000),
  indexes: ["products"],
  filters: { customerGroup: user.group },
  returnFields: ["objectID", "title", "price"],
  userToken: user.id,
})

See Logged-in visitors.

Browser search access

Allowed origins are changed in the dashboard. See Security.

Errors

A failed request throws a FindlaneError with the HTTP status and the API's message. replaceAllStaged throws a StagedReplacementError with the stageId to retry or abort, and the original error as its cause.

import { FindlaneError } from "@findlane/server"

try {
  await products.upsert(records)
} catch (error) {
  if (error instanceof FindlaneError && error.status === 402) alertTeam(error.message)
  else throw error
}

The staged replacement and conditional write methods retry network errors and 408, 429, 502, 503, and 504 responses up to three times. See the error codes.