# Search API

## Search for products

> Search for products

```json
{"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"servers":[{"url":"https://product-api.userflux.co","description":"Products API server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Your Product API Read-Only Key"}},"schemas":{"SearchRequest":{"type":"object","required":["strategy","schemaId","query","topN"],"properties":{"strategy":{"type":"string","description":"Strategy to use for search","enum":["SEMANTIC","FULL_TEXT","HYBRID"]},"schemaId":{"type":"string","description":"ID of the product schema you're querying against"},"query":{"type":"string","description":"The search term"},"topN":{"type":"integer","description":"Number of results to retrieve"},"page":{"type":"integer","description":"Page number to retrieve (defaults to 1 if not provided)"},"searchFields":{"type":"array","description":"Array of product property paths to use in a full-text and hybrid search. Note that only properties marked as full-text searchable in the product schema will be able to be used here.","items":{"$ref":"#/components/schemas/SearchField"}},"propertyFilters":{"type":"object","description":"Filter criteria for search results","$ref":"#/components/schemas/ProductQueryPropertyFilter"},"geoFilter":{"type":"object","description":"Geographical filter criteria for search results","$ref":"#/components/schemas/GeoFilter"},"postFilter":{"$ref":"#/components/schemas/ProductQueryPostFilter"},"profileId":{"type":"string","description":"Unique identifier of the anonymous or known profile. Only required when using a geo filter on the profile's location."}}},"SearchField":{"type":"object","required":["path"],"properties":{"path":{"type":"string","description":"Path to the product property to search on"},"weight":{"type":"number","description":"Weight of the search field. This is a multiplier for the search score. Defaults to 1 if not provided."},"exactMatch":{"type":"boolean","description":"Whether to only match exact words in the search term. Defaults to false if not provided."}}},"ProductQueryPropertyFilter":{"type":"object","required":["join","groups"],"properties":{"join":{"type":"string","description":"Join operator to join the individual filter groups together with","enum":["AND","OR"]},"groups":{"type":"array","description":"Array of product property filters that are grouped together","items":{"$ref":"#/components/schemas/PropertyGroupFilters"}}}},"PropertyGroupFilters":{"type":"object","required":["join","conditions"],"properties":{"join":{"type":"string","description":"Join operator for property group filters","enum":["AND","OR"]},"conditions":{"type":"array","description":"Array of property filters","items":{"$ref":"#/components/schemas/PropertyFilter"}}}},"PropertyFilter":{"type":"object","required":["property","operator","dataType","value"],"properties":{"property":{"type":"string","description":"Path to the product property to filter on"},"operator":{"type":"string","description":"Comparison operator. `Any_` and `Array_` operators are used to filter on items in an array.","enum":["EQUAL","NOT_EQUAL","GREATER_THAN","LESS_THAN","GREATER_THAN_OR_EQUAL","LESS_THAN_OR_EQUAL","ANY_LESS_THAN","ANY_LESS_THAN_OR_EQUAL","ANY_GREATER_THAN","ANY_GREATER_THAN_OR_EQUAL","ARRAY_CONTAINS","ARRAY_NOT_CONTAINS","ARRAY_CONTAINS_ANY","ARRAY_NOT_CONTAINS_ANY"]},"dataType":{"type":"string","description":"Type of the value","enum":["STRING","NUMBER","BOOLEAN","DATE_TIME","DATE"]},"value":{"description":"Value to compare against (can be a string, number, boolean, date-time, or date). Dates should be in ISO 8601 string format."}}},"GeoFilter":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Type of geographical filter","enum":["RADIUS","GEO_BOX"]},"radius":{"$ref":"#/components/schemas/GeoRadiusFilter"},"geoBox":{"$ref":"#/components/schemas/GeoBoxFilter"}}},"GeoRadiusFilter":{"type":"object","required":["source","distance","distanceUnit"],"properties":{"source":{"type":"string","description":"Source of the geographical filter. When using the PROFILE source, the profile's location will be used to filter results. When using the CUSTOM source, the provided latitude and longitude values will be used to filter results.","enum":["PROFILE","CUSTOM"]},"distance":{"type":"integer","description":"Distance in the specified distance unit"},"distanceUnit":{"type":"string","description":"Unit of distance","enum":["METERS","KILOMETERS"]},"latitude":{"type":"number","description":"Custom latitude. Required when using the CUSTOM source."},"longitude":{"type":"number","description":"Custom longitude. Required when using the CUSTOM source."}}},"GeoBoxFilter":{"type":"object","required":["pair","northLatitude","northLongitude","southLatitude","southLongitude"],"properties":{"pair":{"type":"string","enum":["NE_SW","NW_SE"],"description":"Pair of latitudes and longitudes to use for the geographical box filter"},"northLatitude":{"type":"number","description":"North latitude of the geographical box"},"northLongitude":{"type":"number","description":"North longitude of the geographical box"},"southLatitude":{"type":"number","description":"South latitude of the geographical box"},"southLongitude":{"type":"number","description":"South longitude of the geographical box"}}},"ProductQueryPostFilter":{"type":"object","required":[],"properties":{"verifyDateRange":{"$ref":"#/components/schemas/VerifyDateRangePostFilter"},"distinctBy":{"type":"string","description":"Product property path to apply a distinct by filter on"}}},"VerifyDateRangePostFilter":{"type":"object","required":["startDateProperty","endDateProperty","dateRange"],"properties":{"startDateProperty":{"type":"string","description":"Property to filter on start date"},"endDateProperty":{"type":"string","description":"Property to filter on end date"},"dateRange":{"type":"array","description":"Date range to filter on","items":{"type":"string"}}}}}},"paths":{"/search":{"post":{"summary":"Search for products","description":"Search for products","operationId":"search","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Fetched search results successfully"},"400":{"description":"Bad Request - Invalid input parameters"},"401":{"description":"Unauthorized - Authentication credentials are missing or invalid"},"403":{"description":"Forbidden - Insufficient permissions to perform the operation"},"500":{"description":"Internal Server Error - Unexpected server error occurred"}}}}}}
```

## The SearchRequest object

```json
{"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"SearchRequest":{"type":"object","required":["strategy","schemaId","query","topN"],"properties":{"strategy":{"type":"string","description":"Strategy to use for search","enum":["SEMANTIC","FULL_TEXT","HYBRID"]},"schemaId":{"type":"string","description":"ID of the product schema you're querying against"},"query":{"type":"string","description":"The search term"},"topN":{"type":"integer","description":"Number of results to retrieve"},"page":{"type":"integer","description":"Page number to retrieve (defaults to 1 if not provided)"},"searchFields":{"type":"array","description":"Array of product property paths to use in a full-text and hybrid search. Note that only properties marked as full-text searchable in the product schema will be able to be used here.","items":{"$ref":"#/components/schemas/SearchField"}},"propertyFilters":{"type":"object","description":"Filter criteria for search results","$ref":"#/components/schemas/ProductQueryPropertyFilter"},"geoFilter":{"type":"object","description":"Geographical filter criteria for search results","$ref":"#/components/schemas/GeoFilter"},"postFilter":{"$ref":"#/components/schemas/ProductQueryPostFilter"},"profileId":{"type":"string","description":"Unique identifier of the anonymous or known profile. Only required when using a geo filter on the profile's location."}}},"SearchField":{"type":"object","required":["path"],"properties":{"path":{"type":"string","description":"Path to the product property to search on"},"weight":{"type":"number","description":"Weight of the search field. This is a multiplier for the search score. Defaults to 1 if not provided."},"exactMatch":{"type":"boolean","description":"Whether to only match exact words in the search term. Defaults to false if not provided."}}},"ProductQueryPropertyFilter":{"type":"object","required":["join","groups"],"properties":{"join":{"type":"string","description":"Join operator to join the individual filter groups together with","enum":["AND","OR"]},"groups":{"type":"array","description":"Array of product property filters that are grouped together","items":{"$ref":"#/components/schemas/PropertyGroupFilters"}}}},"PropertyGroupFilters":{"type":"object","required":["join","conditions"],"properties":{"join":{"type":"string","description":"Join operator for property group filters","enum":["AND","OR"]},"conditions":{"type":"array","description":"Array of property filters","items":{"$ref":"#/components/schemas/PropertyFilter"}}}},"PropertyFilter":{"type":"object","required":["property","operator","dataType","value"],"properties":{"property":{"type":"string","description":"Path to the product property to filter on"},"operator":{"type":"string","description":"Comparison operator. `Any_` and `Array_` operators are used to filter on items in an array.","enum":["EQUAL","NOT_EQUAL","GREATER_THAN","LESS_THAN","GREATER_THAN_OR_EQUAL","LESS_THAN_OR_EQUAL","ANY_LESS_THAN","ANY_LESS_THAN_OR_EQUAL","ANY_GREATER_THAN","ANY_GREATER_THAN_OR_EQUAL","ARRAY_CONTAINS","ARRAY_NOT_CONTAINS","ARRAY_CONTAINS_ANY","ARRAY_NOT_CONTAINS_ANY"]},"dataType":{"type":"string","description":"Type of the value","enum":["STRING","NUMBER","BOOLEAN","DATE_TIME","DATE"]},"value":{"description":"Value to compare against (can be a string, number, boolean, date-time, or date). Dates should be in ISO 8601 string format."}}},"GeoFilter":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Type of geographical filter","enum":["RADIUS","GEO_BOX"]},"radius":{"$ref":"#/components/schemas/GeoRadiusFilter"},"geoBox":{"$ref":"#/components/schemas/GeoBoxFilter"}}},"GeoRadiusFilter":{"type":"object","required":["source","distance","distanceUnit"],"properties":{"source":{"type":"string","description":"Source of the geographical filter. When using the PROFILE source, the profile's location will be used to filter results. When using the CUSTOM source, the provided latitude and longitude values will be used to filter results.","enum":["PROFILE","CUSTOM"]},"distance":{"type":"integer","description":"Distance in the specified distance unit"},"distanceUnit":{"type":"string","description":"Unit of distance","enum":["METERS","KILOMETERS"]},"latitude":{"type":"number","description":"Custom latitude. Required when using the CUSTOM source."},"longitude":{"type":"number","description":"Custom longitude. Required when using the CUSTOM source."}}},"GeoBoxFilter":{"type":"object","required":["pair","northLatitude","northLongitude","southLatitude","southLongitude"],"properties":{"pair":{"type":"string","enum":["NE_SW","NW_SE"],"description":"Pair of latitudes and longitudes to use for the geographical box filter"},"northLatitude":{"type":"number","description":"North latitude of the geographical box"},"northLongitude":{"type":"number","description":"North longitude of the geographical box"},"southLatitude":{"type":"number","description":"South latitude of the geographical box"},"southLongitude":{"type":"number","description":"South longitude of the geographical box"}}},"ProductQueryPostFilter":{"type":"object","required":[],"properties":{"verifyDateRange":{"$ref":"#/components/schemas/VerifyDateRangePostFilter"},"distinctBy":{"type":"string","description":"Product property path to apply a distinct by filter on"}}},"VerifyDateRangePostFilter":{"type":"object","required":["startDateProperty","endDateProperty","dateRange"],"properties":{"startDateProperty":{"type":"string","description":"Property to filter on start date"},"endDateProperty":{"type":"string","description":"Property to filter on end date"},"dateRange":{"type":"array","description":"Date range to filter on","items":{"type":"string"}}}}}}}
```

## The PropertyFilter object

```json
{"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"PropertyFilter":{"type":"object","required":["property","operator","dataType","value"],"properties":{"property":{"type":"string","description":"Path to the product property to filter on"},"operator":{"type":"string","description":"Comparison operator. `Any_` and `Array_` operators are used to filter on items in an array.","enum":["EQUAL","NOT_EQUAL","GREATER_THAN","LESS_THAN","GREATER_THAN_OR_EQUAL","LESS_THAN_OR_EQUAL","ANY_LESS_THAN","ANY_LESS_THAN_OR_EQUAL","ANY_GREATER_THAN","ANY_GREATER_THAN_OR_EQUAL","ARRAY_CONTAINS","ARRAY_NOT_CONTAINS","ARRAY_CONTAINS_ANY","ARRAY_NOT_CONTAINS_ANY"]},"dataType":{"type":"string","description":"Type of the value","enum":["STRING","NUMBER","BOOLEAN","DATE_TIME","DATE"]},"value":{"description":"Value to compare against (can be a string, number, boolean, date-time, or date). Dates should be in ISO 8601 string format."}}}}}}
```

## The GeoFilter object

```json
{"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"GeoFilter":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Type of geographical filter","enum":["RADIUS","GEO_BOX"]},"radius":{"$ref":"#/components/schemas/GeoRadiusFilter"},"geoBox":{"$ref":"#/components/schemas/GeoBoxFilter"}}},"GeoRadiusFilter":{"type":"object","required":["source","distance","distanceUnit"],"properties":{"source":{"type":"string","description":"Source of the geographical filter. When using the PROFILE source, the profile's location will be used to filter results. When using the CUSTOM source, the provided latitude and longitude values will be used to filter results.","enum":["PROFILE","CUSTOM"]},"distance":{"type":"integer","description":"Distance in the specified distance unit"},"distanceUnit":{"type":"string","description":"Unit of distance","enum":["METERS","KILOMETERS"]},"latitude":{"type":"number","description":"Custom latitude. Required when using the CUSTOM source."},"longitude":{"type":"number","description":"Custom longitude. Required when using the CUSTOM source."}}},"GeoBoxFilter":{"type":"object","required":["pair","northLatitude","northLongitude","southLatitude","southLongitude"],"properties":{"pair":{"type":"string","enum":["NE_SW","NW_SE"],"description":"Pair of latitudes and longitudes to use for the geographical box filter"},"northLatitude":{"type":"number","description":"North latitude of the geographical box"},"northLongitude":{"type":"number","description":"North longitude of the geographical box"},"southLatitude":{"type":"number","description":"South latitude of the geographical box"},"southLongitude":{"type":"number","description":"South longitude of the geographical box"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://userflux.gitbook.io/userflux-docs/apis/search-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.