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": "user-abc123",
"context_id": 101,
"limit": "10",
"filter": [
"category:footwear"
]
}
'import requests
url = "https://api.neuronsearchlab.com/v1/search"
payload = {
"query": "waterproof trail shoes",
"user_id": "user-abc123",
"context_id": 101,
"limit": "10",
"filter": ["category:footwear"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'waterproof trail shoes',
user_id: 'user-abc123',
context_id: 101,
limit: '10',
filter: ['category:footwear']
})
};
fetch('https://api.neuronsearchlab.com/v1/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.neuronsearchlab.com/v1/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'waterproof trail shoes',
'user_id' => 'user-abc123',
'context_id' => 101,
'limit' => '10',
'filter' => [
'category:footwear'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.neuronsearchlab.com/v1/search"
payload := strings.NewReader("{\n \"query\": \"waterproof trail shoes\",\n \"user_id\": \"user-abc123\",\n \"context_id\": 101,\n \"limit\": \"10\",\n \"filter\": [\n \"category:footwear\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.neuronsearchlab.com/v1/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"waterproof trail shoes\",\n \"user_id\": \"user-abc123\",\n \"context_id\": 101,\n \"limit\": \"10\",\n \"filter\": [\n \"category:footwear\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neuronsearchlab.com/v1/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"waterproof trail shoes\",\n \"user_id\": \"user-abc123\",\n \"context_id\": 101,\n \"limit\": \"10\",\n \"filter\": [\n \"category:footwear\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"object": "list",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "/v1/search",
"data": [
{
"id": 3187,
"object": "recommendation",
"item_id": 3187,
"rank": 1,
"score": 0.94,
"item": {
"id": "7f3a2c9e",
"object": "item",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
},
"entity_id": 3187,
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
},
"source": "model",
"explanation": {
"item_id": 2,
"rank": 123,
"summary": "<string>",
"shown_because": [
"<string>"
],
"source": "<string>",
"score": {
"final": 123,
"base": 123,
"cosine_distance": 123,
"retrieval": 123,
"ranker": 123
},
"context": {
"context_id": 2,
"mode": "single",
"filters": [
{}
],
"request_filters": [
{
"column": "<string>",
"operator": "<string>",
"value": "<string>",
"logic": "AND"
}
],
"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": 3187,
"object": "recommendation",
"item_id": 3187,
"rank": 1,
"score": 0.94,
"item": {
"id": "7f3a2c9e",
"object": "item",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
},
"entity_id": 3187,
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
},
"source": "model",
"explanation": {
"item_id": 2,
"rank": 123,
"summary": "<string>",
"shown_because": [
"<string>"
],
"source": "<string>",
"score": {
"final": 123,
"base": 123,
"cosine_distance": 123,
"retrieval": 123,
"ranker": 123
},
"context": {
"context_id": 2,
"mode": "single",
"filters": [
{}
],
"request_filters": [
{
"column": "<string>",
"operator": "<string>",
"value": "<string>",
"logic": "AND"
}
],
"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,
"mode": "single",
"query": "waterproof trail shoes",
"message": "Search results fetched",
"embedding_info": {
"source": "db",
"used_default": true,
"default_reason": "<string>",
"dimension": 1,
"expected_dimension": 64
},
"cold_start_fallback_used": true,
"explanation": {
"scope": "request",
"note": "<string>",
"context": {
"context_id": 2,
"mode": "single",
"filters": [
{}
],
"request_filters": [
{
"column": "<string>",
"operator": "<string>",
"value": "<string>",
"logic": "AND"
}
],
"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": {
"source": "db",
"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,
"search_intent": {
"share": 0.29,
"queries": [
{
"query": "waterproof trail shoes",
"count": 2,
"event_weight": 25,
"share": 0.21,
"last_searched_at": "2023-11-07T05:31:56Z"
}
],
"candidates_added": 3,
"candidates_rescored": 24
},
"search": {
"source": "nsl",
"vector": "query",
"result_item_ids_received": 0,
"event_recorded": true
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}Search
Search
Run query-driven retrieval through the Core API.
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": "user-abc123",
"context_id": 101,
"limit": "10",
"filter": [
"category:footwear"
]
}
'import requests
url = "https://api.neuronsearchlab.com/v1/search"
payload = {
"query": "waterproof trail shoes",
"user_id": "user-abc123",
"context_id": 101,
"limit": "10",
"filter": ["category:footwear"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'waterproof trail shoes',
user_id: 'user-abc123',
context_id: 101,
limit: '10',
filter: ['category:footwear']
})
};
fetch('https://api.neuronsearchlab.com/v1/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.neuronsearchlab.com/v1/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'waterproof trail shoes',
'user_id' => 'user-abc123',
'context_id' => 101,
'limit' => '10',
'filter' => [
'category:footwear'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.neuronsearchlab.com/v1/search"
payload := strings.NewReader("{\n \"query\": \"waterproof trail shoes\",\n \"user_id\": \"user-abc123\",\n \"context_id\": 101,\n \"limit\": \"10\",\n \"filter\": [\n \"category:footwear\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.neuronsearchlab.com/v1/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"waterproof trail shoes\",\n \"user_id\": \"user-abc123\",\n \"context_id\": 101,\n \"limit\": \"10\",\n \"filter\": [\n \"category:footwear\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neuronsearchlab.com/v1/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"waterproof trail shoes\",\n \"user_id\": \"user-abc123\",\n \"context_id\": 101,\n \"limit\": \"10\",\n \"filter\": [\n \"category:footwear\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"object": "list",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "/v1/search",
"data": [
{
"id": 3187,
"object": "recommendation",
"item_id": 3187,
"rank": 1,
"score": 0.94,
"item": {
"id": "7f3a2c9e",
"object": "item",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
},
"entity_id": 3187,
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
},
"source": "model",
"explanation": {
"item_id": 2,
"rank": 123,
"summary": "<string>",
"shown_because": [
"<string>"
],
"source": "<string>",
"score": {
"final": 123,
"base": 123,
"cosine_distance": 123,
"retrieval": 123,
"ranker": 123
},
"context": {
"context_id": 2,
"mode": "single",
"filters": [
{}
],
"request_filters": [
{
"column": "<string>",
"operator": "<string>",
"value": "<string>",
"logic": "AND"
}
],
"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": 3187,
"object": "recommendation",
"item_id": 3187,
"rank": 1,
"score": 0.94,
"item": {
"id": "7f3a2c9e",
"object": "item",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
},
"entity_id": 3187,
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
},
"source": "model",
"explanation": {
"item_id": 2,
"rank": 123,
"summary": "<string>",
"shown_because": [
"<string>"
],
"source": "<string>",
"score": {
"final": 123,
"base": 123,
"cosine_distance": 123,
"retrieval": 123,
"ranker": 123
},
"context": {
"context_id": 2,
"mode": "single",
"filters": [
{}
],
"request_filters": [
{
"column": "<string>",
"operator": "<string>",
"value": "<string>",
"logic": "AND"
}
],
"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,
"mode": "single",
"query": "waterproof trail shoes",
"message": "Search results fetched",
"embedding_info": {
"source": "db",
"used_default": true,
"default_reason": "<string>",
"dimension": 1,
"expected_dimension": 64
},
"cold_start_fallback_used": true,
"explanation": {
"scope": "request",
"note": "<string>",
"context": {
"context_id": 2,
"mode": "single",
"filters": [
{}
],
"request_filters": [
{
"column": "<string>",
"operator": "<string>",
"value": "<string>",
"logic": "AND"
}
],
"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": {
"source": "db",
"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,
"search_intent": {
"share": 0.29,
"queries": [
{
"query": "waterproof trail shoes",
"count": 2,
"event_weight": 25,
"share": 0.21,
"last_searched_at": "2023-11-07T05:31:56Z"
}
],
"candidates_added": 3,
"candidates_rescored": 24
},
"search": {
"source": "nsl",
"vector": "query",
"result_item_ids_received": 0,
"event_recorded": true
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"details": "<unknown>",
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}Description
Returns ranked catalog items for a free-text query. Search uses the Core API data plane athttps://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.
Every search with a user_id (or anonymous_id) is also recorded as an event: one event with the query and no item, on the event type your search signal is bound to. It steers that user’s later recommendations by that event type’s weight, exactly as a click or a purchase does. The results it returned are kept on the event as impressions, not as items the user chose. See searches as events.
When your own engine runs the search
Sendresult_item_ids with the IDs your engine showed for query. NSL records the search with those results and returns recommendations that complement them: the IDs you sent are excluded from data, and retrieval blends the query with the centroid of your top results, so it still works if the query cannot be embedded.
{
"query": "waterproof trail shoes",
"user_id": "user-abc123",
"result_item_ids": [3187, 3190, 3201],
"limit": "6"
}
Request
POST /v1/search
Content-Type: application/json
Authorization: Bearer <access_token>
{
"query": "waterproof trail shoes",
"user_id": "user-abc123",
"context_id": 101,
"limit": "10",
"filter": ["category:footwear"]
}
| Field | Type | Required | Description |
|---|---|---|---|
query | string | yes | Free-text query to embed and retrieve against. |
user_id | string | no | End-user identifier for telemetry, personalization context, and attribution. |
context_id | integer | no | Context ID generated by the dashboard. |
limit | string | no | Number of results to return. Defaults to 20, maximum 100. |
filter | string or string[] | no | Metadata filter shorthand. Repeat to combine filters. |
scope | string | no | JSON-encoded structured request scope, currently honoring filters. |
query_retrieval_enabled | string | no | Per-request override for query retrieval. Prefer configuring this in the active pipeline. |
fusion_method | string | no | rrf or weighted for semantic/keyword fusion. |
semantic_weight | string | no | Semantic retrieval weight when fusion_method is weighted. |
keyword_weight | string | no | Keyword retrieval weight when query retrieval is enabled. |
keyword_fields | string | no | Comma-separated metadata fields for keyword matching. |
result_item_ids | integer[] | no | Item IDs your own search engine showed for query, in rank order (up to 50 are kept). Switches the response to complementary recommendations. A comma-separated string is accepted on GET. |
anonymous_id | string | no | Records the search against this ID when there is no user_id. |
Response
{
"object": "list",
"message": "Search results fetched",
"request_id": "66666666-6666-4666-8666-666666666666",
"url": "/v1/search",
"query": "waterproof trail shoes",
"data": [
{
"id": "7f3a2c9e",
"object": "recommendation",
"item_id": 3187,
"rank": 1,
"score": 0.94,
"item": {
"id": "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": "7f3a2c9e",
"object": "recommendation",
"item_id": 3187,
"rank": 1,
"score": 0.94
}
],
"processing_time_ms": 182,
"search": {
"source": "nsl",
"vector": "query",
"result_item_ids_received": 0,
"event_recorded": true
}
}
search.source is nsl when NSL ran the search and client when you sent result_item_ids. search.event_recorded is false when the request names no user, because a search with nobody to attach it to cannot steer anyone’s recommendations.
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
| Status | Scenario |
|---|---|
400 | Validation failed, malformed filters, or result_item_ids that are not positive integers (invalid_result_item_ids) |
401 | Missing/invalid access token or tenant resolution failed |
403 | Token does not include neuronsearchlab-api/read |
422 | The query cannot be embedded for the team, and no result_item_ids with embeddings were sent |
500 | Unexpected search, database, or model-serving failure |
Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Headers
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.
Optional session identifier stored with served search telemetry.
Optional anonymous identifier stored with served search telemetry when user_id is absent.
Optional SDK name stored with served search telemetry.
Optional SDK version stored with served search telemetry.
Optional client platform stored with served search telemetry.
Body
application/json
Free-text query to embed and retrieve against.
Minimum string length:
1Example:
"waterproof trail shoes"
End-user identifier for telemetry, personalization context, and attribution.
Example:
"user-abc123"
Numeric console context ID.
Required range:
x >= 1Example:
101
Number of results to return. Defaults to 20 and is capped at 100.
Required range:
1 <= x <= 100Example:
"10"
Metadata filter shorthand. Examples: category:footwear, type!=comment, OR:brand:Acme.
Example:
["category:footwear"]
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\"}]}"
Per-request override for query retrieval. Prefer configuring this in the active pipeline.
Semantic/keyword fusion strategy.
Available options:
rrf, weighted Semantic retrieval weight when fusion_method is weighted.
Required range:
0 <= x <= 1Keyword retrieval weight when query retrieval is enabled.
Required range:
0 <= x <= 1Comma-separated fields or array of fields for keyword matching.
Example:
"name,description,category"
Optional stable request ID for retries and attribution. Prefer the X-Request-Id header.
Your own search engine ran query and showed these item IDs, in rank order. NSL records the search with them and returns recommendations that complement them: these IDs are excluded from data. The retrieval vector blends the query embedding with the centroid of your top results.
Maximum array length:
50Required range:
x >= 1Example:
[3187, 3190]
Response
Search results fetched.
Available options:
list Example:
"/v1/search"
- Option 1
- Option 2
Show child attributes
Show child attributes
- Option 1
- Option 2
Show child attributes
Show child attributes
Required range:
1 <= x <= 100Required range:
x >= 0Required range:
x >= 0Available options:
single, auto Example:
"waterproof trail shoes"
Example:
"Search results fetched"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Present in auto mode.
Show child attributes
Show child attributes
Present when the user's recent searches steered this response. Searches from the last 14 days are weighed against item events by event weight, each halving every 72 hours.
Show child attributes
Show child attributes
How this search was served and recorded.
Show child attributes
Show child attributes
Was this page helpful?