Skip to main content
POST
/
v1
/
search
Search
curl --request POST \
  --url https://api.neuronsearchlab.com/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "waterproof trail shoes",
  "user_id": "usr_abc123",
  "context_id": "101",
  "limit": "10",
  "filter": [
    "category:footwear"
  ]
}
'
{
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "/v1/search",
  "data": [
    {
      "id": "rec_itm_7f3a2c9e",
      "item_id": "itm_7f3a2c9e",
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": "itm_7f3a2c9e",
        "name": "Wireless Headphones",
        "description": "Noise-cancelling Bluetooth headphones.",
        "metadata": {
          "category": "electronics",
          "brand": "Acme",
          "price": 10999,
          "currency": "usd"
        }
      },
      "entity_id": "itm_7f3a2c9e",
      "name": "Wireless Headphones",
      "description": "Noise-cancelling Bluetooth headphones.",
      "metadata": {
        "category": "electronics",
        "brand": "Acme",
        "price": 10999,
        "currency": "usd"
      },
      "source": "model",
      "explanation": {
        "item_id": "<string>",
        "rank": 123,
        "summary": "<string>",
        "shown_because": [
          "<string>"
        ],
        "source": "<string>",
        "score": {
          "final": 123,
          "base": 123,
          "cosine_distance": 123,
          "retrieval": 123,
          "ranker": 123
        },
        "context": {
          "context_id": "<string>",
          "filters": [
            {}
          ],
          "request_filters": [
            {
              "column": "<string>",
              "operator": "<string>",
              "value": "<string>"
            }
          ],
          "group_by": [
            "<string>"
          ],
          "exclude_viewed_items": {
            "value": 123,
            "unit": "<string>",
            "interval": "<string>"
          },
          "auto_section": {
            "section_id": "<string>",
            "title": "<string>",
            "subtitle": "<string>",
            "reason": {}
          }
        },
        "embedding": {},
        "pipeline": {
          "id": 123,
          "stages": [
            {
              "stage": "<string>",
              "enabled": true,
              "status": "<string>",
              "pipeline_id": 123,
              "config": {},
              "note": "<string>",
              "item_events": [
                {}
              ]
            }
          ]
        },
        "rules": [
          {}
        ],
        "experiments": [
          {
            "experiment_id": 123,
            "experiment_name": "<string>",
            "variant_id": 123,
            "variant_name": "<string>"
          }
        ],
        "user_segments": [
          "<string>"
        ]
      }
    }
  ],
  "recommendations": [
    {
      "id": "rec_itm_7f3a2c9e",
      "item_id": "itm_7f3a2c9e",
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": "itm_7f3a2c9e",
        "name": "Wireless Headphones",
        "description": "Noise-cancelling Bluetooth headphones.",
        "metadata": {
          "category": "electronics",
          "brand": "Acme",
          "price": 10999,
          "currency": "usd"
        }
      },
      "entity_id": "itm_7f3a2c9e",
      "name": "Wireless Headphones",
      "description": "Noise-cancelling Bluetooth headphones.",
      "metadata": {
        "category": "electronics",
        "brand": "Acme",
        "price": 10999,
        "currency": "usd"
      },
      "source": "model",
      "explanation": {
        "item_id": "<string>",
        "rank": 123,
        "summary": "<string>",
        "shown_because": [
          "<string>"
        ],
        "source": "<string>",
        "score": {
          "final": 123,
          "base": 123,
          "cosine_distance": 123,
          "retrieval": 123,
          "ranker": 123
        },
        "context": {
          "context_id": "<string>",
          "filters": [
            {}
          ],
          "request_filters": [
            {
              "column": "<string>",
              "operator": "<string>",
              "value": "<string>"
            }
          ],
          "group_by": [
            "<string>"
          ],
          "exclude_viewed_items": {
            "value": 123,
            "unit": "<string>",
            "interval": "<string>"
          },
          "auto_section": {
            "section_id": "<string>",
            "title": "<string>",
            "subtitle": "<string>",
            "reason": {}
          }
        },
        "embedding": {},
        "pipeline": {
          "id": 123,
          "stages": [
            {
              "stage": "<string>",
              "enabled": true,
              "status": "<string>",
              "pipeline_id": 123,
              "config": {},
              "note": "<string>",
              "item_events": [
                {}
              ]
            }
          ]
        },
        "rules": [
          {}
        ],
        "experiments": [
          {
            "experiment_id": 123,
            "experiment_name": "<string>",
            "variant_id": 123,
            "variant_name": "<string>"
          }
        ],
        "user_segments": [
          "<string>"
        ]
      }
    }
  ],
  "has_more": true,
  "next_cursor": "<string>",
  "limit": 50,
  "quantity": 1,
  "processing_time_ms": 1,
  "query": "waterproof trail shoes",
  "message": "Search results fetched",
  "embedding_info": {
    "used_default": true,
    "default_reason": "<string>",
    "dimension": 1,
    "expected_dimension": 64
  },
  "cold_start_fallback_used": true,
  "explanation": {
    "scope": "request",
    "note": "<string>",
    "context": {
      "context_id": "<string>",
      "filters": [
        {}
      ],
      "request_filters": [
        {
          "column": "<string>",
          "operator": "<string>",
          "value": "<string>"
        }
      ],
      "group_by": [
        "<string>"
      ],
      "exclude_viewed_items": {
        "value": 123,
        "unit": "<string>",
        "interval": "<string>"
      },
      "auto_section": {
        "section_id": "<string>",
        "title": "<string>",
        "subtitle": "<string>",
        "reason": {}
      }
    },
    "pipeline": {
      "id": 123,
      "stages": [
        {
          "stage": "<string>",
          "enabled": true,
          "status": "<string>",
          "pipeline_id": 123,
          "config": {},
          "note": "<string>",
          "item_events": [
            {}
          ]
        }
      ]
    },
    "experiments": [
      {
        "experiment_id": 123,
        "experiment_name": "<string>",
        "variant_id": 123,
        "variant_name": "<string>"
      }
    ],
    "user_segments": [
      "<string>"
    ],
    "embedding": {
      "used_default": true,
      "default_reason": "<string>",
      "dimension": 1,
      "expected_dimension": 64
    }
  },
  "excluded_viewed_items": {
    "value": 123,
    "unit": "<string>",
    "interval": "<string>"
  },
  "section": {
    "section_id": "<string>",
    "title": "<string>",
    "subtitle": "<string>",
    "reason": {}
  },
  "done": true,
  "experiments": [
    {
      "experiment_id": 123,
      "experiment_name": "<string>",
      "variant_id": 123,
      "variant_name": "<string>"
    }
  ],
  "user_segments": [
    "<string>"
  ],
  "pipeline_id": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Description

Returns ranked catalog items for a free-text query. Search uses the Core API data plane at https://api.neuronsearchlab.com/v1/search; it is not a Platform API or console search endpoint. The search request embeds query, retrieves candidates, applies context filters and pipeline configuration, and returns the same recommendation item shape as GET /v1/recommendations.

​
Request

POST /v1/search
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "query": "waterproof trail shoes",
  "user_id": "usr_abc123",
  "context_id": "101",
  "limit": "10",
  "filter": ["category:footwear"]
}
FieldTypeRequiredDescription
querystringyesFree-text query to embed and retrieve against.
user_idstringnoEnd-user identifier for telemetry, personalization context, and attribution.
context_idstringnoNumeric console context ID. Legacy ctx_ aliases such as ctx_101 are accepted.
context_keystringnoContext lookup key alias when your integration uses keys instead of numeric IDs.
limitstringnoNumber of results to return. Defaults to 20, maximum 100.
filterstring or string[]noMetadata filter shorthand. Repeat to combine filters.
scopestringnoJSON-encoded structured request scope, currently honoring filters.
query_retrieval_enabledstringnoPer-request override for query retrieval. Prefer configuring this in the active pipeline.
fusion_methodstringnorrf or weighted for semantic/keyword fusion.
semantic_weightstringnoSemantic retrieval weight when fusion_method is weighted.
keyword_weightstringnoKeyword retrieval weight when query retrieval is enabled.
keyword_fieldsstringnoComma-separated metadata fields for keyword matching.

​
Response

{
  "object": "list",
  "message": "Search results fetched",
  "request_id": "66666666-6666-4666-8666-666666666666",
  "url": "/v1/search",
  "query": "waterproof trail shoes",
  "data": [
    {
      "id": "rec_itm_7f3a2c9e",
      "object": "recommendation",
      "item_id": "itm_7f3a2c9e",
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": "itm_7f3a2c9e",
        "object": "item",
        "name": "Waterproof Trail Shoes",
        "description": "Lightweight trail shoes with a waterproof upper.",
        "metadata": {
          "category": "footwear"
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "limit": 10,
  "recommendations": [
    {
      "id": "rec_itm_7f3a2c9e",
      "object": "recommendation",
      "item_id": "itm_7f3a2c9e",
      "rank": 1,
      "score": 0.94
    }
  ],
  "processing_time_ms": 182
}
For backwards-compatible rendering code, the response also includes recommendations with the same result array as data. Responses may include embedding_info, request-level explanation, and per-item explanation fields. Use the returned request_id in downstream events to attribute engagement to the search result set. The official JavaScript and PHP SDKs capture it automatically after search().

​
Errors

StatusScenario
400Validation failed or malformed filters
401Missing/invalid access token or tenant resolution failed
403Token does not include neuronsearchlab-api/read
422Search query embedding is unavailable for the team
500Unexpected search, database, or model-serving failure

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
X-Request-Id
string<uuid>

Optional stable request ID for retries and downstream event attribution. The same ID is returned in the response body and X-Request-Id response header.

​
X-Session-Id
string

Optional session identifier stored with served search telemetry.

​
X-Anonymous-Id
string

Optional anonymous identifier stored with served search telemetry when user_id is absent.

​
X-SDK
string

Optional SDK name stored with served search telemetry.

​
X-SDK-Version
string

Optional SDK version stored with served search telemetry.

​
X-Platform
string

Optional client platform stored with served search telemetry.

Body

application/json
​
query
string
required

Free-text query to embed and retrieve against.

Minimum string length: 1
Example:

"waterproof trail shoes"

​
user_id
string

End-user identifier for telemetry, personalization context, and attribution.

Example:

"usr_abc123"

​
context_id
string

Numeric console context ID. Legacy ctx_ aliases such as ctx_101 are also accepted.

Example:

"101"

​
context_key
string

Context lookup key alias when your integration uses keys instead of numeric IDs.

​
limit

Number of results to return. Defaults to 20 and is capped at 100.

Required range: 1 <= x <= 100
Example:

"10"

​
filter

Metadata filter shorthand. Examples: category:footwear, type!=comment, OR:brand:Acme.

Example:
["category:footwear"]
​
scope
string

JSON-encoded request scope. Today only filters is honored, using objects with column, operator, value, and optional logic.

Example:

"{\"filters\":[{\"column\":\"brand\",\"operator\":\"=\",\"value\":\"Acme\"}]}"

​
query_retrieval_enabled

Per-request override for query retrieval. Prefer configuring this in the active pipeline.

​
fusion_method
enum<string>

Semantic/keyword fusion strategy.

Available options:
rrf,
weighted
​
semantic_weight

Semantic retrieval weight when fusion_method is weighted.

Required range: 0 <= x <= 1
​
keyword_weight

Keyword retrieval weight when query retrieval is enabled.

Required range: 0 <= x <= 1
​
keyword_fields

Comma-separated fields or array of fields for keyword matching.

Example:

"name,description,category"

​
request_id
string<uuid>

Optional stable request ID for retries and attribution. Prefer the X-Request-Id header.

Response

Search results fetched.

​
object
enum<string>
required
Available options:
list
​
request_id
string<uuid>
required
​
url
string
required
Example:

"/v1/search"

​
data
object[]
required
​
recommendations
object[]
required
​
has_more
boolean
required
​
next_cursor
string | null
required
​
limit
integer
required
Required range: 1 <= x <= 100
​
quantity
integer
required
Required range: x >= 0
​
processing_time_ms
integer
required
Required range: x >= 0
​
mode
enum<string>
required
Available options:
single,
auto
​
query
string
required
Example:

"waterproof trail shoes"

​
message
string
Example:

"Search results fetched"

​
embedding_info
object
​
cold_start_fallback_used
boolean
​
explanation
object
​
excluded_viewed_items
object
​
section
object
​
done
boolean

Present in auto mode.

​
experiments
object[]
​
user_segments
string[]
​
pipeline_id
integer | null