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": "7f3a2c9e",
      "object": "recommendation",
      "item_id": "7f3a2c9e",
      "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": "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": "7f3a2c9e",
      "object": "recommendation",
      "item_id": "7f3a2c9e",
      "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": "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
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

POST

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": "7f3a2c9e",
      "object": "recommendation",
      "item_id": "7f3a2c9e",
      "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": "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": "7f3a2c9e",
      "object": "recommendation",
      "item_id": "7f3a2c9e",
      "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": "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
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "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 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": "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`	string	no	Numeric console context ID.
`context_key`	string	no	Context lookup key alias when your integration uses keys instead of numeric IDs.
`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.

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": "7f3a2c9e",
      "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": "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

Status	Scenario
`400`	Validation failed or malformed filters
`401`	Missing/invalid access token or tenant resolution failed
`403`	Token does not include `neuronsearchlab-api/read`
`422`	Search query embedding is unavailable for the team
`500`	Unexpected 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:

"user-abc123"

context_id

string

Numeric console context ID.

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

Option 1
Option 2

Show child attributes

recommendations

object[]

required

Option 1
Option 2

Show child attributes

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

Show child attributes

cold_start_fallback_used

boolean

explanation

object

Show child attributes

excluded_viewed_items

object | null

Show child attributes

section

object | null

Show child attributes

done

boolean

Present in auto mode.

experiments

object[]

Show child attributes

user_segments

string[]

pipeline_id

integer | null

Get recommendations

Overview

Authentication

Items

Events

Recommendations

Search

Description

Request

Response

Errors

Authorizations

Headers

Body

Response

​Description

​Request

​Response

​Errors

Authorizations

Headers

Body

Response

Description

Request

Response

Errors