InsightSearch Index Query API Documentation

Complete guide to integrating InsightSearch API into your e-commerce platform. Supports both query string parameters and JSON request body formats.

API Overview

Method	POST
Path	/1/indexes/{indexName}/query
Base URL Example	https://insight.prophetes.ai (scheme / host / port configurable)
Full URL Example	https://insight.prophetes.ai/1/indexes/test_product/query

Demo Download

Download our official Demos to quickly integrate Insight Search into your application:

Python Demo

Uses standard library urllib with no additional dependencies

Download Demo

Java Demo

Uses java.net.http.HttpClient with no third-party dependencies

Download Demo

Authentication

Request headers must include:

Header	Description
`x-insight-application-id`	Application ID
`x-insight-api-key`	API Key (requires search permission)
`Content-Type`	application/json

Request Body Format

Parameters as Query String (params string)

Request body is JSON containing only the params field, with URL-encoded query parameter string:

{
  "params": "query=sofa&page=1&hitsPerPage=10"
}

Multiple parameters connected with &, URL encoding required.

Parameters as JSON Object

Request body is a JSON object with parameter names as keys:

{
  "query": "sofa",
  "page": 1,
  "hitsPerPage": 10
}

Search Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	Search query text
`page`	integer	No	1	Current page number
`hitsPerPage`	integer	No	12	Number of results per page

Additional parameters (such as filters, attributesToRetrieve, etc.) can be included if supported by the server.

Response Structure

Success returns HTTP status code 2xx with JSON response body, example:

{
  "msg": "ok",
  "code": 200,
  "data": {
    "query": "sofa",
    "indexUse": "test_product",
    "recallSource": ["fullTextSearch", "semanticSearch"],
    "nbHits": 96,
    "page": 1,
    "hitsPerPage": 12,
    "serverTimeMS": 1019,
    "processingTimeMS": 1019,
    "hits": [
      {
        "id": "2519",
        "score": 0.629,
        "source": {
          "id": 2519,
          "sku": "iD6-0020",
          "title": "...",
          "product_name": "..."
        }
      }
    ]
  }
}

data.nbHits: Total number of hits
data.page / data.hitsPerPage: Current page and results per page
data.hits: Current page hit list, each item contains id, score, source, etc.

Examples

cURL (JSON Object Parameters)

curl "https://insight.prophetes.ai/1/indexes/test_product/query" \
  -X POST \
  -H "x-insight-application-id: YOUR_APPLICATION_ID" \
  -H "x-insight-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"sofa","page":1,"hitsPerPage":12}'

cURL (params as query string)

curl "https://insight.prophetes.ai/1/indexes/test_product/query" \
  -X POST \
  -H "x-insight-application-id: YOUR_APPLICATION_ID" \
  -H "x-insight-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":"query=sofa&page=1&hitsPerPage=12"}'