Searching

Searching is the one call everything else on this site exists to serve: give a list a query and it returns the records that best answer it, best match first. Two kinds of matching run together on every search. Word matching finds records containing the words the visitor typed, forgiving typos as it goes. Meaning matching — switched on by attaching an embedding model — compares what the words mean, so a search for “jumper” also finds a record that only ever says “sweater”. You never choose between the two per query: both run, and the strongest matches win.

This page is the reference for the search request itself — the address, every option you can send, and how the ranking works. The search box at the top of every list in the console uses exactly this engine, so it is the quickest way to try what you read here against your own records. To see the endpoints in action first, try the live meaning-based search and document search demos.

The basic request

Every list exposes one search address, carrying your API key in an X‑API‑Key header (create one on the console’s Developers tab — see API keys). The version in the path pins which shape of the list you are searching:

GET https://api.searchstack.dev/search/{account}/{list}/{version}?query=inception

To search several lists as one, use the group form — same options, results merged across every member list:

GET https://api.searchstack.dev/search/group/{account}/{group}/{version}?query=inception

For a group you can pass latest in place of the version to always search the group’s current version — the server resolves it at request time, so a pinned demo or integration never rots when the group is bumped or recreated. Pass a concrete integer version instead to freeze the exact set of records searched:

GET https://api.searchstack.dev/search/group/{account}/{group}/latest?query=inception

Both have a POST form taking the same options as a JSON body — handy once a request carries more than a couple of them:

POST https://api.searchstack.dev/search/{account}/{list}/{version}

{
  "query": "cordless drill",
  "filter": "in_stock eq true",
  "size": 20
}

How results are ranked

Each result carries a score per kind of match — @text_score for words and meaning, and @image_score, @document_score, @video_score, @audio_score when the record’s attached files contributed — each between 0 and 1, where 1 is a perfect match and absent means that kind played no part. Results are ordered by their strongest score, so a record that matches brilliantly on meaning is not held back by a weak word match. On a list without an embedding model, plain word-match relevance decides the order instead.

Two things can take over the ordering:

• A reranker attached to the list or group re-reads the top results against the query and promotes the ones that truly answer it. It runs automatically; send reranker=false to switch it off for one request.
• order_by sorts by fields instead of relevance — order_by=price asc, modified_utc desc. Sortable fields are name, created_utc, modified_utc and any typed facet.

Sending ranking=none skips relevance re-ordering entirely and returns the engine’s natural order — useful for filtered browsing where order doesn’t matter. To judge results against a written instruction after the search (“only family-friendly titles”), that’s a judge, not a ranking option.

Every option

The response

A ranked results array — engine data at the top level of each hit, your own fields under fields — plus counts and a query_id you can send to the click-through analytics endpoint to record which result the visitor chose:

{
  "results": [
    {
      "id": "b71b7c9c4f2e4c98",
      "name": "aero-runner-crimson",
      "list_name": "products",
      "version": 3,
      "@text_score": 0.91,
      "fields": { "title": "Aero Runner — Crimson", "price": 89.99, "in_stock": true }
    }
  ],
  "count": 1,
  "total_count": 14,
  "query_id": "0af8c2f1d0d94b76b5a4a4f8c2e1d901"
}

Radius searches add distance and location to each hit. Use id for edit and delete calls; name is the human-friendly key.

Search inside documents

A record can carry whole files — and search can read them. Point a resource field at a PDF (a public URL, or a file in the list’s media store) and, when the list’s embedding model can read documents, indexing takes the PDF’s content into account automatically. A query that matches what a document says finds its record — even when the record’s own name and fields never mention it. Those matches score under @document_score, tunable with minimum_document_score.

Models read PDFs in one of two ways, chosen automatically: models with native document support embed the pages directly (up to the model’s page limit), and any text model reads the text out of the PDF and matches on that. Either way there is nothing to transcribe or parse yourself — upload the record, and the file is part of the search.

You can also pull the text back out — to show the matching passage, feed a summariser, or build a preview pane:

GET https://api.searchstack.dev/search-result/document-text/{account}/{list}/{record-name}

{
  "search_result_name": "attention-is-all-you-need",
  "max_pages": 6,
  "documents": [
    { "uri": "https://cdn.acme.example/papers/attention.pdf", "page_count": 15, "text": "Abstract. The dominant sequence transduction models…", "error": null }
  ]
}

PDF is the supported document format today. Text comes back up to the max_pages cap; a per-document error explains any file that could not be read. The list must have a model attached.

A worked example

A research team keeps a papers list: searchable title and summary, facet year and category, and a document_url resource pointing at each paper’s PDF, indexed with a model that reads documents. A colleague searches “training image models without labels”. The word match catches papers that say so in their titles; the meaning match adds ones phrased as “self-supervised visual pretraining”; and the document match surfaces a paper whose title says nothing of the sort — because page four of the PDF does. The app shows the ranked results with their title and year, and when the colleague opens one, a call to document-text pulls the passage straight out of the file. One list, one query — words, meaning and documents searched together.

The rest of the search family

• Image search — query with a picture instead of words.
• Suggestions — the as-you-type endpoint that powers autocomplete.
• Related results — “more like this one”, seeded from a record instead of a query.
• Judges and Evaluations — filter results against an instruction, and measure search quality over time.