# Personalise API ## Fetch recommendations for a user > Fetch recommendations for a user ```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":{"PersonaliseRequest":{"type":"object","required":["modelConfig","profileId","topN","page"],"properties":{"modelConfig":{"$ref":"#/components/schemas/PersonaliseRequestModelConfig"},"profileId":{"type":"string","description":"Unique identifier of the anonymous or known profile"},"stateKey":{"type":"string","description":"Use this to cache returned results by a specific key. Using this will automatically filter out any results that are in the cache on subsequent requests. Ideal when loading a page with multiple sections of recommendations where you want to avoid overlapping results per section."},"propertyFilters":{"$ref":"#/components/schemas/ProductQueryPropertyFilter"},"geoFilter":{"$ref":"#/components/schemas/GeoFilter"},"postFilter":{"$ref":"#/components/schemas/ProductQueryPostFilter"},"topN":{"type":"integer","description":"Number of results to retrieve"},"page":{"type":"integer","description":"Page number to retrieve (defaults to 1 if not provided)"},"fallbackSearchQuery":{"type":"string","description":"Fallback search query to use if no results are found for personalisation retrieval."}}},"PersonaliseRequestModelConfig":{"type":"object","required":["strategy","models"],"properties":{"strategy":{"type":"string","description":"Model strategy to use for personalisation retrieval","enum":["FIRST_WITH_RESULT","FUSE_ALL_RESULTS"]},"models":{"type":"array","description":"List of model references to use for personalisation retrieval","items":{"$ref":"#/components/schemas/PersonaliseModelReference"}}}},"PersonaliseModelReference":{"type":"object","required":["modelId","priority"],"properties":{"modelId":{"type":"string","description":"ID of the model to use for personalisation retrieval"},"priority":{"type":"integer","description":"Priority of the model to use for personalisation retrieval. Lower values are higher priority."},"blendCohortKey":{"type":"string","description":"Key of the blend cohort to use for personalisation retrieval. This is optional, if not provided the service will attempt to derive the cohort key from the supplied profile id. Cohort key properties are separated by an underscore."},"weight":{"type":"number","description":"Weight of the model in the FUSE_ALL_RESULTS strategy. This is a multiplier used in reciprocal rank fusion scoring. Defaults to 1 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":{"/personalise":{"post":{"summary":"Fetch recommendations for a user","description":"Fetch recommendations for a user","operationId":"getUserRecommendations","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaliseRequest"}}}},"responses":{"200":{"description":"Fetched recommendations 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 PersonaliseRequest object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"PersonaliseRequest":{"type":"object","required":["modelConfig","profileId","topN","page"],"properties":{"modelConfig":{"$ref":"#/components/schemas/PersonaliseRequestModelConfig"},"profileId":{"type":"string","description":"Unique identifier of the anonymous or known profile"},"stateKey":{"type":"string","description":"Use this to cache returned results by a specific key. Using this will automatically filter out any results that are in the cache on subsequent requests. Ideal when loading a page with multiple sections of recommendations where you want to avoid overlapping results per section."},"propertyFilters":{"$ref":"#/components/schemas/ProductQueryPropertyFilter"},"geoFilter":{"$ref":"#/components/schemas/GeoFilter"},"postFilter":{"$ref":"#/components/schemas/ProductQueryPostFilter"},"topN":{"type":"integer","description":"Number of results to retrieve"},"page":{"type":"integer","description":"Page number to retrieve (defaults to 1 if not provided)"},"fallbackSearchQuery":{"type":"string","description":"Fallback search query to use if no results are found for personalisation retrieval."}}},"PersonaliseRequestModelConfig":{"type":"object","required":["strategy","models"],"properties":{"strategy":{"type":"string","description":"Model strategy to use for personalisation retrieval","enum":["FIRST_WITH_RESULT","FUSE_ALL_RESULTS"]},"models":{"type":"array","description":"List of model references to use for personalisation retrieval","items":{"$ref":"#/components/schemas/PersonaliseModelReference"}}}},"PersonaliseModelReference":{"type":"object","required":["modelId","priority"],"properties":{"modelId":{"type":"string","description":"ID of the model to use for personalisation retrieval"},"priority":{"type":"integer","description":"Priority of the model to use for personalisation retrieval. Lower values are higher priority."},"blendCohortKey":{"type":"string","description":"Key of the blend cohort to use for personalisation retrieval. This is optional, if not provided the service will attempt to derive the cohort key from the supplied profile id. Cohort key properties are separated by an underscore."},"weight":{"type":"number","description":"Weight of the model in the FUSE_ALL_RESULTS strategy. This is a multiplier used in reciprocal rank fusion scoring. Defaults to 1 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 PersonaliseRequestModelConfig object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"PersonaliseRequestModelConfig":{"type":"object","required":["strategy","models"],"properties":{"strategy":{"type":"string","description":"Model strategy to use for personalisation retrieval","enum":["FIRST_WITH_RESULT","FUSE_ALL_RESULTS"]},"models":{"type":"array","description":"List of model references to use for personalisation retrieval","items":{"$ref":"#/components/schemas/PersonaliseModelReference"}}}},"PersonaliseModelReference":{"type":"object","required":["modelId","priority"],"properties":{"modelId":{"type":"string","description":"ID of the model to use for personalisation retrieval"},"priority":{"type":"integer","description":"Priority of the model to use for personalisation retrieval. Lower values are higher priority."},"blendCohortKey":{"type":"string","description":"Key of the blend cohort to use for personalisation retrieval. This is optional, if not provided the service will attempt to derive the cohort key from the supplied profile id. Cohort key properties are separated by an underscore."},"weight":{"type":"number","description":"Weight of the model in the FUSE_ALL_RESULTS strategy. This is a multiplier used in reciprocal rank fusion scoring. Defaults to 1 if not provided."}}}}}} ``` ## The PersonaliseModelReference object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"PersonaliseModelReference":{"type":"object","required":["modelId","priority"],"properties":{"modelId":{"type":"string","description":"ID of the model to use for personalisation retrieval"},"priority":{"type":"integer","description":"Priority of the model to use for personalisation retrieval. Lower values are higher priority."},"blendCohortKey":{"type":"string","description":"Key of the blend cohort to use for personalisation retrieval. This is optional, if not provided the service will attempt to derive the cohort key from the supplied profile id. Cohort key properties are separated by an underscore."},"weight":{"type":"number","description":"Weight of the model in the FUSE_ALL_RESULTS strategy. This is a multiplier used in reciprocal rank fusion scoring. Defaults to 1 if not provided."}}}}}} ``` ## The ProductQueryPropertyFilter object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}} ``` ## The PropertyGroupFilters object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}} ``` ## 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"}}}}}} ``` ## The GeoRadiusFilter object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}} ``` ## The GeoBoxFilter object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}} ``` ## The ProductQueryPostFilter object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"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 VerifyDateRangePostFilter object ```json {"openapi":"3.1.0","info":{"title":"Products API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}} ``` --- # 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/personalise-api.md?ask= ``` 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.