> For the complete documentation index, see [llms.txt](https://userflux.gitbook.io/userflux-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://userflux.gitbook.io/userflux-docs/apis/search-api.md).

# 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"}}}}}}
```