Search · API reference

4 endpoints.

GET /v1/suggest
GET /v1/search
POST /v1/search
GET /v1/recommend

GET/v1/suggest

Suggestions while typing (never billed)

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`q`	`query`	`string`	yes	max length 128
`lang`	`query`	`string`	no	`auto` or a tenant locale. · default "auto" · pattern ^(auto\|[a-z]{2})$
`limit`	`query`	`integer`	no	default 8 · min 1 · max 20
`products`	`query`	`integer`	no	How many product previews to include. · default 4 · min 0 · max 10
`session`	`query`	`string \| null`	no	max length 64

Responses

200Successful ResponseSuggestResponse

GET/v1/search

Search (GET form)

Needs a key or a dashboard session

Filters use `filter[<name>]=v1,v2` and `filter[<name>][gte|lte]=n`. Response has the `X-SeekGist-Usage` header. Billed when page=1.

Parameters

Name	In	Type	Required	Description
`q`	`query`	`string`	no	max length 256
`lang`	`query`	`string`	no	`auto` or a tenant locale. · default "auto" · pattern ^(auto\|[a-z]{2})$
`page`	`query`	`integer`	no	default 1 · min 1 · max 1000
`per_page`	`query`	`integer`	no	default 20 · min 1 · max 100
`sort`	`query`	`"relevance" \| "price_asc" \| "price_desc" \| "newest" \| "popular"`	no	default "relevance"
`facets`	`query`	`string \| null`	no	Comma-separated facet names.
`ai`	`query`	`"auto" \| "on" \| "off"`	no	default "auto"
`session`	`query`	`string \| null`	no	max length 64
`device`	`query`	`"desktop" \| "mobile" \| "tablet" \| "unknown"`	no	default "unknown"

Responses

200Successful ResponseSearchResponse

POST/v1/search

Search (JSON body, complex filters)

Needs a key or a dashboard session

Request body `application/json` `SearchRequest`

Name	Type	Required	Description
`q`	`string`	no	max length 256
`lang`	`string`	no	`auto` or a tenant locale.default "auto" · pattern ^(auto\|[a-z]{2})$
`page`	`integer`	no	default 1 · min 1 · max 1000
`per_page`	`integer`	no	default 20 · min 1 · max 100
`filters`	`map<string, string[] \| RangeFilter \| string \| boolean>`	no	e.g. {"brand": ["Lenovo"], "price": {"lte": 600}, "in_stock": true}
`sort`	`"relevance" \| "price_asc" \| "price_desc" \| "newest" \| "popular"`	no	default "relevance"
`facets`	`string[]`	no	Facet names to return, e.g. brand, category, price.
`ai`	`"auto" \| "on" \| "off"`	no	auto = plan + tenant setting decide, and the AI runs only when it helps (price or use-case requests, long or unknown words, zero results); on = the AI on every query (plan and budget still apply); off = never call the AI.default "auto"
`session`	`string \| null`	no	Opaque shopper session id (no PII).max length 64
`device`	`"desktop" \| "mobile" \| "tablet" \| "unknown"`	no	default "unknown"
`debug`	`boolean`	no	Secret key or dashboard only: include the pipeline trace.default false
`config_override`	`RankingConfig \| null`	no	Dashboard session only (ignored for API keys): try a ranking/synonym setup without saving it.

Responses

200Successful ResponseSearchResponse

GET/v1/recommend

Needs a key or a dashboard session

Parameters

Name	In	Type	Required	Description
`type`	`query`	`"similar" \| "also_viewed" \| "trending" \| "recently_viewed"`	yes
`product_id`	`query`	`string \| null`	no	max length 128
`category_id`	`query`	`string \| null`	no	max length 128
`session`	`query`	`string \| null`	no	max length 64
`limit`	`query`	`integer`	no	default 10 · min 1 · max 50

Responses

200Successful ResponseRecommendResponse

Data shapes on this page

SuggestResponse

Suggestions while typing. NEVER billed, never calls the AI.

Name	Type	Required
`query`	`string`	yes
`suggestions`	`Suggestion[]`	yes
`products`	`ProductCard[]`	no
`categories`	`FacetBucket[]`	no
`took_ms`	`number`	yes

Suggestion

Recent searches are NOT returned here: the widget keeps them in the shopper's browser only (localStorage, no server copy, no PII). See docs/adr/0012 and packages/widget/README.md.

Name	Type	Required	Description
`text`	`string`	yes
`highlighted`	`string \| null`	no
`kind`	`"query" \| "category" \| "brand"`	no	default "query"
`target`	`string \| null`	no	Category or brand id/url for kind=category\|brand.

ProductCard

Display fields. Connectors that render their own cards use only `id`.

Name	Type	Required
`id`	`string`	yes
`name`	`map<string, string>`	yes
`url`	`string \| null`	no
`image_url`	`string \| null`	no
`price`	`string`	yes
`sale_price`	`string \| null`	no
`currency`	`string`	yes
`in_stock`	`boolean`	yes
`brand`	`string \| null`	no
`category`	`map<string, string> \| null`	no

FacetBucket

Name	Type	Required
`value`	`string`	yes
`label`	`map<string, string> \| null`	no
`count`	`integer`	yes

SearchResponse

Name	Type	Required	Description
`search_id`	`string`	yes	Send it back with click/event calls to attribute them.
`query`	`ParsedQuery`	yes
`ids`	`string[]`	yes	Product ids in rank order (what connectors use).
`hits`	`SearchHit[]`	yes
`total`	`integer`	yes
`page`	`integer`	yes
`per_page`	`integer`	yes
`facets`	`Facet[]`	no
`did_you_mean`	`string \| null`	no
`redirect`	`Redirect \| null`	no
`banners`	`Banner[]`	no
`zero_result_help`	`ZeroResultHelp \| null`	no
`experiment`	`ExperimentAssignment \| null`	no
`took_ms`	`number`	yes
`debug`	`object \| null`	no

ParsedQuery

Name	Type	Required	Description
`text`	`string`	yes	As typed.
`normalized`	`string`	yes	After the Arabic layer.
`rewritten`	`string \| null`	no	After the rule parser or the AI rewrite.
`lang`	`string`	yes
`filters`	`object`	no	Filters the parser found, e.g. price_max 600.
`sort`	`string \| null`	no
`ai_used`	`boolean`	no	default false
`ai_cached`	`boolean`	no	default false

SearchHit

Name	Type	Required	Description
`id`	`string`	yes
`score`	`number \| null`	no
`product`	`ProductCard`	yes
`highlights`	`map<string, string>`	no
`pinned`	`boolean`	no	default false

Name	Type	Required
`name`	`string`	yes
`type`	`"terms" \| "range" \| "boolean" \| "category_tree"`	yes
`buckets`	`FacetBucket[]`	no
`min`	`number \| null`	no
`max`	`number \| null`	no

Redirect

Name	Type	Required	Description
`url`	`string`	yes
`rule_id`	`string`	yes

ZeroResultHelp

Name	Type	Required	Description
`relaxed`	`boolean`	yes	True when the results come from a relaxed query.
`relaxed_query`	`string \| null`	no
`popular_categories`	`FacetBucket[]`	no

ExperimentAssignment

Name	Type	Required	Description
`experiment_id`	`string`	yes
`variant`	`string`	yes

SearchRequest

POST /v1/search body. GET /v1/search takes the same fields as query parameters (filters as `filter[brand]=Lenovo&filter[price][lte]=600`).

Name	Type	Required	Description
`q`	`string`	no	max length 256
`lang`	`string`	no	`auto` or a tenant locale.default "auto" · pattern ^(auto\|[a-z]{2})$
`page`	`integer`	no	default 1 · min 1 · max 1000
`per_page`	`integer`	no	default 20 · min 1 · max 100
`filters`	`map<string, string[] \| RangeFilter \| string \| boolean>`	no	e.g. {"brand": ["Lenovo"], "price": {"lte": 600}, "in_stock": true}
`sort`	`"relevance" \| "price_asc" \| "price_desc" \| "newest" \| "popular"`	no	default "relevance"
`facets`	`string[]`	no	Facet names to return, e.g. brand, category, price.
`ai`	`"auto" \| "on" \| "off"`	no	auto = plan + tenant setting decide, and the AI runs only when it helps (price or use-case requests, long or unknown words, zero results); on = the AI on every query (plan and budget still apply); off = never call the AI.default "auto"
`session`	`string \| null`	no	Opaque shopper session id (no PII).max length 64
`device`	`"desktop" \| "mobile" \| "tablet" \| "unknown"`	no	default "unknown"
`debug`	`boolean`	no	Secret key or dashboard only: include the pipeline trace.default false
`config_override`	`RankingConfig \| null`	no	Dashboard session only (ignored for API keys): try a ranking/synonym setup without saving it.

RangeFilter

Name	Type	Required	Description
`gte`	`number \| null`	no
`lte`	`number \| null`	no

RankingConfig

One ranking setup, used by the dashboard playground (`SearchRequest.config_override`) and by A/B variants (`Variant.config`). Every field is optional: a missing field means "use the tenant's saved value" (`TenantSettings.search`, same field names). Nothing here is saved.

Name	Type	Required	Description
`ai_rewrite`	`boolean \| null`	no
`rule_parser`	`boolean \| null`	no
`in_stock_first`	`boolean \| null`	no
`business_signals`	`map<string, number> \| null`	no	Weights 0..1, e.g. {popularity: 0.2, margin: 0.1}. {} turns them all off.
`typo_tolerance`	`boolean \| null`	no
`hybrid_search`	`boolean \| null`	no
`cheap_rerank_top_n`	`integer \| null`	no	min 10 · max 200
`merch_rules`	`boolean \| null`	no	false = ignore all merchandising rules.
`disabled_rule_ids`	`string[] \| null`	no
`synonym_sets`	`string[] \| null`	no	Tenant synonym sets that are on. "default" is the normal set. Example A/B: A = ["default"], B = ["default", "winter-2026"].
`global_synonyms`	`boolean \| null`	no	false = ignore the platform's global synonyms.

RecommendResponse

Name	Type	Required
`type`	`"similar" \| "also_viewed" \| "trending" \| "recently_viewed"`	yes
`ids`	`string[]`	yes
`products`	`ProductCard[]`	yes
`source`	`"attributes" \| "vectors" \| "co_views" \| "popularity" \| "session"`	yes

Suggestions while typing (never billed)

Parameters

Responses

Search (GET form)

Parameters

Responses

Search (JSON body, complex filters)

Request body application/json SearchRequest

Responses

Recommendations

Parameters

Responses

Data shapes on this page

SuggestResponse

Suggestion

ProductCard

FacetBucket

SearchResponse

ParsedQuery

SearchHit

Facet

Redirect

Banner

ZeroResultHelp

ExperimentAssignment

SearchRequest

RangeFilter

RankingConfig

RecommendResponse

Request body `application/json` `SearchRequest`