> ## 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.

# Search

> Run query-driven retrieval through the Core API.

## 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

```http theme={null}
POST /v1/search
Content-Type: application/json
Authorization: Bearer <access_token>
```

```json theme={null}
{
  "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

```json theme={null}
{
  "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    |


## OpenAPI

````yaml POST /v1/search
openapi: 3.0.3
info:
  title: NeuronSearchLab Core API
  version: 1.0.0
  description: >-
    Versioned data-plane API for OAuth token exchange, catalog item ingestion,
    user event ingestion, and recommendation serving.
  license:
    name: Proprietary
    url: https://neuronsearchlab.com
servers:
  - url: https://api.neuronsearchlab.com
    description: Core API Gateway custom domain
security:
  - oauth2: []
tags:
  - name: Authentication
    description: OAuth 2.0 client credentials token exchange.
  - name: Items
    description: Catalog item ingestion, lookup, update, deletion, and pagination.
  - name: Events
    description: User interaction event ingestion, lookup, and pagination.
  - name: Recommendations
    description: >-
      Personalized recommendation serving, request-scoped filtering, and
      auto-section generation.
  - name: Search
    description: Query-driven search serving through the Core API data plane.
  - name: CORS
    description: Browser preflight routes generated by API Gateway.
paths:
  /v1/search:
    post:
      tags:
        - Search
      summary: Search
      description: >-
        Run query-driven retrieval through the Core API data plane. This
        endpoint is served from the public AWS API Gateway and is not the
        console Platform API.
      operationId: search
      parameters:
        - name: X-Request-Id
          in: header
          description: >-
            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.
          schema:
            type: string
            format: uuid
        - name: X-Session-Id
          in: header
          description: Optional session identifier stored with served search telemetry.
          schema:
            type: string
        - name: X-Anonymous-Id
          in: header
          description: >-
            Optional anonymous identifier stored with served search telemetry
            when `user_id` is absent.
          schema:
            type: string
        - name: X-SDK
          in: header
          description: Optional SDK name stored with served search telemetry.
          schema:
            type: string
        - name: X-SDK-Version
          in: header
          description: Optional SDK version stored with served search telemetry.
          schema:
            type: string
        - name: X-Platform
          in: header
          description: Optional client platform stored with served search telemetry.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              basic:
                summary: Search footwear
                value:
                  query: waterproof trail shoes
                  user_id: user-abc123
                  context_id: '101'
                  limit: '10'
                  filter:
                    - category:footwear
      responses:
        '200':
          description: Search results fetched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchList'
        '400':
          description: Validation failed or malformed filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Token does not include neuronsearchlab-api/read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Search query embedding is unavailable for the team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected search, database, or model-serving failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - oauth2:
            - neuronsearchlab-api/read
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          minLength: 1
          description: Free-text query to embed and retrieve against.
          example: waterproof trail shoes
        user_id:
          type: string
          description: >-
            End-user identifier for telemetry, personalization context, and
            attribution.
          example: user-abc123
        context_id:
          type: string
          description: Numeric console context ID.
          example: '101'
        context_key:
          type: string
          description: >-
            Context lookup key alias when your integration uses keys instead of
            numeric IDs.
        limit:
          oneOf:
            - type: integer
              minimum: 1
              maximum: 100
            - type: string
          description: Number of results to return. Defaults to 20 and is capped at 100.
          example: '10'
        filter:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            Metadata filter shorthand. Examples: category:footwear,
            type!=comment, OR:brand:Acme.
          example:
            - category:footwear
        scope:
          type: string
          description: >-
            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:
          oneOf:
            - type: string
            - type: boolean
          description: >-
            Per-request override for query retrieval. Prefer configuring this in
            the active pipeline.
        fusion_method:
          type: string
          enum:
            - rrf
            - weighted
          description: Semantic/keyword fusion strategy.
        semantic_weight:
          oneOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: string
          description: Semantic retrieval weight when fusion_method is weighted.
        keyword_weight:
          oneOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: string
          description: Keyword retrieval weight when query retrieval is enabled.
        keyword_fields:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Comma-separated fields or array of fields for keyword matching.
          example: name,description,category
        request_id:
          type: string
          format: uuid
          description: >-
            Optional stable request ID for retries and attribution. Prefer the
            X-Request-Id header.
      additionalProperties: true
    SearchList:
      allOf:
        - $ref: '#/components/schemas/RecommendationList'
        - type: object
          required:
            - query
          properties:
            message:
              type: string
              example: Search results fetched
            url:
              type: string
              example: /v1/search
            query:
              type: string
              example: waterproof trail shoes
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - not_found_error
                - conflict_error
                - rate_limit_error
                - api_error
            code:
              type: string
            message:
              type: string
            details: {}
            request_id:
              type: string
              format: uuid
          additionalProperties: true
    RecommendationList:
      type: object
      required:
        - object
        - request_id
        - url
        - data
        - has_more
        - next_cursor
        - limit
        - recommendations
        - quantity
        - processing_time_ms
        - mode
      properties:
        object:
          type: string
          enum:
            - list
        message:
          type: string
          example: Recommendations fetched
        request_id:
          type: string
          format: uuid
        url:
          type: string
          example: /v1/recommendations
        data:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/Recommendation'
              - $ref: '#/components/schemas/RecommendationGroup'
        recommendations:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/Recommendation'
              - $ref: '#/components/schemas/RecommendationGroup'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
        embedding_info:
          $ref: '#/components/schemas/EmbeddingInfo'
        cold_start_fallback_used:
          type: boolean
        explanation:
          $ref: '#/components/schemas/RecommendationRequestExplanation'
        quantity:
          type: integer
          minimum: 0
        excluded_viewed_items:
          type: object
          nullable: true
          properties:
            value:
              type: integer
              nullable: true
            unit:
              type: string
              nullable: true
            interval:
              type: string
              nullable: true
          additionalProperties: true
        processing_time_ms:
          type: integer
          minimum: 0
        mode:
          type: string
          enum:
            - single
            - auto
        section:
          type: object
          nullable: true
          properties:
            section_id:
              type: string
            title:
              type: string
            subtitle:
              type: string
            reason:
              $ref: '#/components/schemas/Object'
          additionalProperties: true
        done:
          type: boolean
          description: Present in auto mode.
        experiments:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentAssignment'
        user_segments:
          type: array
          items:
            type: string
        pipeline_id:
          type: integer
          nullable: true
      additionalProperties: true
    Recommendation:
      type: object
      required:
        - id
        - object
        - item_id
        - rank
        - score
        - item
      properties:
        id:
          type: string
          pattern: ^rec_
          example: 7f3a2c9e
        object:
          type: string
          enum:
            - recommendation
        item_id:
          type: string
          example: 7f3a2c9e
        entity_id:
          type: string
          description: Raw item entity ID from the candidate source.
          example: 7f3a2c9e
        rank:
          type: integer
          minimum: 1
          example: 1
        score:
          type: number
          format: double
          example: 0.94
        name:
          type: string
          example: Wireless Headphones
        description:
          type: string
          example: Noise-cancelling Bluetooth headphones.
        metadata:
          $ref: '#/components/schemas/Metadata'
        source:
          type: string
          description: >-
            Candidate source, such as `model`, `trending_backfill`, or
            `exploration`.
          example: model
        item:
          $ref: '#/components/schemas/RecommendationItem'
        explanation:
          $ref: '#/components/schemas/RecommendationExplanation'
      additionalProperties: true
    RecommendationGroup:
      type: object
      required:
        - group
        - items
        - score
      properties:
        group:
          type: string
          description: Group key built from the active context `group_by` fields.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Recommendation'
        score:
          type: number
          format: double
        similarity:
          type: number
          format: double
      additionalProperties: true
    EmbeddingInfo:
      type: object
      required:
        - source
        - used_default
        - default_reason
        - dimension
        - expected_dimension
      properties:
        source:
          type: string
          enum:
            - db
            - default
            - item
        used_default:
          type: boolean
        default_reason:
          type: string
          nullable: true
          description: >-
            Reason the default embedding was used, for example
            `no_db_embedding`.
        dimension:
          type: integer
          minimum: 0
        expected_dimension:
          type: integer
          example: 64
    RecommendationRequestExplanation:
      type: object
      properties:
        scope:
          type: string
          example: request
        note:
          type: string
        context:
          $ref: '#/components/schemas/ContextExplanation'
        pipeline:
          $ref: '#/components/schemas/PipelineExplanation'
        experiments:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentAssignment'
        user_segments:
          type: array
          items:
            type: string
        embedding:
          $ref: '#/components/schemas/EmbeddingInfo'
      additionalProperties: true
    Object:
      type: object
      additionalProperties: true
    ExperimentAssignment:
      type: object
      properties:
        experiment_id:
          type: integer
        experiment_name:
          type: string
        variant_id:
          type: integer
        variant_name:
          type: string
      additionalProperties: true
    Metadata:
      type: object
      description: Arbitrary JSON object used for filtering, ranking, and debugging.
      additionalProperties: true
      example:
        category: electronics
        brand: Acme
        price: 10999
        currency: usd
    RecommendationItem:
      type: object
      required:
        - id
        - object
        - name
        - description
        - metadata
      properties:
        id:
          type: string
          example: 7f3a2c9e
        object:
          type: string
          enum:
            - item
        name:
          type: string
          example: Wireless Headphones
        description:
          type: string
          example: Noise-cancelling Bluetooth headphones.
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: true
    RecommendationExplanation:
      type: object
      properties:
        item_id:
          type: string
        rank:
          type: integer
        summary:
          type: string
        shown_because:
          type: array
          items:
            type: string
        source:
          type: string
        score:
          type: object
          properties:
            final:
              type: number
              nullable: true
            base:
              type: number
              nullable: true
            cosine_distance:
              type: number
              nullable: true
            retrieval:
              type: number
              nullable: true
            ranker:
              type: number
              nullable: true
          additionalProperties: true
        context:
          $ref: '#/components/schemas/ContextExplanation'
        embedding:
          type: object
          additionalProperties: true
        pipeline:
          $ref: '#/components/schemas/PipelineExplanation'
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Object'
        experiments:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentAssignment'
        user_segments:
          type: array
          items:
            type: string
      additionalProperties: true
    ContextExplanation:
      type: object
      properties:
        context_id:
          type: string
          nullable: true
        mode:
          type: string
          enum:
            - single
            - auto
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Object'
        request_filters:
          type: array
          items:
            $ref: '#/components/schemas/ScopeFilter'
        group_by:
          type: array
          items:
            type: string
        exclude_viewed_items:
          type: object
          nullable: true
          properties:
            value:
              type: integer
              nullable: true
            unit:
              type: string
              nullable: true
            interval:
              type: string
              nullable: true
          additionalProperties: true
        auto_section:
          type: object
          nullable: true
          properties:
            section_id:
              type: string
            title:
              type: string
            subtitle:
              type: string
            reason:
              $ref: '#/components/schemas/Object'
          additionalProperties: true
      additionalProperties: true
    PipelineExplanation:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        stages:
          type: array
          items:
            $ref: '#/components/schemas/PipelineStageTrace'
      additionalProperties: true
    ScopeFilter:
      type: object
      required:
        - column
        - operator
        - value
      properties:
        column:
          type: string
        operator:
          type: string
          description: Filter operator, such as `=`, `!=`, `<`, `>`, `LIKE`, or `ILIKE`.
        value:
          oneOf:
            - type: string
            - type: number
            - type: boolean
        logic:
          type: string
          enum:
            - AND
            - OR
      additionalProperties: true
    PipelineStageTrace:
      type: object
      properties:
        stage:
          type: string
        enabled:
          type: boolean
        status:
          type: string
        pipeline_id:
          type: integer
          nullable: true
        config:
          $ref: '#/components/schemas/Object'
        note:
          type: string
        item_events:
          type: array
          items:
            $ref: '#/components/schemas/Object'
      additionalProperties: true
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.neuronsearchlab.com/oauth2/token
          scopes:
            neuronsearchlab-api/read: Read recommendations, items, and events.
            neuronsearchlab-api/write: Create, update, and delete items; submit events.

````