{
"openapi": "3.0.0",
"paths": {
"/search": {
"get": {
"description": "Query the search engine using keyword, vector, or hybrid techniques. Requires a valid x-api-key.",
"operationId": "SearchController_search",
"parameters": [
{
"name": "q",
"required": false,
"in": "query",
"description": "Search query string",
"schema": {
"example": "shoes",
"type": "string"
}
},
{
"name": "category",
"required": false,
"in": "query",
"description": "Filter by category name",
"schema": {
"example": "Footwear",
"type": "string"
}
},
{
"name": "minPrice",
"required": false,
"in": "query",
"description": "Minimum price filter",
"schema": {
"example": 10,
"type": "number"
}
},
{
"name": "maxPrice",
"required": false,
"in": "query",
"description": "Maximum price filter",
"schema": {
"example": 200,
"type": "number"
}
},
{
"name": "tags",
"required": false,
"in": "query",
"description": "Filter by comma-separated tags",
"schema": {
"example": "sale,new",
"type": "string"
}
},
{
"name": "inStockOnly",
"required": false,
"in": "query",
"description": "Filter for only in-stock items",
"schema": {
"example": true,
"type": "boolean"
}
},
{
"name": "sortBy",
"required": false,
"in": "query",
"description": "Sort order (e.g. price:asc, price:desc)",
"schema": {
"example": "price:asc",
"type": "string"
}
},
{
"name": "page",
"required": false,
"in": "query",
"description": "Page number (1-indexed)",
"schema": {
"example": 1,
"type": "number"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"description": "Results per page",
"schema": {
"example": 20,
"type": "number"
}
},
{
"name": "searchType",
"required": false,
"in": "query",
"description": "Search retrieval strategy",
"schema": {
"enum": [
"keyword",
"vector",
"hybrid"
],
"type": "string"
}
},
{
"name": "storeView",
"required": false,
"in": "query",
"description": "Store view code or ID",
"schema": {
"example": "en",
"type": "string"
}
},
{
"name": "hasFilter",
"required": false,
"in": "query",
"description": "Whether to compute and return facet aggregations (default: true)",
"schema": {
"example": true,
"type": "boolean"
}
},
{
"name": "fields",
"in": "query",
"required": false,
"description": "Comma-separated product fields to return in hits (e.g. \"id,title,sku,price,imageUrl\"). Default: all",
"schema": {
"type": "string",
"example": "id,title,sku,price,imageUrl"
}
},
{
"name": "sessionId",
"in": "query",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\" (or header x-session-id)",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "userId",
"in": "query",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\" (or header x-user-id)",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "device",
"in": "query",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\" (or header x-device)",
"schema": {
"type": "string",
"example": "desktop"
}
},
{
"name": "x-api-key",
"in": "header",
"description": "NexorAIQ API Key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-session-id",
"in": "header",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\"",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "x-user-id",
"in": "header",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\"",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "x-device",
"in": "header",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\"",
"schema": {
"type": "string",
"example": "desktop"
}
}
],
"responses": {
"200": {
"description": "Search results returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"hits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "4efaacd9-8100-4998-83e6-cef4e7dfed64"
},
"title": {
"type": "string",
"example": "Apple iPhone 16 Pro 6.3-inch 512gb - Desert Titanium"
},
"description": {
"type": "string",
"example": "Product Details: Manufacturer: Apple, Color: Black"
},
"shortDescription": {
"type": "string",
"example": "Latest flagship smartphone"
},
"sku": {
"type": "string",
"example": "40007"
},
"price": {
"type": "number",
"example": 414.9
},
"regularPrice": {
"type": "number",
"example": 414.9
},
"specialPrice": {
"type": "number",
"example": 399.9
},
"currencyCode": {
"type": "string",
"example": "KWD"
},
"currencySymbol": {
"type": "string",
"example": "د.ك"
},
"imageUrl": {
"type": "string",
"example": "https://cdn.example.com/media/iphone16.webp"
},
"category": {
"type": "string",
"example": "Apple/Apple iPhone, Phones"
},
"inStock": {
"type": "boolean",
"example": true
},
"stockStatus": {
"type": "string",
"example": "in_stock"
},
"url": {
"type": "string",
"example": "apple-iphone-16-pro-512gb.html"
},
"manufacturer": {
"type": "string",
"example": "Apple"
},
"ratingSummary": {
"type": "number",
"example": 95
},
"reviewsCount": {
"type": "number",
"example": 12
},
"externalId": {
"type": "string",
"example": "1_en_17052"
},
"storeViewId": {
"type": "string",
"example": "1_en"
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"https://cdn.example.com/media/iphone16.webp"
]
},
"hoverImage": {
"type": "string",
"example": "https://cdn.example.com/media/iphone16-hover.webp"
}
}
}
},
"total": {
"type": "number",
"example": 83
},
"currentPage": {
"type": "number",
"example": 1
},
"totalPage": {
"type": "number",
"example": 21
},
"limit": {
"type": "number",
"example": 4
},
"search_time_ms": {
"type": "number",
"example": 12
},
"aggregations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"example": "categories"
},
"label": {
"type": "string",
"example": "Categories"
},
"type": {
"type": "string",
"example": "list"
},
"order": {
"type": "number",
"example": 1
},
"data": {
"type": "object"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request — check your query parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 400
},
"message": {
"type": "string",
"example": "Invalid search parameters"
},
"error": {
"type": "string",
"example": "Bad Request"
}
}
}
}
}
},
"401": {
"description": "Unauthorized — missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid or missing x-api-key header"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden — trial expired, domain/IP restriction, or scope error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 403
},
"message": {
"type": "string",
"example": "Trial expired. Please upgrade to a paid plan."
},
"error": {
"type": "string",
"example": "Forbidden"
}
}
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 404
},
"message": {
"type": "string",
"example": "Resource not found"
},
"error": {
"type": "string",
"example": "Not Found"
}
}
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 429
},
"message": {
"type": "string",
"example": "Rate limit exceeded. Please try again later."
},
"error": {
"type": "string",
"example": "Too Many Requests"
}
}
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 500
},
"message": {
"type": "string",
"example": "Internal server error"
},
"error": {
"type": "string",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"security": [
{
"ApiKey": []
}
],
"summary": "Full Search (GET)",
"tags": [
"Search"
]
},
"post": {
"description": "Query the search engine using keyword, vector, or hybrid techniques via POST JSON body. Requires a valid x-api-key.",
"operationId": "SearchController_searchPost",
"parameters": [
{
"name": "x-api-key",
"in": "header",
"description": "NexorAIQ API Key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-session-id",
"in": "header",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\"",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "x-user-id",
"in": "header",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\"",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "x-device",
"in": "header",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\"",
"schema": {
"type": "string",
"example": "desktop"
}
}
],
"requestBody": {
"required": true,
"description": "JSON request body payload for POST search request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "Search query string",
"example": "shoes"
},
"category": {
"type": "string",
"description": "Filter by category name",
"example": "Footwear"
},
"minPrice": {
"type": "number",
"description": "Minimum price filter",
"example": 10
},
"maxPrice": {
"type": "number",
"description": "Maximum price filter",
"example": 200
},
"tags": {
"type": "string",
"description": "Filter by comma-separated tags",
"example": "sale,new"
},
"inStockOnly": {
"type": "boolean",
"description": "Filter for only in-stock items",
"example": true
},
"sortBy": {
"type": "string",
"description": "Sort order (e.g. price:asc, price:desc)",
"example": "price:asc"
},
"page": {
"type": "number",
"description": "Page number (1-indexed)",
"example": 1
},
"limit": {
"type": "number",
"description": "Results per page",
"example": 20
},
"searchType": {
"type": "string",
"enum": [
"keyword",
"vector",
"hybrid"
],
"description": "Search retrieval strategy",
"example": "keyword"
},
"storeView": {
"type": "string",
"description": "Store view code or ID",
"example": "en"
},
"hasFilter": {
"type": "boolean",
"description": "Whether to compute and return facet aggregations (default: true)",
"example": true
},
"fields": {
"type": "string",
"description": "Comma-separated product fields to return in hits (e.g. \"id,title,sku,price,imageUrl\"). Default: all",
"example": "id,title,sku,price,imageUrl"
},
"sessionId": {
"type": "string",
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\" (or header x-session-id)",
"example": "sess_abc123"
},
"userId": {
"type": "string",
"description": "Customer account ID for shopper analytics. Default: \"shopper\" (or header x-user-id)",
"example": "usr_456"
},
"device": {
"type": "string",
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\" (or header x-device)",
"example": "desktop"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Search results returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"hits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "4efaacd9-8100-4998-83e6-cef4e7dfed64"
},
"title": {
"type": "string",
"example": "Apple iPhone 16 Pro 6.3-inch 512gb - Desert Titanium"
},
"description": {
"type": "string",
"example": "Product Details: Manufacturer: Apple, Color: Black"
},
"shortDescription": {
"type": "string",
"example": "Latest flagship smartphone"
},
"sku": {
"type": "string",
"example": "40007"
},
"price": {
"type": "number",
"example": 414.9
},
"regularPrice": {
"type": "number",
"example": 414.9
},
"specialPrice": {
"type": "number",
"example": 399.9
},
"currencyCode": {
"type": "string",
"example": "KWD"
},
"currencySymbol": {
"type": "string",
"example": "د.ك"
},
"imageUrl": {
"type": "string",
"example": "https://cdn.example.com/media/iphone16.webp"
},
"category": {
"type": "string",
"example": "Apple/Apple iPhone, Phones"
},
"inStock": {
"type": "boolean",
"example": true
},
"stockStatus": {
"type": "string",
"example": "in_stock"
},
"url": {
"type": "string",
"example": "apple-iphone-16-pro-512gb.html"
},
"manufacturer": {
"type": "string",
"example": "Apple"
},
"ratingSummary": {
"type": "number",
"example": 95
},
"reviewsCount": {
"type": "number",
"example": 12
},
"externalId": {
"type": "string",
"example": "1_en_17052"
},
"storeViewId": {
"type": "string",
"example": "1_en"
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"https://cdn.example.com/media/iphone16.webp"
]
},
"hoverImage": {
"type": "string",
"example": "https://cdn.example.com/media/iphone16-hover.webp"
}
}
}
},
"total": {
"type": "number",
"example": 83
},
"currentPage": {
"type": "number",
"example": 1
},
"totalPage": {
"type": "number",
"example": 21
},
"limit": {
"type": "number",
"example": 4
},
"search_time_ms": {
"type": "number",
"example": 12
},
"aggregations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"example": "categories"
},
"label": {
"type": "string",
"example": "Categories"
},
"type": {
"type": "string",
"example": "list"
},
"order": {
"type": "number",
"example": 1
},
"data": {
"type": "object"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request — check your parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 400
},
"message": {
"type": "string",
"example": "Invalid search parameters"
},
"error": {
"type": "string",
"example": "Bad Request"
}
}
}
}
}
},
"401": {
"description": "Unauthorized — missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid or missing x-api-key header"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden — trial expired, domain/IP restriction, or scope error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 403
},
"message": {
"type": "string",
"example": "Trial expired. Please upgrade to a paid plan."
},
"error": {
"type": "string",
"example": "Forbidden"
}
}
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 404
},
"message": {
"type": "string",
"example": "Resource not found"
},
"error": {
"type": "string",
"example": "Not Found"
}
}
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 429
},
"message": {
"type": "string",
"example": "Rate limit exceeded. Please try again later."
},
"error": {
"type": "string",
"example": "Too Many Requests"
}
}
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 500
},
"message": {
"type": "string",
"example": "Internal server error"
},
"error": {
"type": "string",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"security": [
{
"ApiKey": []
}
],
"summary": "Full Search (POST)",
"tags": [
"Search"
]
}
},
"/search/autocomplete": {
"get": {
"description": "Fetch autocomplete type-ahead suggestions for shoppers via GET query parameters. Requires a valid x-api-key.",
"operationId": "SearchController_autocomplete",
"parameters": [
{
"name": "q",
"required": true,
"in": "query",
"description": "The search term to autocomplete",
"schema": {
"example": "iph",
"type": "string"
}
},
{
"name": "type",
"required": false,
"in": "query",
"description": "Type of suggestions to return: query, brand, category, product, all, or comma-separated list (e.g. query,brand)",
"schema": {
"example": "query",
"type": "string"
}
},
{
"name": "storeView",
"required": false,
"in": "query",
"description": "Optional store view identifier",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"description": "Number of suggestions to return",
"schema": {
"example": 10,
"type": "number"
}
},
{
"name": "sessionId",
"in": "query",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\" (or header x-session-id)",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "userId",
"in": "query",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\" (or header x-user-id)",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "device",
"in": "query",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\" (or header x-device)",
"schema": {
"type": "string",
"example": "desktop"
}
},
{
"name": "x-api-key",
"in": "header",
"description": "NexorAIQ API Key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-session-id",
"in": "header",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\"",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "x-user-id",
"in": "header",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\"",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "x-device",
"in": "header",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\"",
"schema": {
"type": "string",
"example": "desktop"
}
}
],
"responses": {
"200": {
"description": "Autocomplete suggestions returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"example": "iph"
},
"search_time_ms": {
"type": "number",
"example": 6
},
"suggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"example": "iphone 16 pro"
},
"type": {
"type": "string",
"example": "query"
},
"weight": {
"type": "number",
"example": 980
},
"parts": {
"type": "object",
"properties": {
"before": {
"type": "string",
"example": ""
},
"match": {
"type": "string",
"example": "iph"
},
"after": {
"type": "string",
"example": "one 16 pro"
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request — check your parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 400
},
"message": {
"type": "string",
"example": "Invalid autocomplete parameters"
},
"error": {
"type": "string",
"example": "Bad Request"
}
}
}
}
}
},
"401": {
"description": "Unauthorized — missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid or missing x-api-key header"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden — trial expired, domain/IP restriction, or scope error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 403
},
"message": {
"type": "string",
"example": "Trial expired. Please upgrade to a paid plan."
},
"error": {
"type": "string",
"example": "Forbidden"
}
}
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 429
},
"message": {
"type": "string",
"example": "Rate limit exceeded"
},
"error": {
"type": "string",
"example": "Too Many Requests"
}
}
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 500
},
"message": {
"type": "string",
"example": "Internal server error"
},
"error": {
"type": "string",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"security": [
{
"ApiKey": []
}
],
"summary": "Auto Complete (GET)",
"tags": [
"Search"
]
},
"post": {
"description": "Fetch autocomplete type-ahead suggestions for shoppers via POST JSON body. Requires a valid x-api-key.",
"operationId": "SearchController_autocompletePost",
"parameters": [
{
"name": "x-api-key",
"in": "header",
"description": "NexorAIQ API Key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-session-id",
"in": "header",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\"",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "x-user-id",
"in": "header",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\"",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "x-device",
"in": "header",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\"",
"schema": {
"type": "string",
"example": "desktop"
}
}
],
"requestBody": {
"required": true,
"description": "JSON request body payload for POST autocomplete request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The search term to autocomplete",
"example": "iph"
},
"type": {
"type": "string",
"description": "Type of suggestions to return: query, brand, category, product, all, or comma-separated list",
"example": "query"
},
"storeView": {
"type": "string",
"description": "Optional store view identifier",
"example": "en"
},
"limit": {
"type": "number",
"description": "Number of suggestions to return",
"example": 10
},
"sessionId": {
"type": "string",
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\" (or header x-session-id)",
"example": "sess_abc123"
},
"userId": {
"type": "string",
"description": "Customer account ID for shopper analytics. Default: \"shopper\" (or header x-user-id)",
"example": "usr_456"
},
"device": {
"type": "string",
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\" (or header x-device)",
"example": "desktop"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Autocomplete suggestions returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"example": "iph"
},
"search_time_ms": {
"type": "number",
"example": 6
},
"suggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"example": "iphone 16 pro"
},
"type": {
"type": "string",
"example": "query"
},
"weight": {
"type": "number",
"example": 980
},
"parts": {
"type": "object",
"properties": {
"before": {
"type": "string",
"example": ""
},
"match": {
"type": "string",
"example": "iph"
},
"after": {
"type": "string",
"example": "one 16 pro"
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request — check your parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 400
},
"message": {
"type": "string",
"example": "Invalid autocomplete parameters"
},
"error": {
"type": "string",
"example": "Bad Request"
}
}
}
}
}
},
"401": {
"description": "Unauthorized — missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid or missing x-api-key header"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden — trial expired, domain/IP restriction, or scope error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 403
},
"message": {
"type": "string",
"example": "Trial expired. Please upgrade to a paid plan."
},
"error": {
"type": "string",
"example": "Forbidden"
}
}
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 429
},
"message": {
"type": "string",
"example": "Rate limit exceeded"
},
"error": {
"type": "string",
"example": "Too Many Requests"
}
}
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 500
},
"message": {
"type": "string",
"example": "Internal server error"
},
"error": {
"type": "string",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"security": [
{
"ApiKey": []
}
],
"summary": "Auto Complete (POST)",
"tags": [
"Search"
]
}
},
"/search/overlay": {
"get": {
"description": "Fetch rich search overlay suggestions, categories, brands, and top product matches via GET query parameters. Requires a valid x-api-key.",
"operationId": "SearchController_overlay",
"parameters": [
{
"name": "searchType",
"required": false,
"in": "query",
"description": "Search strategy (keyword, vector, hybrid)",
"schema": {
"type": "string"
}
},
{
"name": "sortBy",
"required": false,
"in": "query",
"description": "Sort order (e.g. price:asc, created_at:desc)",
"schema": {
"type": "string"
}
},
{
"name": "tags",
"required": false,
"in": "query",
"description": "Comma-separated tags",
"schema": {
"type": "string"
}
},
{
"name": "maxPrice",
"required": false,
"in": "query",
"description": "Maximum price filter",
"schema": {
"type": "number"
}
},
{
"name": "minPrice",
"required": false,
"in": "query",
"description": "Minimum price filter",
"schema": {
"type": "number"
}
},
{
"name": "categoryFilter",
"required": false,
"in": "query",
"description": "Filter products by category name",
"schema": {
"type": "string"
}
},
{
"name": "inStockOnly",
"required": false,
"in": "query",
"description": "Return only in-stock items",
"schema": {
"example": true,
"type": "boolean"
}
},
{
"name": "brandLimit",
"required": false,
"in": "query",
"description": "Maximum brand suggestions to return",
"schema": {
"example": 5,
"type": "number"
}
},
{
"name": "categoryLimit",
"required": false,
"in": "query",
"description": "Maximum category suggestions to return",
"schema": {
"example": 5,
"type": "number"
}
},
{
"name": "suggestionLimit",
"required": false,
"in": "query",
"description": "Maximum search suggestions to return",
"schema": {
"example": 5,
"type": "number"
}
},
{
"name": "brand",
"required": false,
"in": "query",
"description": "Include brand suggestions (true/false)",
"schema": {
"example": true,
"type": "boolean"
}
},
{
"name": "category",
"required": false,
"in": "query",
"description": "Include category suggestions (true/false)",
"schema": {
"example": true,
"type": "boolean"
}
},
{
"name": "suggestion",
"required": false,
"in": "query",
"description": "Include search suggestions (true/false)",
"schema": {
"example": true,
"type": "boolean"
}
},
{
"name": "limit",
"required": false,
"in": "query",
"description": "Number of top product matches to return",
"schema": {
"example": 5,
"type": "number"
}
},
{
"name": "storeView",
"required": false,
"in": "query",
"description": "Optional store view identifier",
"schema": {
"example": "en"
}
},
{
"name": "q",
"required": false,
"in": "query",
"description": "The search query term",
"schema": {
"example": "shoes"
}
},
{
"name": "sessionId",
"in": "query",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\" (or header x-session-id)",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "userId",
"in": "query",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\" (or header x-user-id)",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "device",
"in": "query",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\" (or header x-device)",
"schema": {
"type": "string",
"example": "desktop"
}
},
{
"name": "x-api-key",
"in": "header",
"description": "NexorAIQ API Key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-session-id",
"in": "header",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\"",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "x-user-id",
"in": "header",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\"",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "x-device",
"in": "header",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\"",
"schema": {
"type": "string",
"example": "desktop"
}
}
],
"responses": {
"200": {
"description": "Search overlay results returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "prod_45514"
},
"title": {
"type": "string",
"example": "Nike Air Max Running Shoes"
},
"sku": {
"type": "string",
"example": "NK-8821"
},
"price": {
"type": "number",
"example": 120
},
"regularPrice": {
"type": "number",
"example": 150
},
"specialPrice": {
"type": "number",
"example": 120
},
"currencySymbol": {
"type": "string",
"example": "$"
},
"imageUrl": {
"type": "string",
"example": "https://example.com/shoes.jpg"
},
"hoverImage": {
"type": "string",
"example": "https://example.com/shoes-side.jpg"
},
"inStock": {
"type": "boolean",
"example": true
},
"externalId": {
"type": "string",
"example": "en_us_1024"
}
}
}
},
"total": {
"type": "number",
"example": 42
},
"suggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"example": "running shoes men"
},
"type": {
"type": "string",
"example": "query"
},
"weight": {
"type": "number",
"example": 950
}
}
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Footwear/Running",
"Sports/Athletic"
]
},
"brands": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Nike",
"Adidas",
"Puma"
]
},
"search_time_ms": {
"type": "number",
"example": 8
}
}
}
}
}
},
"400": {
"description": "Bad Request — check your parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 400
},
"message": {
"type": "string",
"example": "Invalid overlay parameters"
},
"error": {
"type": "string",
"example": "Bad Request"
}
}
}
}
}
},
"401": {
"description": "Unauthorized — missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid or missing x-api-key header"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden — trial expired, domain/IP restriction, or scope error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 403
},
"message": {
"type": "string",
"example": "Trial expired. Please upgrade to a paid plan."
},
"error": {
"type": "string",
"example": "Forbidden"
}
}
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 429
},
"message": {
"type": "string",
"example": "Rate limit exceeded"
},
"error": {
"type": "string",
"example": "Too Many Requests"
}
}
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 500
},
"message": {
"type": "string",
"example": "Internal server error"
},
"error": {
"type": "string",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"security": [
{
"ApiKey": []
}
],
"summary": "Overlay Search (GET)",
"tags": [
"Search"
]
},
"post": {
"description": "Fetch rich search overlay suggestions, categories, brands, and top product matches via POST JSON body. Requires a valid x-api-key.",
"operationId": "SearchController_overlayPost",
"parameters": [
{
"name": "x-api-key",
"in": "header",
"description": "NexorAIQ API Key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-session-id",
"in": "header",
"required": false,
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\"",
"schema": {
"type": "string",
"example": "sess_abc123"
}
},
{
"name": "x-user-id",
"in": "header",
"required": false,
"description": "Customer account ID for shopper analytics. Default: \"shopper\"",
"schema": {
"type": "string",
"example": "usr_456"
}
},
{
"name": "x-device",
"in": "header",
"required": false,
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\"",
"schema": {
"type": "string",
"example": "desktop"
}
}
],
"requestBody": {
"required": true,
"description": "JSON request body payload for POST overlay search request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The search query term",
"example": "shoes"
},
"storeView": {
"type": "string",
"description": "Optional store view identifier",
"example": "en"
},
"limit": {
"type": "number",
"description": "Number of top product matches to return",
"example": 5
},
"suggestion": {
"type": "boolean",
"description": "Include search suggestions (true/false)",
"example": true
},
"category": {
"type": "boolean",
"description": "Include category suggestions (true/false)",
"example": true
},
"brand": {
"type": "boolean",
"description": "Include brand suggestions (true/false)",
"example": true
},
"suggestionLimit": {
"type": "number",
"description": "Maximum search suggestions to return",
"example": 5
},
"categoryLimit": {
"type": "number",
"description": "Maximum category suggestions to return",
"example": 5
},
"brandLimit": {
"type": "number",
"description": "Maximum brand suggestions to return",
"example": 5
},
"inStockOnly": {
"type": "boolean",
"description": "Return only in-stock items",
"example": true
},
"categoryFilter": {
"type": "string",
"description": "Filter products by category name"
},
"minPrice": {
"type": "number",
"description": "Minimum price filter"
},
"maxPrice": {
"type": "number",
"description": "Maximum price filter"
},
"tags": {
"type": "string",
"description": "Comma-separated tags"
},
"sortBy": {
"type": "string",
"description": "Sort order (e.g. price:asc, created_at:desc)"
},
"searchType": {
"type": "string",
"description": "Search strategy (keyword, vector, hybrid)",
"example": "keyword"
},
"sessionId": {
"type": "string",
"description": "Shopper session ID to link searches, clicks and conversions. Default: \"storefront-search\" (or header x-session-id)",
"example": "sess_abc123"
},
"userId": {
"type": "string",
"description": "Customer account ID for shopper analytics. Default: \"shopper\" (or header x-user-id)",
"example": "usr_456"
},
"device": {
"type": "string",
"description": "Shopper device: \"desktop\", \"mobile\" or \"tablet\". Default: \"storefront\" (or header x-device)",
"example": "desktop"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Search overlay results returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "prod_45514"
},
"title": {
"type": "string",
"example": "Nike Air Max Running Shoes"
},
"sku": {
"type": "string",
"example": "NK-8821"
},
"price": {
"type": "number",
"example": 120
},
"regularPrice": {
"type": "number",
"example": 150
},
"specialPrice": {
"type": "number",
"example": 120
},
"currencySymbol": {
"type": "string",
"example": "$"
},
"imageUrl": {
"type": "string",
"example": "https://example.com/shoes.jpg"
},
"hoverImage": {
"type": "string",
"example": "https://example.com/shoes-side.jpg"
},
"inStock": {
"type": "boolean",
"example": true
},
"externalId": {
"type": "string",
"example": "en_us_1024"
}
}
}
},
"total": {
"type": "number",
"example": 42
},
"suggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"example": "running shoes men"
},
"type": {
"type": "string",
"example": "query"
},
"weight": {
"type": "number",
"example": 950
}
}
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Footwear/Running",
"Sports/Athletic"
]
},
"brands": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Nike",
"Adidas",
"Puma"
]
},
"search_time_ms": {
"type": "number",
"example": 8
}
}
}
}
}
},
"400": {
"description": "Bad Request — check your parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 400
},
"message": {
"type": "string",
"example": "Invalid overlay parameters"
},
"error": {
"type": "string",
"example": "Bad Request"
}
}
}
}
}
},
"401": {
"description": "Unauthorized — missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid or missing x-api-key header"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden — trial expired, domain/IP restriction, or scope error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 403
},
"message": {
"type": "string",
"example": "Trial expired. Please upgrade to a paid plan."
},
"error": {
"type": "string",
"example": "Forbidden"
}
}
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 429
},
"message": {
"type": "string",
"example": "Rate limit exceeded"
},
"error": {
"type": "string",
"example": "Too Many Requests"
}
}
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 500
},
"message": {
"type": "string",
"example": "Internal server error"
},
"error": {
"type": "string",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"security": [
{
"ApiKey": []
}
],
"summary": "Overlay Search (POST)",
"tags": [
"Search"
]
}
},
"/search/products": {
"post": {
"description": "Ingest or update products in the search index. Send one product object, or an array / { products: [...] } of 1 to 50 products. Requires proper authentication.",
"operationId": "SearchController_indexProduct",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"externalId": {
"type": "string",
"example": "prod_123"
},
"title": {
"type": "string",
"example": "Wireless Headphones"
},
"description": {
"type": "string",
"example": "High fidelity noise-cancelling audio headphones"
},
"sku": {
"type": "string",
"example": "HP-123"
},
"price": {
"type": "number",
"example": 99.99
},
"compareAtPrice": {
"type": "number",
"example": 129.99
},
"inventory": {
"type": "number",
"example": 50
},
"imageUrl": {
"type": "string",
"example": "https://example.com/image.png"
},
"category": {
"type": "string",
"example": "Electronics"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"audio",
"wireless"
]
}
},
"required": [
"externalId",
"title",
"sku",
"price"
]
},
"examples": {
"single": {
"summary": "Single product",
"value": {
"externalId": "prod_123",
"title": "Wireless Headphones",
"sku": "HP-123",
"price": 99.99,
"inventory": 50
}
},
"batch": {
"summary": "Multiple products (max 50)",
"description": "Send { products: [...] } or a plain array. Returns { success, indexed, failed, errors }.",
"value": {
"products": [
{
"externalId": "prod_123",
"title": "Wireless Headphones",
"sku": "HP-123",
"price": 99.99,
"inventory": 50
},
{
"externalId": "prod_124",
"title": "Wireless Earbuds",
"sku": "EB-124",
"price": 59.99,
"inventory": 20
}
]
}
}
}
}
}
},
"responses": {
"201": {
"description": "Product indexed successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "prod_9012"
},
"tenantId": {
"type": "string",
"example": "tenant_abc123"
},
"externalId": {
"type": "string",
"example": "prod_123"
},
"title": {
"type": "string",
"example": "Men's Running Shoes"
},
"description": {
"type": "string",
"example": "High quality running shoes."
},
"sku": {
"type": "string",
"example": "RUN-SHOES-123"
},
"price": {
"type": "number",
"example": 89.99
},
"compareAtPrice": {
"type": "number",
"example": 109.99
},
"inventory": {
"type": "number",
"example": 50
},
"imageUrl": {
"type": "string",
"example": "https://example.com/image.png"
},
"category": {
"type": "string",
"example": "Footwear"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"sale",
"new-arrival"
]
},
"inStock": {
"type": "boolean",
"example": true
},
"storeViewId": {
"type": "string",
"example": "sv_default"
},
"storeViewCode": {
"type": "string",
"example": "default"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
}
},
"summary": "Index/Upsert Products",
"tags": [
"Search"
]
}
},
"/search/products/{id}": {
"delete": {
"description": "Remove a product from the database and the search index.",
"operationId": "SearchController_deleteProduct",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"description": "The unique identifier of the product to delete",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Product deleted successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
}
}
}
}
}
},
"401": {
"description": "Missing or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
}
},
"summary": "Delete a Product",
"tags": [
"Search"
]
}
},
"/analytics/search": {
"post": {
"description": "Record a search query event from your storefront for analytics tracking. No authentication required — uses tenant identification via x-api-key.",
"operationId": "AnalyticsController_logSearch",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"example": "wireless headphones"
},
"sessionId": {
"type": "string",
"example": "sess_abc123"
},
"userId": {
"type": "string",
"example": "user_456"
},
"resultsCount": {
"type": "number",
"example": 42
},
"tookMs": {
"type": "number",
"example": 18
},
"device": {
"type": "string",
"example": "mobile"
},
"storeView": {
"type": "string",
"example": "saudi_ar"
}
},
"required": [
"query",
"sessionId",
"resultsCount",
"tookMs"
]
}
}
}
},
"responses": {
"201": {
"description": "Search event logged successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"responseId": {
"type": "string",
"example": "138ec786-545e-4b98-8b0f-d715168b8020"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid API Key"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
}
},
"summary": "Log Search Event",
"tags": [
"Analytics"
]
}
},
"/analytics/event": {
"post": {
"description": "Record a storefront interaction event to feed your analytics dashboard. Supported values for `eventType`:\n* `CLICK`: Fired when a user clicks a product in search results. Requires `productId` and `query` (for keyword attribution).\n* `ADD_TO_CART`: Fired when a user adds a product found via search to their cart. Requires `productId` and `query`.\n* `CONVERSION`: Fired when a transaction is completed. Requires `productId`, `query`, and `revenue` (for revenue attribution and average order value calculations).\n* `SEARCH`: Fired when a search request occurs (alternative to the dedicated /analytics/search endpoint).\n\nNote: Telemetry events use storefront x-api-key headers for background tenant association.",
"operationId": "AnalyticsController_logEvent",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sessionId": {
"type": "string"
},
"userId": {
"type": "string"
},
"eventType": {
"type": "string",
"enum": [
"CLICK",
"SEARCH",
"CONVERSION",
"ADD_TO_CART",
"PAGE_VIEW"
]
},
"query": {
"type": "string"
},
"productId": {
"type": "string"
},
"productID": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"search",
"trending",
"default",
"merchandising"
],
"example": "search",
"description": "Where the shopper found the product. If empty: search when query is set, else default."
},
"revenue": {
"type": "number"
},
"currencyCode": {
"type": "string",
"example": "SAR"
},
"currency_code": {
"type": "string",
"example": "SAR"
},
"currency": {
"type": "string",
"example": "SAR"
},
"baseRevenue": {
"type": "number",
"example": 3.25
},
"base_revenue": {
"type": "number",
"example": 3.25
},
"baseCurrency": {
"type": "string",
"example": "KD"
},
"base_currency": {
"type": "string",
"example": "KD"
},
"baseCurrencyCode": {
"type": "string",
"example": "KWD"
},
"base_currency_code": {
"type": "string",
"example": "KWD"
},
"products": {
"type": "array",
"description": "Array of product objects for batch event logging. Each object requires productID/productId and optional revenue and currency fields.",
"items": {
"type": "object",
"properties": {
"productID": {
"type": "string"
},
"productId": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"search",
"trending",
"default",
"merchandising"
],
"example": "search",
"description": "Per-product source; overrides top-level. Where the shopper found the product. If empty: search when query is set, else default."
},
"revenue": {
"type": "number"
},
"currencyCode": {
"type": "string"
},
"currency_code": {
"type": "string"
},
"currency": {
"type": "string"
},
"baseRevenue": {
"type": "number"
},
"base_revenue": {
"type": "number"
},
"baseCurrency": {
"type": "string"
},
"base_currency": {
"type": "string"
},
"baseCurrencyCode": {
"type": "string"
},
"base_currency_code": {
"type": "string"
}
}
}
},
"device": {
"type": "string"
},
"storeView": {
"type": "string",
"example": "saudi_ar"
},
"storeViewId": {
"type": "string",
"example": "saudi_ar"
},
"store_view_id": {
"type": "string",
"example": "saudi_ar"
}
},
"required": [
"sessionId",
"eventType"
]
},
"examples": {
"CLICK": {
"summary": "CLICK Event Example (Single Product)",
"description": "Logged when a shopper clicks a single product in search results.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "CLICK",
"query": "wireless headphones",
"productId": "prod_789",
"storeView": "saudi_ar",
"device": "desktop"
}
},
"CLICK_MULTIPLE": {
"summary": "CLICK with Multiple Products (Batch)",
"description": "Logged when a shopper clicks multiple products in a batch from search results.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "CLICK",
"storeView": "saudi_ar",
"products": [
{
"query": "wireless headphones",
"productID": "prod_789"
},
{
"query": "wireless headphones",
"productID": "prod_101"
}
],
"device": "desktop"
}
},
"ADD_TO_CART": {
"summary": "ADD_TO_CART Event Example (Single Product)",
"description": "Logged when a shopper adds a single search result product to their cart.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "ADD_TO_CART",
"query": "wireless headphones",
"productId": "prod_789",
"storeView": "saudi_ar",
"device": "desktop"
}
},
"ADD_TO_CART_MULTIPLE": {
"summary": "ADD_TO_CART with Multiple Products (Batch)",
"description": "Logged when a shopper adds multiple products to cart in a batch.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "ADD_TO_CART",
"storeView": "saudi_ar",
"products": [
{
"query": "wireless headphones",
"productID": "prod_789"
},
{
"query": "wireless headphones",
"productID": "prod_101"
}
],
"device": "desktop"
}
},
"CONVERSION": {
"summary": "CONVERSION Event Example (Single Product)",
"description": "Logged when a shopper purchases a single product found via search.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "CONVERSION",
"query": "wireless headphones",
"productId": "prod_789",
"revenue": 40,
"currencyCode": "SAR",
"currency": "SAR",
"baseRevenue": 3.25,
"baseCurrency": "KD",
"baseCurrencyCode": "KWD",
"storeView": "saudi_ar",
"device": "desktop"
}
},
"CONVERSION_MULTIPLE": {
"summary": "CONVERSION with Multiple Products (Batch)",
"description": "Logged when a shopper purchases multiple products in a single order.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "CONVERSION",
"storeView": "saudi_ar",
"products": [
{
"query": "wireless headphones",
"productID": "prod_789",
"revenue": 40,
"currencyCode": "SAR",
"currency": "SAR",
"baseRevenue": 3.25,
"baseCurrency": "KD",
"baseCurrencyCode": "KWD"
},
{
"query": "wireless headphones",
"productID": "prod_101",
"revenue": 20,
"currencyCode": "SAR",
"currency": "SAR",
"baseRevenue": 1.62,
"baseCurrency": "KD",
"baseCurrencyCode": "KWD"
}
],
"device": "desktop"
}
},
"SEARCH": {
"summary": "SEARCH Event Example",
"description": "Alternative method to log search query events.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "SEARCH",
"query": "wireless headphones",
"storeView": "saudi_ar",
"device": "desktop"
}
},
"PAGE_VIEW": {
"summary": "PAGE_VIEW Event Example",
"description": "Logged when a shopper views a storefront page.",
"value": {
"sessionId": "sess_abc123",
"userId": "user_456",
"eventType": "PAGE_VIEW",
"query": "/bags/backpacks.html",
"storeView": "saudi_ar",
"device": "desktop"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Interaction event logged successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "evt_12345"
},
"tenantId": {
"type": "string",
"example": "tenant_abc123"
},
"sessionId": {
"type": "string",
"example": "sess_abc123"
},
"userId": {
"type": "string",
"example": "user_456"
},
"eventType": {
"type": "string",
"example": "CLICK"
},
"query": {
"type": "string",
"example": "wireless headphones"
},
"productId": {
"type": "string",
"example": "prod_789"
},
"revenue": {
"type": "number",
"example": 49.99
},
"createdAt": {
"type": "string",
"example": "2026-07-08T12:00:00.000Z"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid API Key"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
}
},
"summary": "Log Interaction Event",
"tags": [
"Analytics"
]
}
}
},
"info": {
"title": "NexorAIQ AI Search API",
"description": "Integrate blazing-fast, AI-powered product search into your e-commerce storefront with the NexorAIQ AI Search API. This reference covers everything you need to get up and running — from generating API keys to executing REST and GraphQL queries for full catalog search, type-ahead autocomplete, and rich search overlay.\n\n---\n\n## Getting Started\n\n### 1. Create Your Account\nSign up at [app.nexoraiq.tech](https://app.nexoraiq.tech) and complete the onboarding wizard to connect your store (Magento, Shopify, or custom catalog).\n\n### 2. Generate an API Key\nAPI keys authenticate your storefront requests and catalog ingestion calls.\n\nWhen you complete the account onboarding wizard at [app.nexoraiq.tech](https://app.nexoraiq.tech), two default API keys are **automatically created** for your tenant:\n* **Default Search-only Key (`key_search_...`)** — Pre-configured with read-only permissions (`search`, `suggestions`). Safe for client-side storefront JavaScript, web widgets, and mobile apps.\n* **Default Ingestion Key (`key_ingest_...`)** — Pre-configured with index write permissions (`index:read`, `index:write`). Used for server-side catalog synchronization, connectors, and webhooks.\n\n#### Key Types & Permissions:\n* **SEARCH (Search-only)** — Read-only, for storefront queries (`search`, `suggestions`). Recommended for client-side frontend code.\n* **INGEST (Scoped Ingestion)** — Write access (`index:read`, `index:write`), for catalog product sync and webhooks. Must be kept strictly server-side.\n* **ADMIN** — *(Coming Soon)* Full administrative access and key rotation.\n\nYou can view active keys, copy secrets, or generate additional keys in **[NexorAIQ Console → Developer Platform → API Keys](https://app.nexoraiq.tech/developers)**:\n\n![\"API](\"/images/api-keys-table.png\")
\n\n> **Security Note:** Never expose INGEST or secret keys in client-side storefront code. Always use SEARCH keys for frontend integrations and keep INGEST keys server-side only.\n\n### 3. Make Your First Request:\nInclude your API key in the `x-api-key` HTTP header:\n\n```bash\ncurl \"https://api.nexoraiq.tech/search?q=wireless+headphones\" \\\n -H \"x-api-key: key_search_gwxqcwz5slhniw7zba2g8\"\n```\n\n---\n\n## REST Search APIs\n\nNexorAIQ provides 3 high-speed endpoints for storefront search interactions:\n\n![\"Interactive](\"/images/api-explorer.png\")
\n\n### 1. Full Search\nExecutes full catalog searches using **keyword (BM25)**, **vector (semantic)**, or **hybrid (RRF)** search strategies. Supports filtering by category, price, tags, stock status, sorting, pagination, and dynamic facets/aggregations.\n\n#### Query Parameters:\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `q` | string | `\"\"` | Search query text |\n| `category` | string | `null` | Filter by category name |\n| `minPrice` | number | `null` | Minimum price filter |\n| `maxPrice` | number | `null` | Maximum price filter |\n| `tags` | string | `null` | Comma-separated tags |\n| `inStockOnly` | boolean | `false` | Return only in-stock items |\n| `sortBy` | string | `null` | Sort order (e.g. `price:asc`, `price:desc`, `created_at:desc`) |\n| `page` | number | `1` | Page number (1-indexed) |\n| `limit` | number | `20` | Results per page |\n| `searchType` | string | `hybrid` | Search strategy: `keyword`, `vector`, or `hybrid` |\n| `storeView` | string | `null` | Store view code or ID |\n| `hasFilter` | boolean | `true` | Compute and include faceted aggregations in response |\n\n#### REST Example:\n```bash\ncurl \"https://api.nexoraiq.tech/search?q=shoes&category=Footwear&minPrice=20&maxPrice=150&inStockOnly=true&sortBy=price:asc&searchType=hybrid\" \\\n -H \"x-api-key: niq_sk_your_api_key_here\"\n```\n\n---\n\n### 2. Auto Complete\nProvides fast, real-time query completion and keyword suggestions as shoppers type in the search box.\n\n#### Query Parameters:\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `q` | string | *(required)* | Partial query string typed by shopper |\n| `type` | string | `query` | Suggestion type: `query`, `brand`, `category`, `product`, `all`, or comma-separated list |\n| `storeView` | string | `null` | Optional store view identifier |\n| `limit` | number | `10` | Maximum suggestions to return (max 20) |\n\n#### REST Example:\n```bash\ncurl \"https://api.nexoraiq.tech/search/autocomplete?q=iph&type=query&limit=10\" \\\n -H \"x-api-key: niq_sk_your_api_key_here\"\n```\n\n---\n\n### 3. Overlay Search\nFetches a single composite payload for storefront search dropdowns/overlays containing top product matches, search suggestions, matching categories, and matching brands.\n\n#### Query Parameters:\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `q` | string | `\"\"` | Search query term |\n| `storeView` | string | `null` | Store view identifier |\n| `limit` | number | `5` | Top product matches to return |\n| `suggestion` | boolean | `true` | Include search query suggestions |\n| `category` | boolean | `true` | Include matching category suggestions |\n| `brand` | boolean | `true` | Include matching brand suggestions |\n| `suggestionLimit` | number | `5` | Maximum search suggestions to return |\n| `categoryLimit` | number | `5` | Maximum categories to return |\n| `brandLimit` | number | `5` | Maximum brands to return |\n| `inStockOnly` | boolean | `false` | Return only in-stock items |\n| `categoryFilter` | string | `null` | Filter products by category name |\n| `minPrice` | number | `null` | Minimum price filter |\n| `maxPrice` | number | `null` | Maximum price filter |\n| `tags` | string | `null` | Comma-separated tags |\n| `sortBy` | string | `null` | Sort order (e.g. `price:asc`) |\n| `searchType` | string | `keyword` | Search strategy (`keyword`, `vector`, `hybrid`) |\n\n#### REST Example:\n```bash\ncurl \"https://api.nexoraiq.tech/search/overlay?q=shoes&limit=5&suggestionLimit=5&categoryLimit=5&brandLimit=5\" \\\n -H \"x-api-key: niq_sk_your_api_key_here\"\n```\n\n---\n\n## GraphQL API\n\nNexorAIQ exposes a high-performance GraphQL endpoint at `/graphql`. You can authenticate using the same `x-api-key` header. Use the **[GraphQL Explorer](/graphql)** for interactive testing — select any operation, edit variables, and run queries directly from your browser.\n\n**Quick access:** [Search Catalog](/graphql?op=searchCatalog) · [Autocomplete](/graphql?op=autocomplete) · [Search Overlay](/graphql?op=overlay) · [Index Product](/graphql?op=indexProduct) · [Log Search Event](/graphql?op=logSearch) · [Click Event](/graphql?op=logEventClick) · [Add to Cart Event](/graphql?op=logEventAddToCart) · [Conversion Event](/graphql?op=logEventConversion) · [Search Interaction](/graphql?op=logEventSearch)\n\n### Endpoint URL\n\n```\nPOST https://api.nexoraiq.tech/graphql\n```\n\n### 1. Full Search\n\n```graphql\nquery LiveCatalogSearch {\n searchCatalog(\n query: \"iphone\"\n storeCode: \"en\"\n page: 1\n perPage: 10\n searchType: hybrid\n hasFilter: true\n ) {\n total_found\n search_time_ms\n responseId\n redirected\n destinationUrl\n hits {\n id\n sku\n name\n title\n price\n regular_price\n special_price\n discount_percent\n stock_status\n inventory\n imageUrl\n externalId\n storeViewCode\n }\n aggregations {\n key\n label\n type\n order\n data\n }\n }\n}\n```\n\n[→ Try Search Catalog in Explorer](/graphql?op=searchCatalog)\n\n---\n\n### 2. Auto Complete\n\n```graphql\nquery LiveAutocomplete {\n autocomplete(\n query: \"iph\"\n storeCode: \"en\"\n type: \"query\"\n limit: 10\n ) {\n query\n search_time_ms\n responseId\n redirected\n destinationUrl\n suggestions {\n text\n type\n source\n volume\n weight\n parts {\n before\n match\n after\n }\n redirected\n destinationUrl\n }\n }\n}\n```\n\n[→ Try Autocomplete in Explorer](/graphql?op=autocomplete)\n\n---\n\n### 3. Overlay Search\n\n```graphql\nquery LiveSearchOverlay {\n overlay(\n query: \"shoes\"\n storeCode: \"en\"\n searchType: keyword\n limit: 5\n suggestion: true\n category: true\n brand: true\n suggestionLimit: 5\n categoryLimit: 5\n brandLimit: 5\n ) {\n total\n search_time_ms\n responseId\n redirected\n destinationUrl\n products {\n id\n sku\n name\n title\n price\n regular_price\n special_price\n discount_percent\n stock_status\n inventory\n imageUrl\n hover_image\n externalId\n }\n suggestions {\n text\n type\n weight\n }\n categories\n brands\n }\n}\n```\n\n[→ Try Search Overlay in Explorer](/graphql?op=overlay)\n\n---\n\n### 4. Index Product\n\n```graphql\nmutation IngestProduct {\n indexProduct(\n externalId: \"en_us_1024\"\n title: \"Luma Sports Duffel Bag\"\n sku: \"24-MB01\"\n price: 34.00\n inventory: 15\n imageUrl: \"https://example.com/bag.jpg\"\n category: \"Gear/Bags\"\n tags: [\"bags\", \"fitness\"]\n ) {\n success\n message\n }\n}\n```\n\n[→ Try Index Product in Explorer](/graphql?op=indexProduct)\n\n---\n\n### 5. Log Search\n\n```graphql\nmutation LogSearchTelemetry {\n logSearch(\n query: \"wireless headphones\"\n sessionId: \"sess_abc123\"\n resultsCount: 42\n tookMs: 18\n device: \"mobile\"\n ) {\n success\n responseId\n }\n}\n```\n\n[→ Try Log Search Event in Explorer](/graphql?op=logSearch)\n\n---\n\n### 6. Log Events\n\nLog storefront interaction events across all 4 event types (`CLICK`, `ADD_TO_CART`, `CONVERSION`, `SEARCH`):\n\n#### 6.1 CLICK Event Mutation\nLog when a shopper clicks products in search results (supports Single Product or Multiple Products batch):\n\n##### A. Single Product Click Mutation\n```graphql\nmutation LogClickInteraction {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CLICK\n query: \"backpack\"\n productId: \"prod_789\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n productId\n createdAt\n }\n}\n```\n\n[→ Try Log Click Event in Explorer](/graphql?op=logEventClick)\n\n##### B. Multiple Products (Batch) Click Mutation\n```graphql\nmutation LogBatchClickInteraction {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CLICK\n storeView: \"saudi_ar\"\n products: [\n { query: \"backpack\", productId: \"prod_789\" },\n { query: \"backpack\", productId: \"prod_101\" }\n ]\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n count\n createdAt\n }\n}\n```\n\n[→ Try Log Batch Click Event in Explorer](/graphql?op=logEventClickBatch)\n\n#### 6.2 ADD_TO_CART Event Mutation\nLog when a shopper adds products to cart from search results (supports Single Product or Multiple Products batch):\n\n##### A. Single Product Add To Cart Mutation\n```graphql\nmutation LogAddToCartInteraction {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: ADD_TO_CART\n query: \"backpack\"\n productId: \"prod_789\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n productId\n createdAt\n }\n}\n```\n\n[→ Try Log Add To Cart Event in Explorer](/graphql?op=logEventAddToCart)\n\n##### B. Multiple Products (Batch) Add To Cart Mutation\n```graphql\nmutation LogBatchAddToCartInteraction {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: ADD_TO_CART\n storeView: \"saudi_ar\"\n products: [\n { query: \"backpack\", productId: \"prod_789\" },\n { query: \"backpack\", productId: \"prod_101\" }\n ]\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n count\n createdAt\n }\n}\n```\n\n[→ Try Log Batch Add To Cart Event in Explorer](/graphql?op=logEventAddToCartBatch)\n\n#### 6.3 CONVERSION Event Mutation\nLog when a shopper completes a purchase with itemized product revenue (supports Single Product or Multiple Products batch):\n\n##### A. Single Product Conversion Mutation\n```graphql\nmutation LogSingleConversionInteraction {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CONVERSION\n query: \"backpack\"\n productId: \"prod_789\"\n revenue: 40.00\n currencyCode: \"SAR\"\n currency: \"SAR\"\n baseRevenue: 3.25\n baseCurrency: \"KD\"\n baseCurrencyCode: \"KWD\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n productId\n revenue\n currencyCode\n currency\n baseRevenue\n baseCurrency\n baseCurrencyCode\n createdAt\n }\n}\n```\n\n[→ Try Log Conversion Event in Explorer](/graphql?op=logEventConversion)\n\n##### B. Multiple Products (Batch) Conversion Mutation\n```graphql\nmutation LogBatchConversionInteraction {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CONVERSION\n storeView: \"saudi_ar\"\n products: [\n {\n query: \"backpack\"\n productId: \"prod_789\"\n revenue: 40\n currencyCode: \"SAR\"\n currency: \"SAR\"\n baseRevenue: 3.25\n baseCurrency: \"KD\"\n baseCurrencyCode: \"KWD\"\n },\n {\n query: \"backpack\"\n productId: \"prod_101\"\n revenue: 20\n currencyCode: \"SAR\"\n currency: \"SAR\"\n baseRevenue: 1.62\n baseCurrency: \"KD\"\n baseCurrencyCode: \"KWD\"\n }\n ]\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n count\n createdAt\n }\n}\n```\n\n[→ Try Log Batch Conversion Event in Explorer](/graphql?op=logEventConversionBatch)\n\n#### 6.4 SEARCH Event Mutation\nLog search query interaction event for analytics:\n\n```graphql\nmutation LogSearchInteraction {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: SEARCH\n query: \"backpack\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n createdAt\n }\n}\n```\n\n[→ Try Log Search Interaction in Explorer](/graphql?op=logEventSearch)\n\n---\n\n## Authentication\n\nAll API requests require authentication. You must provide your NexorAIQ API Key in the `x-api-key` HTTP header with every request:\n\n| Header Name | Example Format | Best For |\n|-------------|----------------|----------|\n| `x-api-key` | `niq_sk_live_abc123...` | Storefront search, autocomplete, overlay, and catalog ingestion requests |\n\nExample Request\n\n\n```bash\ncurl -X GET \"https://api.nexoraiq.tech/search?q=shoes\" \\\n -H \"x-api-key: niq_sk_your_api_key_here\"\n```\n\n---\n\n## Base URL\n\nAll API requests should be made to:\n\n```\nhttps://api.nexoraiq.tech\n```\n\n---\n\n## Access Control Policy\n\nNexorAIQ provides origin and IP restriction policies to protect your search index, analytics streams, and webhooks against unauthorized usage and API key theft.\n\nConfigure and manage security policies in **[NexorAIQ Console → Developer Platform → Access Control](https://app.nexoraiq.tech/developers)**.\n\n### 1. Whitelisted Domains (CORS)\nRestricts browser-based storefront API calls (`/search`, `/search/autocomplete`, `/search/overlay`) to authorized client domains. Blocks unauthorized third-party sites from querying your index.\n* **Syntax Examples**: `example.com`, `*.example.com`, `registerdomain.com`\n\n![\"Whitelisted](\"/images/whitelisted-domains.png\")
\n\n---\n\n### 2. Whitelisted IPs & CIDRs\nRestricts server-to-server API calls, catalog sync jobs, and incoming webhooks to trusted backend IP addresses or subnets.\n* **Syntax Examples**: `203.0.113.10`, `192.168.1.0/24`, `182.22.23.234`\n\n![\"Whitelisted](\"/images/whitelisted-ips.png\")
\n\n---\n\n### 3. Developer IPs (Bypass)\nUnconditionally overrides domain and IP restrictions for specified developer machine IPs. Allows team members to test APIs locally or via Postman without altering production whitelists.\n* **Syntax Examples**: `203.0.113.20`, `127.0.0.1`, `273.23.23.278`\n\n![\"Developer](\"/images/developer-ips.png\")
\n\n---\n\n### 4. Live Policy Simulator\nThe **Live Policy Simulator** allows developers to test and verify whether any incoming origin domain or client IP address will be **ALLOWED**, **BYPASSED**, or **BLOCKED (403 Forbidden)** under active rules before deploying changes to production.\n\n#### A. Domain Whitelist Verification (ALLOWED)\nWhen testing a whitelisted origin domain (e.g. `registerdomain.com`), the simulator confirms `ALLOWED` status and highlights the matching domain rule:\n\n![\"Simulator](\"/images/simulator-allowed-domain.png\")
\n\n#### B. Unauthorized Domain Block (403 Forbidden)\nWhen an unlisted domain attempts a request, the simulator shows `BLOCKED (403)` along with the restriction reason:\n\n![\"Simulator](\"/images/simulator-blocked-domain.png\")
\n\n#### C. Whitelisted IP Verification (ALLOWED)\nWhen testing a explicitly whitelisted IP address (e.g. `203.0.113.10`), the simulator verifies that server-to-server requests are `ALLOWED`:\n\n![\"Simulator](\"/images/simulator-allowed-ip.png\")
\n\n#### D. Unauthorized IP Restriction (403 Forbidden)\nWhen testing an unlisted client IP (e.g. `203.0.113.11`), the simulator verifies that request execution will be rejected with `BLOCKED (403)`:\n\n![\"Simulator](\"/images/simulator-blocked-ip.png\")
\n\n#### E. Developer IP Bypass Verification (BYPASSED)\nWhen testing a developer machine IP (e.g. `203.0.113.20`), the simulator verifies that all domain and IP restrictions are `BYPASSED (ALLOWED)` for local testing:\n\n![\"Simulator](\"/images/simulator-bypassed-ip.png\")
\n\n---\n\n## Search Retrieval Strategies\n\nNexorAIQ supports three search retrieval strategies:\n\n| Type | Description | Best For |\n|------|-------------|----------|\n| `keyword` | Traditional full-text search using BM25 ranking | Exact product names, SKUs |\n| `vector` | AI-powered semantic search using embeddings | Natural language queries |\n| `hybrid` | Combines keyword + vector results with RRF fusion | **Recommended default** — best overall relevance |\n\nPass the `searchType` query parameter to choose a strategy:\n\n```\nGET /search?q=comfortable+running+shoes&searchType=hybrid\n```\n\n---\n\n## Filtering & Parameters\n\nAll search APIs support both **GET** (query parameters) and **POST** (JSON request body).\n\n### 1. Full Search\n\n| Parameter | Type | Default / Example | Description |\n|-----------|------|-------------------|-------------|\n| `q` | string | `\"\"` | Search query text |\n| `category` | string | `null` | Filter by category name |\n| `minPrice` | number | `null` | Minimum price filter |\n| `maxPrice` | number | `null` | Maximum price filter |\n| `tags` | string | `null` | Comma-separated tags (e.g. `sale,new-arrival`) |\n| `inStockOnly` | boolean | `false` | Return only in-stock items |\n| `sortBy` | string | `null` | Sort order (e.g. `price:asc`, `price:desc`, `created_at:desc`) |\n| `page` | number | `1` | Page number (1-indexed) |\n| `limit` | number | `20` | Results per page (max 100) |\n| `searchType` | string | `hybrid` | Search strategy: `keyword`, `vector`, or `hybrid` |\n| `storeView` | string | `null` | Multi-store view code or ID |\n| `hasFilter` | boolean | `true` | Compute and return dynamic facet aggregations |\n\n---\n\n### 2. Auto Complete\n\n| Parameter | Type | Default / Example | Description |\n|-----------|------|-------------------|-------------|\n| `q` | string | *(required)* | Partial query string typed by shopper |\n| `type` | string | `query` | Suggestion type: `query`, `brand`, `category`, `product`, `all` |\n| `storeView` | string | `null` | Store view code or ID |\n| `limit` | number | `10` | Maximum suggestions to return (max 20) |\n\n---\n\n### 3. Overlay Search\n\n| Parameter | Type | Default / Example | Description |\n|-----------|------|-------------------|-------------|\n| `q` | string | `\"\"` | Search query term |\n| `storeView` | string | `null` | Store view code or ID |\n| `limit` | number | `5` | Top product matches to return |\n| `suggestion` | boolean | `true` | Include search query suggestions (`true`/`false`) |\n| `category` | boolean | `true` | Include matching category suggestions (`true`/`false`) |\n| `brand` | boolean | `true` | Include matching brand suggestions (`true`/`false`) |\n| `suggestionLimit` | number | `5` | Maximum search suggestions to return |\n| `categoryLimit` | number | `5` | Maximum category suggestions to return |\n| `brandLimit` | number | `5` | Maximum brand suggestions to return |\n| `inStockOnly` | boolean | `false` | Return only in-stock items (`true`/`false`) |\n| `categoryFilter` | string | `null` | Filter products by category name |\n| `minPrice` | number | `null` | Minimum price filter |\n| `maxPrice` | number | `null` | Maximum price filter |\n| `tags` | string | `null` | Comma-separated tags |\n| `sortBy` | string | `null` | Sort order (e.g. `price:asc`, `created_at:desc`) |\n| `searchType` | string | `keyword` | Search strategy: `keyword`, `vector`, or `hybrid` |\n\n---\n\n### 4. Analytics & Events\n\n| Parameter | Type | Required / Default | Value to Pass & Description |\n|-----------|------|-------------------|-----------------------------|\n| `sessionId` | string | *(required)* | **Shopper Session ID**: Unique session identifier (e.g., `sess_abc123` or browser cookie/session ID). Must be maintained across search, click, cart, and checkout actions to correlate user journey flow. |\n| `eventType` | string | *(required for `/analytics/event`)* | **Interaction Event Type**: Type of storefront interaction event. Allowed values: `SEARCH`, `CLICK`, `ADD_TO_CART`, `CONVERSION`, `PAGE_VIEW`. |\n| `productId` | string | Required (`CLICK`, `ADD_TO_CART`, `CONVERSION`) | **Product Identifier**: Pass the **`externalId`** (or product `id`) obtained directly from Search API (`hits[].externalId` or `products[].externalId`). |\n| `products` | array | Optional (Batch Mode) | **Batch Product Array**: Array of itemized product objects for logging multiple products in a single API call (e.g., multi-item checkout, multi-add to cart). Each item contains `productID`/`productId`, `query`, `revenue`, `currencyCode`, `baseRevenue`, `baseCurrency`, and `baseCurrencyCode`. |\n| `query` | string | Recommended | **Search Query Text**: The exact search query term typed by the shopper (e.g., `wireless headphones`). Used to compute search keyword conversion rates and revenue attribution. |\n| `revenue` | number | Required (`CONVERSION`) | **Local Product Revenue**: Monetary purchase amount in shopper's local currency (e.g., `40.00`). Used to calculate search-generated sales revenue and AOV. |\n| `currencyCode` | string | Optional (e.g. `SAR`) | **Local Currency Code**: 3-letter ISO code for the local transaction currency (e.g., `SAR`, `USD`, `AED`). Defaults to `SAR`. |\n| `currency` | string | Optional (e.g. `SAR`) | **Local Currency Symbol / Code**: Alias for `currencyCode` (e.g., `SAR` or `$`). |\n| `baseRevenue` | number | Optional (e.g. `3.25`) | **Base Store Revenue**: Converted revenue in the default store base currency (e.g., `3.25` for Magento primary store currency KWD). Fallbacks to `revenue` if omitted. |\n| `baseCurrency` | string | Optional (e.g. `KD`) | **Base Currency Symbol**: Symbol for default store base currency (e.g., `KD` or `KWD`). Fallbacks to `currencyCode` if omitted. |\n| `baseCurrencyCode` | string | Optional (e.g. `KWD`) | **Base Currency Code**: 3-letter ISO code for default store base currency (e.g., `KWD`). Fallbacks to `currencyCode` if omitted. |\n| `storeView` | string | `null` (Optional, e.g. `en`, `ar`, `saudi_ar`, `default`) | **Store View Code**: Store view or language code. Maps to multi-store catalog views and multi-currency settings. |\n| `userId` | string | `null` (Optional) | **Customer Account ID**: Unique ID of logged-in customer (e.g., `user_456`). Enables cross-session customer lifecycle tracking. |\n| `device` | string | `desktop` (Optional) | **Client Device Environment**: Device or platform type (e.g., `desktop`, `mobile`, `tablet`, `ios`, `android`). |\n| `resultsCount` | number | Required (`/analytics/search`) | **Search Results Count**: Total hit count returned in Search API response (`total_found`). Used for zero-result query tracking. |\n| `tookMs` | number | Required (`/analytics/search`) | **Search Latency**: Server execution time in milliseconds (`search_time_ms`). Used to monitor engine performance. |\n\n#### Batch Logging & Multi-Currency Architecture\n* **Single Request Efficiency**: Instead of dispatching $N$ separate HTTP requests for multi-item checkouts or multi-product cart additions, storefronts send a single payload with a `products` array containing all itemized products.\n* **Consolidated API Response**: NexorAIQ ingests all itemized products in parallel into ClickHouse and returns a clean, consolidated response with `count: N` and `createdAt` timestamp.\n* **Automatic Multi-Currency Fallback**: When operating multi-storefronts (e.g. a Saudi store view pricing in SAR while the Magento default store operates in KWD), send local `revenue`/`currencyCode` alongside `baseRevenue`/`baseCurrencyCode`. If base fields are missing, NexorAIQ automatically fallbacks base values to local revenue and currency.\n\n---\n\n## Analytics & Events\n\nNexorAIQ captures storefront interaction events and streams live HTTP request telemetry to help developers verify query execution, analyze latency, and debug status codes.\n\n### 1. Real-Time API Logs\nAll incoming storefront search requests (`GET /search`, `POST /graphql`) emit real-time Server-Sent Event (SSE) telemetry logs. Developers can inspect live request streams to verify API latency (`search_time_ms`), result hit counts, HTTP response status codes (`200 OK`, `403 Forbidden`), client origin domains, and developer IP bypass status.\n\n![\"Live](\"/images/live-api-logs.png\")
\n\n#### Live Log Telemetry Attributes:\n* **Timestamp**: Exact server execution time for each incoming request.\n* **HTTP Method & Endpoint**: Request method (`GET`, `POST`) and endpoint path (`/search`, `/graphql`).\n* **Result Summary**: Catalog match count returned by the engine (e.g. `40 results`, `523 results`, `0 results`).\n* **HTTP Status Code**: Immediate status response code (`200 OK`, `403 Forbidden`, `429 Rate Limited`).\n* **Latency**: End-to-end server execution and query latency in milliseconds (`6ms`, `30ms`, `246ms`).\n\n---\n\n### 2. SEARCH Event\nLogged when a user executes a search request.\n* **GraphQL Mutation**:\n ```graphql\n mutation {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: SEARCH\n query: \"backpack\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n eventType\n createdAt\n }\n }\n ```\n* **REST Payload (`POST /analytics/event`)**:\n ```json\n {\n \"eventType\": \"SEARCH\",\n \"sessionId\": \"sess_abc123\",\n \"query\": \"backpack\",\n \"storeView\": \"saudi_ar\",\n \"device\": \"desktop\"\n }\n ```\n* **Sample Response (Success)**:\n ```json\n {\n \"id\": \"evt_search_9988\",\n \"tenantId\": \"tenant_abc123\",\n \"sessionId\": \"sess_abc123\",\n \"eventType\": \"SEARCH\",\n \"query\": \"backpack\",\n \"createdAt\": \"2026-07-09T11:00:00.000Z\"\n }\n ```\n\n---\n\n### 3. CLICK Event\nLogged when a shopper clicks on a product from search results. Supports both **Single Product** (via top-level `productId`) and **Multiple Products** (via `products` array).\n\n> **Parameter Note:** Set `productId` = `externalId` obtained from Search API response (`hits[].externalId` or `products[].externalId`).\n\n#### A. Single Product Click\n\n* **GraphQL Mutation**:\n ```graphql\n mutation LogSingleClick {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CLICK\n query: \"backpack\"\n productId: \"prod_789\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n productId\n createdAt\n }\n }\n ```\n* **REST Payload (`POST /analytics/event`)**:\n ```json\n {\n \"eventType\": \"CLICK\",\n \"sessionId\": \"sess_abc123\",\n \"query\": \"backpack\",\n \"productId\": \"prod_789\",\n \"storeView\": \"saudi_ar\",\n \"device\": \"desktop\"\n }\n ```\n* **Sample Response (Success)**:\n ```json\n {\n \"id\": \"evt_click_1122\",\n \"tenantId\": \"tenant_abc123\",\n \"sessionId\": \"sess_abc123\",\n \"eventType\": \"CLICK\",\n \"query\": \"backpack\",\n \"productId\": \"prod_789\",\n \"createdAt\": \"2026-07-09T11:01:00.000Z\"\n }\n ```\n\n#### B. Multiple Products (Batch) Click\n\n* **GraphQL Mutation**:\n ```graphql\n mutation LogBatchClick {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CLICK\n storeView: \"saudi_ar\"\n products: [\n { query: \"backpack\", productId: \"prod_789\" },\n { query: \"backpack\", productId: \"prod_101\" }\n ]\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n count\n createdAt\n }\n }\n ```\n* **REST Payload (`POST /analytics/event`)**:\n ```json\n {\n \"eventType\": \"CLICK\",\n \"sessionId\": \"sess_abc123\",\n \"storeView\": \"saudi_ar\",\n \"products\": [\n { \"query\": \"backpack\", \"productId\": \"prod_789\" },\n { \"query\": \"backpack\", \"productId\": \"prod_101\" }\n ],\n \"device\": \"desktop\"\n }\n ```\n* **Sample Response (Success)**:\n ```json\n {\n \"id\": \"evt_click_1122\",\n \"tenantId\": \"tenant_abc123\",\n \"sessionId\": \"sess_abc123\",\n \"eventType\": \"CLICK\",\n \"count\": 2,\n \"createdAt\": \"2026-07-09T11:01:00.000Z\"\n }\n ```\n\n---\n\n### 4. ADD_TO_CART Event\nLogged when a shopper adds search results to their cart. Supports both **Single Product** (via top-level `productId`) and **Multiple Products** (via `products` array).\n\n> **Parameter Note:** Set `productId` = `externalId` obtained from Search API response (`hits[].externalId` or `products[].externalId`).\n\n#### A. Single Product Add to Cart\n\n* **GraphQL Mutation**:\n ```graphql\n mutation LogSingleAddToCart {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: ADD_TO_CART\n query: \"backpack\"\n productId: \"prod_789\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n productId\n createdAt\n }\n }\n ```\n* **REST Payload (`POST /analytics/event`)**:\n ```json\n {\n \"eventType\": \"ADD_TO_CART\",\n \"sessionId\": \"sess_abc123\",\n \"query\": \"backpack\",\n \"productId\": \"prod_789\",\n \"storeView\": \"saudi_ar\",\n \"device\": \"desktop\"\n }\n ```\n* **Sample Response (Success)**:\n ```json\n {\n \"id\": \"evt_cart_3344\",\n \"tenantId\": \"tenant_abc123\",\n \"sessionId\": \"sess_abc123\",\n \"eventType\": \"ADD_TO_CART\",\n \"query\": \"backpack\",\n \"productId\": \"prod_789\",\n \"createdAt\": \"2026-07-09T11:02:00.000Z\"\n }\n ```\n\n#### B. Multiple Products (Batch) Add to Cart\n\n* **GraphQL Mutation**:\n ```graphql\n mutation LogBatchAddToCart {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: ADD_TO_CART\n storeView: \"saudi_ar\"\n products: [\n { query: \"backpack\", productId: \"prod_789\" },\n { query: \"backpack\", productId: \"prod_101\" }\n ]\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n count\n createdAt\n }\n }\n ```\n* **REST Payload (`POST /analytics/event`)**:\n ```json\n {\n \"eventType\": \"ADD_TO_CART\",\n \"sessionId\": \"sess_abc123\",\n \"storeView\": \"saudi_ar\",\n \"products\": [\n { \"query\": \"backpack\", \"productId\": \"prod_789\" },\n { \"query\": \"backpack\", \"productId\": \"prod_101\" }\n ],\n \"device\": \"desktop\"\n }\n ```\n* **Sample Response (Success)**:\n ```json\n {\n \"id\": \"evt_cart_3344\",\n \"tenantId\": \"tenant_abc123\",\n \"sessionId\": \"sess_abc123\",\n \"eventType\": \"ADD_TO_CART\",\n \"count\": 2,\n \"createdAt\": \"2026-07-09T11:02:00.000Z\"\n }\n ```\n\n---\n\n### 5. CONVERSION Event\nLogged when a transaction is completed. Attributes order revenue to keywords and search sessions. Supports both **Single Product** (via top-level `productId` & `revenue`) and **Multiple Products** (via `products` array).\n\n> **Parameter Note:** Set `productId` = `externalId` obtained from Search API response (`hits[].externalId` or `products[].externalId`) and `revenue` = purchase dollar amount.\n\n#### A. Single Product Conversion\n\n* **GraphQL Mutation**:\n ```graphql\n mutation LogSingleConversion {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CONVERSION\n query: \"backpack\"\n productId: \"prod_789\"\n revenue: 40.00\n currencyCode: \"SAR\"\n currency: \"SAR\"\n baseRevenue: 3.25\n baseCurrency: \"KD\"\n baseCurrencyCode: \"KWD\"\n storeView: \"saudi_ar\"\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n productId\n revenue\n currencyCode\n currency\n baseRevenue\n baseCurrency\n baseCurrencyCode\n createdAt\n }\n }\n ```\n* **REST Payload (`POST /analytics/event`)**:\n ```json\n {\n \"eventType\": \"CONVERSION\",\n \"sessionId\": \"sess_abc123\",\n \"query\": \"backpack\",\n \"productId\": \"prod_789\",\n \"revenue\": 40.00,\n \"currencyCode\": \"SAR\",\n \"currency\": \"SAR\",\n \"baseRevenue\": 3.25,\n \"baseCurrency\": \"KD\",\n \"baseCurrencyCode\": \"KWD\",\n \"storeView\": \"saudi_ar\",\n \"device\": \"desktop\"\n }\n ```\n* **Sample REST Response**:\n ```json\n {\n \"id\": \"evt_conv_5566\",\n \"tenantId\": \"tenant_abc123\",\n \"sessionId\": \"sess_abc123\",\n \"eventType\": \"CONVERSION\",\n \"query\": \"backpack\",\n \"productId\": \"prod_789\",\n \"revenue\": 40.00,\n \"createdAt\": \"2026-07-09T11:03:00.000Z\"\n }\n ```\n\n#### B. Multiple Products (Batch) Conversion\n\n* **GraphQL Mutation**:\n ```graphql\n mutation LogBatchConversion {\n logEvent(\n sessionId: \"sess_abc123\"\n eventType: CONVERSION\n storeView: \"saudi_ar\"\n products: [\n {\n query: \"backpack\"\n productId: \"prod_789\"\n revenue: 40\n currencyCode: \"SAR\"\n currency: \"SAR\"\n baseRevenue: 3.25\n baseCurrency: \"KD\"\n baseCurrencyCode: \"KWD\"\n },\n {\n query: \"backpack\"\n productId: \"prod_101\"\n revenue: 20\n currencyCode: \"SAR\"\n currency: \"SAR\"\n baseRevenue: 1.62\n baseCurrency: \"KD\"\n baseCurrencyCode: \"KWD\"\n }\n ]\n device: \"desktop\"\n ) {\n id\n responseId\n eventType\n count\n createdAt\n }\n }\n ```\n* **REST Payload (`POST /analytics/event`)**:\n ```json\n {\n \"eventType\": \"CONVERSION\",\n \"sessionId\": \"sess_abc123\",\n \"storeView\": \"saudi_ar\",\n \"products\": [\n {\n \"query\": \"backpack\",\n \"productId\": \"prod_789\",\n \"revenue\": 40,\n \"currencyCode\": \"SAR\",\n \"currency\": \"SAR\",\n \"baseRevenue\": 3.25,\n \"baseCurrency\": \"KD\",\n \"baseCurrencyCode\": \"KWD\"\n },\n {\n \"query\": \"backpack\",\n \"productId\": \"prod_101\",\n \"revenue\": 20,\n \"currencyCode\": \"SAR\",\n \"currency\": \"SAR\",\n \"baseRevenue\": 1.62,\n \"baseCurrency\": \"KD\",\n \"baseCurrencyCode\": \"KWD\"\n }\n ],\n \"device\": \"desktop\"\n }\n ```\n* **Sample REST Response**:\n ```json\n {\n \"id\": \"evt_conv_5566\",\n \"tenantId\": \"tenant_abc123\",\n \"sessionId\": \"sess_abc123\",\n \"eventType\": \"CONVERSION\",\n \"count\": 2,\n \"createdAt\": \"2026-07-09T11:03:00.000Z\"\n }\n ```\n\nThese events power the analytics dashboard in your NexorAIQ console — including search volume, conversion funnels, top queries, and zero-result tracking.\n\n\n---\n\n## Rate Limits\n\n| Plan | API Rate Limit | Searches/month |\n|------|----------------|----------------|\n| **Starter** | 50 RPS (3,000 req/min) | 100K (100,000) |\n| **Growth** | 80 RPS (4,800 req/min) | 1M (1,000,000) |\n| **Professional** | 100 RPS (6,000 req/min) | 15M (15,000,000) |\n| **Enterprise** | Custom | Custom |\n\nRate-limited requests return HTTP `429` with a `Retry-After` header.\n\n---\n\n## Error Handling\n\nAll errors follow a consistent JSON format:\n\n```json\n{\n \"statusCode\": 403,\n \"message\": \"This request's origin domain is not whitelisted for API access.\",\n \"error\": \"Forbidden\"\n}\n```\n\n### Debugging 403 Forbidden & Access Restrictions\n\nWhen an API request fails with `403 Forbidden` due to an unlisted origin domain or unauthorized client IP address, the **Live API Log Details Drawer** provides detailed diagnostic trace information:\n\n![\"Live](\"/images/live-log-details-403.png\")
\n\n### Diagnostic Details Included:\n* **Error Message & Reason**: Exact cause of failure (e.g. `\"This request's origin domain is not whitelisted for API access.\"`).\n* **Troubleshooting Guidance**: Direct steps for adding client domains or IPs under Access Control settings.\n* **Request Metadata**: Request Origin (`http://localhost:3000`), Client IP (`::1`), Query String (`q=backpack&page=1&limit=4`), and Search Mode (`Keyword`, `Vector`, `Hybrid`).\n\n| Status | Meaning |\n|--------|---------|\n| `200` | Success |\n| `201` | Created (for POST operations) |\n| `400` | Bad request — check your parameters |\n| `401` | Unauthorized — invalid or missing API key |\n| `403` | Forbidden — trial expired, domain/IP restriction, or scope error |\n| `404` | Resource not found |\n| `429` | Rate limit exceeded |\n| `500` | Internal server error |\n\n---\n\n## Need Help?\n\n- 📧 Email: [support@nexoraiq.tech](mailto:support@nexoraiq.tech)\n- 💬 Dashboard: [app.nexoraiq.tech](https://app.nexoraiq.tech)\n- 📖 Changelog: Check the dashboard for the latest updates\n\n---\n",
"version": "1.0 (latest)",
"contact": {}
},
"tags": [
{
"name": "Search",
"description": "Execute storefront queries, index product catalogs, or delete products. All search actions support full-text keyword matching, semantic vector search, or hybrid retrieval. These operations are also accessible via GraphQL."
},
{
"name": "Analytics",
"description": "Log real-time storefront telemetry events (searches, product clicks, cart additions, conversions) to feed the NexorAIQ analytics dashboard. These operations are also accessible via GraphQL."
}
],
"servers": [
{
"url": "https://api.nexoraiq.tech",
"description": "NexorAIQ API Server"
}
],
"components": {
"securitySchemes": {
"ApiKey": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "NexorAIQ API Key — generate from Settings → API Keys in your dashboard"
}
},
"schemas": {}
},
"externalDocs": {
"description": "NexorAIQ Console",
"url": "https://app.nexoraiq.tech"
}
}