Search

Try it

GET /:handle/search

Full-text search with pagination, facets, filters, sorting, highlighting, histograms, and geo clustering.

Query parameters

Parameter	Type	Default	Description
q	string	""	Search query text. Empty string returns all documents.
page	number	1	Page number (1-based).
perPage	number	20 / config	Results per page (1–100).
sort	json	—	Sort order. JSON object mapping field names to "asc" or "desc".
facets	string	config default	Comma-separated list of fields to aggregate as facets.
filters	json	—	Field filters. See Filters.
highlight	string	config default	"true" to highlight all fields, or a comma-separated list of field names to highlight selectively (e.g. "title,description").
fields	string	all fields	Comma-separated list of fields to return.
suggest	string	—	"true" to enable phrase suggestions (requires suggestField in config). ES/OS only
boosts	json	config default	Field boost weights. JSON object mapping field names to numbers. ES/OS only
histogram	json	—	Histogram intervals. See Histograms. ES/OS only
geoGrid	json	—	Geo tile grid. See Geo Map. ES/OS only

All field-name parameters (sort, facets, filters, boosts, fields, highlight, histogram, geoGrid.field) support field aliases when configured.

Which fields get searched

Field weights are normally set in config via fields with weight — these are applied automatically on every search. The boosts query param exists as an override: if a request passes boosts, the config weights are ignored for that request.

When no boosts are configured at all, the API falls back to fields marked searchable: true, then to all fields (*).

See Configuration for setting up field weights.

Sort field resolution

Note

ES/OS only — when you sort on a text field that has a .keyword sub-field, the API automatically resolves to field.keyword. You can pass {"title":"asc"} without worrying about the underlying Elasticsearch mapping.

Phrase suggestions

When suggest=true is set and a suggestField is configured for the index, the API returns phrase-level corrections in the suggestions array. The suggest field should have a shingle analyzer configured in your Elasticsearch mapping for best results. Suggestions are only generated when the search query is non-empty.

Response

{
  "hits": [
    {
      "objectID": "498",
      "_index": "museum_collections",
      "_score": 12.5,
      "_highlights": {
        "title": ["Stirling <mark>Castle</mark>"]
      },
      "title": "Stirling Castle",
      "country": "Scotland"
    }
  ],
  "totalHits": 42,
  "page": 1,
  "perPage": 20,
  "totalPages": 3,
  "facets": {
    "country": [
      { "value": "Scotland", "count": 18 },
      { "value": "England", "count": 15 }
    ]
  },
  "suggestions": []
}

Field	Type	Description
hits	SearchHit[]	Array of matching documents.
totalHits	number	Total number of matching documents.
page	number	Current page number (1-based).
perPage	number	Results per page.
totalPages	number	Total number of pages.
facets	Record<string, FacetValue[]>	Facet aggregations keyed by field name.
histograms	Record<string, Bucket[]>?	Histogram aggregations (when requested).
geoClusters	GeoCluster[]?	Geo tile grid results (when requested).
suggestions	string[]	Spelling/phrase suggestions.

Each hit contains all document fields plus metadata: objectID, _index, _score, and _highlights.

Examples

Basic search

curl "https://search-api-elysia-production.up.railway.app/collections/search?q=castle"

Paginated and sorted

curl "https://search-api-elysia-production.up.railway.app/collections/search?q=castle&page=2&perPage=10&sort=%7B%22title%22%3A%22asc%22%7D"

The sort param decoded: {"title":"asc"}

With facets and filters

curl "https://search-api-elysia-production.up.railway.app/collections/search?q=&facets=country,region&filters=%7B%22country%22%3A%22Scotland%22%7D"

Highlighting enabled

curl "https://search-api-elysia-production.up.railway.app/collections/search?q=castle&highlight=true"

Specific fields only

curl "https://search-api-elysia-production.up.railway.app/collections/search?q=castle&fields=title,country"

With field boosts

curl "https://search-api-elysia-production.up.railway.app/collections/search?q=castle&boosts=%7B%22title%22%3A10%2C%22description%22%3A2%7D"

The boosts param decoded: {"title":10,"description":2}

Error responses

Status	Condition
400	Invalid JSON in sort, filters, boosts, histogram, or geoGrid
401	Missing or invalid bearer token
404	Index handle not found