Search · مرجع الواجهة البرمجية

4 نقاط وصول. أسماء نقاط الوصول وأوصافها مأخوذة من ملف OpenAPI، لذلك تظهر بالإنجليزية.

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

GET/v1/suggest

Suggestions while typing (never billed)

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`q`	`query`	`string`	نعم	max length 128
`lang`	`query`	`string`	لا	`auto` or a tenant locale. · default "auto" · pattern ^(auto\|[a-z]{2})$
`limit`	`query`	`integer`	لا	default 8 · min 1 · max 20
`products`	`query`	`integer`	لا	How many product previews to include. · default 4 · min 0 · max 10
`session`	`query`	`string \| null`	لا	max length 64

الردود

200Successful ResponseSuggestResponse

GET/v1/search

Search (GET form)

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

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

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`q`	`query`	`string`	لا	max length 256
`lang`	`query`	`string`	لا	`auto` or a tenant locale. · default "auto" · pattern ^(auto\|[a-z]{2})$
`page`	`query`	`integer`	لا	default 1 · min 1 · max 1000
`per_page`	`query`	`integer`	لا	default 20 · min 1 · max 100
`sort`	`query`	`"relevance" \| "price_asc" \| "price_desc" \| "newest" \| "popular"`	لا	default "relevance"
`facets`	`query`	`string \| null`	لا	Comma-separated facet names.
`ai`	`query`	`"auto" \| "on" \| "off"`	لا	default "auto"
`session`	`query`	`string \| null`	لا	max length 64
`device`	`query`	`"desktop" \| "mobile" \| "tablet" \| "unknown"`	لا	default "unknown"

الردود

200Successful ResponseSearchResponse

POST/v1/search

Search (JSON body, complex filters)

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

جسم الطلب `application/json` `SearchRequest`

الاسم	النوع	إلزامي	الوصف
`q`	`string`	لا	max length 256
`lang`	`string`	لا	`auto` or a tenant locale.default "auto" · pattern ^(auto\|[a-z]{2})$
`page`	`integer`	لا	default 1 · min 1 · max 1000
`per_page`	`integer`	لا	default 20 · min 1 · max 100
`filters`	`map<string, string[] \| RangeFilter \| string \| boolean>`	لا	e.g. {"brand": ["Nike"], "price": {"lte": 100}, "in_stock": true}
`sort`	`"relevance" \| "price_asc" \| "price_desc" \| "newest" \| "popular"`	لا	default "relevance"
`facets`	`string[]`	لا	Facet names to return, e.g. brand, category, price.
`ai`	`"auto" \| "on" \| "off"`	لا	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`	لا	Opaque shopper session id (no PII).max length 64
`device`	`"desktop" \| "mobile" \| "tablet" \| "unknown"`	لا	default "unknown"
`debug`	`boolean`	لا	Secret key or dashboard only: include the pipeline trace.default false
`config_override`	`RankingConfig \| null`	لا	Dashboard session only (ignored for API keys): try a ranking/synonym setup without saving it.

الردود

200Successful ResponseSearchResponse

GET/v1/recommend

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`type`	`query`	`"similar" \| "also_viewed" \| "trending" \| "recently_viewed"`	نعم
`product_id`	`query`	`string \| null`	لا	max length 128
`category_id`	`query`	`string \| null`	لا	max length 128
`session`	`query`	`string \| null`	لا	max length 64
`limit`	`query`	`integer`	لا	default 10 · min 1 · max 50

الردود

200Successful ResponseRecommendResponse

أشكال البيانات في هذه الصفحة

SuggestResponse

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

الاسم	النوع	إلزامي
`query`	`string`	نعم
`suggestions`	`Suggestion[]`	نعم
`products`	`ProductCard[]`	لا
`categories`	`FacetBucket[]`	لا
`took_ms`	`number`	نعم

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.

الاسم	النوع	إلزامي	الوصف
`text`	`string`	نعم
`highlighted`	`string \| null`	لا
`kind`	`"query" \| "category" \| "brand"`	لا	default "query"
`target`	`string \| null`	لا	Category or brand id/url for kind=category\|brand.

ProductCard

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

الاسم	النوع	إلزامي
`id`	`string`	نعم
`name`	`map<string, string>`	نعم
`url`	`string \| null`	لا
`image_url`	`string \| null`	لا
`price`	`string`	نعم
`sale_price`	`string \| null`	لا
`currency`	`string`	نعم
`in_stock`	`boolean`	نعم
`brand`	`string \| null`	لا
`category`	`map<string, string> \| null`	لا

FacetBucket

الاسم	النوع	إلزامي
`value`	`string`	نعم
`label`	`map<string, string> \| null`	لا
`count`	`integer`	نعم

SearchResponse

الاسم	النوع	إلزامي	الوصف
`search_id`	`string`	نعم	Send it back with click/event calls to attribute them.
`query`	`ParsedQuery`	نعم
`ids`	`string[]`	نعم	Product ids in rank order (what connectors use).
`hits`	`SearchHit[]`	نعم
`total`	`integer`	نعم
`page`	`integer`	نعم
`per_page`	`integer`	نعم
`facets`	`Facet[]`	لا
`did_you_mean`	`string \| null`	لا
`redirect`	`Redirect \| null`	لا
`banners`	`Banner[]`	لا
`zero_result_help`	`ZeroResultHelp \| null`	لا
`experiment`	`ExperimentAssignment \| null`	لا
`took_ms`	`number`	نعم
`debug`	`object \| null`	لا

ParsedQuery

الاسم	النوع	إلزامي	الوصف
`text`	`string`	نعم	As typed.
`normalized`	`string`	نعم	After the Arabic layer.
`rewritten`	`string \| null`	لا	After the rule parser or the AI rewrite.
`lang`	`string`	نعم
`filters`	`object`	لا	Filters the parser found, e.g. price_max 600.
`sort`	`string \| null`	لا
`ai_used`	`boolean`	لا	default false
`ai_cached`	`boolean`	لا	default false

SearchHit

الاسم	النوع	إلزامي	الوصف
`id`	`string`	نعم
`score`	`number \| null`	لا
`product`	`ProductCard`	نعم
`highlights`	`map<string, string>`	لا
`pinned`	`boolean`	لا	default false

الاسم	النوع	إلزامي
`name`	`string`	نعم
`type`	`"terms" \| "range" \| "boolean" \| "category_tree"`	نعم
`buckets`	`FacetBucket[]`	لا
`min`	`number \| null`	لا
`max`	`number \| null`	لا

Redirect

الاسم	النوع	إلزامي	الوصف
`url`	`string`	نعم
`rule_id`	`string`	نعم

ZeroResultHelp

الاسم	النوع	إلزامي	الوصف
`relaxed`	`boolean`	نعم	True when the results come from a relaxed query.
`relaxed_query`	`string \| null`	لا
`popular_categories`	`FacetBucket[]`	لا

ExperimentAssignment

الاسم	النوع	إلزامي	الوصف
`experiment_id`	`string`	نعم
`variant`	`string`	نعم

SearchRequest

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

الاسم	النوع	إلزامي	الوصف
`q`	`string`	لا	max length 256
`lang`	`string`	لا	`auto` or a tenant locale.default "auto" · pattern ^(auto\|[a-z]{2})$
`page`	`integer`	لا	default 1 · min 1 · max 1000
`per_page`	`integer`	لا	default 20 · min 1 · max 100
`filters`	`map<string, string[] \| RangeFilter \| string \| boolean>`	لا	e.g. {"brand": ["Nike"], "price": {"lte": 100}, "in_stock": true}
`sort`	`"relevance" \| "price_asc" \| "price_desc" \| "newest" \| "popular"`	لا	default "relevance"
`facets`	`string[]`	لا	Facet names to return, e.g. brand, category, price.
`ai`	`"auto" \| "on" \| "off"`	لا	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`	لا	Opaque shopper session id (no PII).max length 64
`device`	`"desktop" \| "mobile" \| "tablet" \| "unknown"`	لا	default "unknown"
`debug`	`boolean`	لا	Secret key or dashboard only: include the pipeline trace.default false
`config_override`	`RankingConfig \| null`	لا	Dashboard session only (ignored for API keys): try a ranking/synonym setup without saving it.

RangeFilter

الاسم	النوع	إلزامي	الوصف
`gte`	`number \| null`	لا
`lte`	`number \| null`	لا

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.

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

RecommendResponse

الاسم	النوع	إلزامي
`type`	`"similar" \| "also_viewed" \| "trending" \| "recently_viewed"`	نعم
`ids`	`string[]`	نعم
`products`	`ProductCard[]`	نعم
`source`	`"attributes" \| "vectors" \| "co_views" \| "popularity" \| "session"`	نعم

Suggestions while typing (never billed)

المعاملات

الردود

Search (GET form)

المعاملات

الردود

Search (JSON body, complex filters)

جسم الطلب application/json SearchRequest

الردود

Recommendations

المعاملات

الردود

أشكال البيانات في هذه الصفحة

SuggestResponse

Suggestion

ProductCard

FacetBucket

SearchResponse

ParsedQuery

SearchHit

Facet

Redirect

Banner

ZeroResultHelp

ExperimentAssignment

SearchRequest

RangeFilter

RankingConfig

RecommendResponse

جسم الطلب `application/json` `SearchRequest`