InsightSearch 索引查询 API 文档

将 InsightSearch API 集成到您的电商平台的完整指南。支持查询参数以 query string 形式与请求体 JSON 对象两种传参方式。

接口概览

方法	POST
路径	/1/indexes/{indexName}/query
Base URL 示例	https://insight.prophetes.ai（scheme / host / port 可配置）
完整 URL 示例	https://insight.prophetes.ai/1/indexes/test_product/query

Demo 下载

下载我们的官方 Demo，快速将 Insight 搜索集成到您的应用中：

使用 java.net.http.HttpClient，无第三方依赖

下载 Demo

鉴权

请求头需携带以下信息：

Header	说明
`x-insight-application-id`	应用 ID
`x-insight-api-key`	API Key（需具备 search 权限）
`Content-Type`	application/json

请求体格式

参数以 Query String 形式（params 字符串）

请求体为 JSON，仅包含 params 字段，值为 URL 编码的查询参数字符串：

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

多个参数用 & 连接，需做 URL 编码。

参数以 JSON 对象形式

请求体为 JSON 对象，键为参数名：

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

搜索参数

参数	类型	必填	默认值	说明
`query`	string	是	-	搜索查询文本
`page`	integer	否	1	当前页码
`hitsPerPage`	integer	否	12	每页返回结果数量

更多参数（如 filters、attributesToRetrieve 等）若服务端支持可一并传入。

响应结构

成功时 HTTP 状态码 2xx，响应体为 JSON，示例：

{
  "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：总命中数
data.page / data.hitsPerPage：当前页、每页条数
data.hits：当前页命中列表，每项含 id、score、source 等

示例代码

cURL（JSON 对象传参）

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 为 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"}'