Recommendation

Get Items Recommendations from Generic Input

POST recommendation/generic/items/

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations from any reco type.

The endpoint is a generic input wrapper over all *-to-items reco types. It accepts all input parameters from any of these endpoints. It uses a generic scenario passed as a parameter or configured by default. After a first generic scenario evaluation, the final reco_type will be resolved dynamically at runtime. The generic case scenario selects the reco_type and optionally a scenario for this reco_type. A second scenario evaluation will be performed for this reco_type.

Generic scenarios also support ab_test and condition types, and allow them to resolve to different final reco types. While it’s only a wrapper over the specific endpoints, it allows experimentation with different reco types without having to deploy new code.

Input parameters that were given but not used for the selected reco_type are silently ignored.

Request JSON Object

• user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Used to personalize recommendations when the generic input resolves to: profile_to_items, profile_to_items_w_ctx_items, precomputed_profile_to_items. Otherwise used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics.

• session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Used to personalize recommendations when the generic input resolves to: session_to_items, session_to_items_w_ctx_items. Otherwise used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics, when a user_id is not available.

• item_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Item ID. Used to get similar items when the generic input resolves to: item_to_items, precomputed_item_to_items

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• interactions (object-array) –

  Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • interaction_type (O) – Interaction Type

  • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)

• ratings (object-array) –

  Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • rating (float32) – [min: 1 max: 10] Rating value

• user_properties (object) – Optional. User properties. Useful to solve the cold-start problem

• context_items (object-array) –

  Optional. Context items array. Can be used to provide additional context like items in a cart.Contact our support for advanced usage.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• item_properties (object) – Optional. Properties to search similar items.

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

• exclude_rated_items (bool) – Optional. Exclude already rated items from response

• table (string) – Optional. Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves

EXAMPLE QUERY BODY

  {
      "scenario": "generic_home_page",
      "user_id": 123456789,
      "item_id": "123e4567-e89b-12d3-a456-426614174000",
      "amt": 8
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "generic_runtime": [
              {"scenario_type": "alias", "scenario_name": "generic_home_page", "to": "alias"},
              {"scenario_type": "condition", "scenario_name": "generic_conditional_scenario", "to": "then"},
              {"scenario_type": "case", "scenario_name": "use_profile"}
          ],
          "generic_default": [
              {"scenario_type": "case", "scenario_name": "generic_default"}
          ],
          "reco_type": "profile_to_items",
          "runtime": [
              {"scenario_type": "case", "scenario_name": "only_thrillers"}
          ],
          "default": [
              {"scenario_type": "case", "scenario_name": "only_recent_movies"}
          ]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if an item property required by a business rule does not exist

• WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Similar Items Recommendations

GET recommendation/items/<str:item_id>/items/

Note

Authorized Roles: root, manager, backend, frontend

Get similar items.

Query Parameters

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

• user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Only used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics. NOT used to personalize recommendations. Cannot be used together with a session_id.

• session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Only used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics. NOT used to personalize recommendations. Cannot be used together with a user_id.

EXAMPLE QUERY PARAMS

?amt=10&filters=price:lt:10&reranking=genres:diversity:0.75::default_malus:0.25

or with a runtime-scenario and the default one, adding a filter

EXAMPLE QUERY PARAMS

  ?amt=10&scenario=scenario109&filters=price:lt:10

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [
              {"scenario_type": "alias", "scenario_name": "items_page", "to": "alias"}],
              {"scenario_type": "condition", "scenario_name": "is_item_popular", "to": "then"}],
              {"scenario_type": "ab_test", "scenario_name": "ab_test_on_item_categories", "to": "group_b"}],
              {"scenario_type": "case", "scenario_name": "only_thrillers"}
          ],
          "default": [
              {"scenario_type": "case", "scenario_name": "only_recent_movies"}
          ]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• NotFoundError with error name ITEM_NOT_FOUND if the item does not have properties that a business rule requires; and with error name ITEM_PROPERTY_NOT_FOUND if an item property required by a business rule does not exist

• WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Similar Items Recommendations using Item-Properties

POST recommendation/items-properties/items/

Note

Authorized Roles: root, manager, backend, frontend

Get similar items using item properties.

Important:

• At least one text property to activate full-text search.

• The algorithm must have activated real-time content-based.

Request JSON Object

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• item_properties (object) – Properties to search similar items.

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

EXAMPLE QUERY BODY

  {
      "item_properties": {
          "description": "drama thriller comedy",
          "year": 2020
      },
      "amt": 5
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932",
          "c3391d83-543b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70552932",
          "c3391d83-553b-40e7-813e-fcf658ec397d"
      ],
      "next_cursor": null
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if an item property required by a business rule does not exist

• WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Session-Based Items Recommendations

POST recommendation/sessions/items/

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given the ratings or interactions of an anonymous session. Note that the HTTP verb is POST so that ratings can be sent in the body, but the endpoint is stateless as GET. Ratings and interactions are mutually exclusive.

This endpoint supports multiple ways to personalize the recommendations when no history of the user’s item interactions is available, for instance when the user ID itself is not available. The simplest use case is to use an anonymous session ID for which item interactions were previously created. Alternatively, this endpoint also supports sending the item interactions (or equivalently item ratings) directly in the request body.

Compared to the endpoint GET recommendation/users/<str:user_id>/items/, this endpoint is more optimized for capturing short term interactions.

In the special case with no interaction, this endpoint will approximately return the most popular items satisfying the business rules.

Request JSON Object

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Recommendations will be personalized using the item interactions that were previously created for this anonymous session ID. Also used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics. Mutually exclusive with providing ratings or user_id.

• interactions (object-array) –

  Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • interaction_type (O) – Interaction Type

  • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)

• ratings (object-array) –

  Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • rating (float32) – [min: 1 max: 10] Rating value

• user_properties (object) – Optional. User properties. Useful to solve the cold-start problem

• user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Very rarely used, and NOT used to personalize recommendations. Mutually exclusive with providing session_id as a user is either logged-in or anonymous. Only used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics, using a user_id instead of a session_id. Note that after an anonymous user is logging-in, using the user_id is preferred to the former anonymous session_id. However, typically when a user_id is available, it is more common to use the GET recommendation/users/<str:user_id>/items/ endpoint instead of this endpoint.

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

• exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY BODY WITH INTERACTIONS

  {
      "interactions": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "interaction_type": "like",
              "timestamp": 1632759339.123
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "interaction_type": "dislike",
              "timestamp": 1632759339.123
          }
      ],
      "user_properties": {
          "age": 25
      },
      "amt": 10,
      "filters": [
          {"property_name": "tags", "op": "in", "value": ["family", "fiction"]},
          {"property_name": "poster", "op": "notempty"}
      ],
      "exclude_rated_items": true
  }

EXAMPLE QUERY BODY WITH RATINGS

  {
      "ratings": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "rating": 8.5},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "rating": 2.0}
      ],
      "user_properties": {
          "subscriptions": ["channel1", "channel2"]
      },
      "amt": 10,
      "filters": [
          {"property_name": "price", "op": "lt", "value": 10},
          {"property_name": "genres", "op": "eq", "value": "drama"}
      ],
      "exclude_rated_items": true
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [
              {"scenario_type": "alias", "scenario_name": "home", "to": "alias"}],
              {"scenario_type": "ab_test", "scenario_name": "ab_test_on_model_type", "to": "group_a"}],
              {"scenario_type": "case", "scenario_name": "strongly_collaborative_filter"}
          ],
          "default": [
              {"scenario_type": "case", "scenario_name": "future_events_filter"}
          ]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if a filter property to filter on does not exist, with error name USER_PROPERTY_NOT_FOUND if a user property does not exist.

• WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Session-Based Recommendations of Item-Properties

POST recommendation/sessions/items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend, frontend

Get item-property recommendations given the ratings or interactions of an anonymous session. Note that the HTTP verb is POST so that ratings or interactions can be sent in the body, but the endpoint is stateless as GET. Ratings and interactions are mutually exclusive.

Warning: while it may change in the future, current implementation uses an intermediate step selecting items. Consequently, using filters may have a strange behavior that you’re invited to check first, and the filters option may be removed in future versions of the API.

Request JSON Object

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Recommendations will be personalized using the item interactions that were previously created for this anonymous session ID. Also used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics. Mutually exclusive with providing ratings or user_id.

• interactions (object-array) –

  Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • interaction_type (O) – Interaction Type

  • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)

• ratings (object-array) –

  Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • rating (float32) – [min: 1 max: 10] Rating value

• user_properties (object) – Optional. User properties. Useful to solve the cold-start problem

• user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Very rarely used, and NOT used to personalize recommendations. Mutually exclusive with providing session_id as a user is either logged-in or anonymous. Only used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics, using a user_id instead of a session_id. Note that after an anonymous user is logging-in, using the user_id is preferred to the former anonymous session_id. However, typically when a user_id is available, it is more common to use the GET recommendation/users/<str:user_id>/items/ endpoint instead of this endpoint.

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

EXAMPLE QUERY BODY WITH INTERACTIONS

  {
      "interactions": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "interaction_type": "like",
              "timestamp": 1632759339.123
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "interaction_type": "dislike",
              "timestamp": 1632759339.123
          }
      ],
      "user_properties": {
          "age": 25
      },
      "amt": 10,
      "filters": [
          {"property_name": "tags", "op": "in", "value": ["family", "fiction", "drama", "thriller", "comedy"]},
          {"property_name": "poster", "op": "notempty"}
      ]
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• properties (list-of-(string|int|float)) – Item properties. Values type uniquely depends on the property

EXAMPLE RESPONSE

  {
      "properties": ["drama", "thriller", "comedy"],
      "warnings": []
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has trained for this database

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if the property name cannot be found.

• WrongData with error name WRONG_DATA_TYPE if the property cannot be recommended, or if there is no allowlisted trained instance

Get Profile-Based Items Recommendations

GET recommendation/users/<str:user_id>/items/

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given a user profile.

Compared to the endpoint POST recommendation/sessions/items/, this endpoint is more optimized for capturing long term interactions.

In the special case with no interaction, this endpoint will approximately return the most popular items satisfying the business rules.

Query Parameters

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

• exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY PARAMS

  ?amt=10&filters=price:lt:10&filters=genres:eq:drama&filters=tags:in:family,fiction&filters=poster:notempty&exclude_rated_items=true

EXAMPLE QUERY PARAMS

  ?amt=10&scenario=rule109&skip_default_scenario=true

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [{"scenario_type": "case", "scenario_name": "year_filters"}],
          "default": [{"scenario_type": "case", "scenario_name": "favorite_scenario"}]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has trained for this database

• NotFoundError with error name USER_NOT_FOUND if the user does not exist, with error name ITEM_PROPERTY_NOT_FOUND if a filter property to filter on does not exist

• WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid. if the user does not exist, with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Profile-Based Recommendations of Item-Properties

GET recommendation/users/<str:user_id>/items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend, frontend

Get item-property recommendations given a user profile.

Warning: while it may change in the future, current implementation uses an intermediate step selecting items. Consequently, using filters may have a strange behavior that you’re invited to check first, and the filters option may be removed in future versions of the API.

Query Parameters

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

EXAMPLE QUERY PARAMS

  ?amt=10

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• properties (list-of-(string|int|float)) – Item properties. Values type uniquely depends on the property

EXAMPLE RESPONSE

  {
      "properties": ["drama", "thriller", "comedy"],
      "warnings": ["the user had no ratings, used most-popular"]
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has trained for this database

• NotFoundError with error name USER_NOT_FOUND if the user does not exist, with error name ITEM_PROPERTY_NOT_FOUND if the property name cannot be found.

• WrongData with error name WRONG_DATA_TYPE if the property cannot be recommended, or if there is no allowlisted trained instance

Get Items Recommendations for Groups of Users

POST recommendation/users-groups/items/

Note

Authorized Roles: root, manager, backend

Get items recommendations given a group of users. Note that the HTTP verb is POST so that user ids can be sent in the body, but the endpoint is stateless as GET.

Request JSON Object

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• users (object-array) –

  [min_length: 2] Users array

  Inner fields

  • user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID

• consensus_factor (float) – Optional. [min: 0 max: 1] Parameter controlling the consensus between the tastes of the users from the group. Float between 0 and 1 (defaults to 0.5); 0 for no consensus between the users (that is, find a mix from the top items of each individual), 1 for maximal consensus (that is, find the least-worst items among each individual).

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

EXAMPLE QUERY BODY

  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000"
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d"
          },
          {
              "user_id": "e89b1d83-818e-40e7-12d3-174005e89b1d"
          }
      ],
      "consensus_factor": 0.7,
      "amt": 2,
      "filters": [
          {"property_name": "tags", "op": "in", "value": ["family", "fiction"]},
          {"property_name": "poster", "op": "notempty"}
      ]
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [{"scenario_type": "case", "scenario_name": "year_filters"}],
          "default": [{"scenario_type": "case", "scenario_name": "favorite_scenario"}]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Profile-Based Items Recommendations with Context Items

POST recommendation/context-items/users/<str:user_id>/items/

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given a user profile and a set of context items. Note that the HTTP verb is POST so that items ID can be sent in the body, but the endpoint is stateless as GET.

Request JSON Object

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• context_items (object-array) –

  Context items array. Can be used to provide additional context like items in a cart.Contact our support for advanced usage.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

• exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY BODY

  {
      "context_items": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000"},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d"},
          {"item_id": "sdf33000-0011-5fh3-235a-sldkjflsjdcc"}
      ],
      "amt": 10,
      "filters": [
          {"property_name": "price", "op": "lt", "value": 10},
          {"property_name": "genres", "op": "eq", "value": "drama"},
          {"property_name": "tags", "op": "in", "value": ["family", "fiction"]},
          {"property_name": "poster", "op": "notempty"}
      ],
      "exclude_rated_items": true
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [{"scenario_type": "case", "scenario_name": "year_filters"}]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Session-Based Items Recommendations with Context Items

POST recommendation/context-items/sessions/items/

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given the ratings of an anonymous session.and a set of context items. Note that the HTTP verb is POST so that the ratings and items ID can be sent in the body, but the endpoint is stateless as GET.

Request JSON Object

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Recommendations will be personalized using the item interactions that were previously created for this anonymous session ID. Also used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics. Mutually exclusive with providing ratings or user_id.

• interactions (object-array) –

  Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • interaction_type (O) – Interaction Type

  • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)

• ratings (object-array) –

  Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • rating (float32) – [min: 1 max: 10] Rating value

• user_properties (object) – Optional. User properties. Useful to solve the cold-start problem

• user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Very rarely used, and NOT used to personalize recommendations. Mutually exclusive with providing session_id as a user is either logged-in or anonymous. Only used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics, using a user_id instead of a session_id. Note that after an anonymous user is logging-in, using the user_id is preferred to the former anonymous session_id. However, typically when a user_id is available, it is more common to use the GET recommendation/users/<str:user_id>/items/ endpoint instead of this endpoint.

• context_items (object-array) –

  Context items array. Can be used to provide additional context like items in a cart.Contact our support for advanced usage.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

• reranking (list-of-object) –

  Optional. Reranking business rules to apply [see Reranking on Item Property]

  Inner fields

  • property_name (string) – Item-property name. Used for diversity reranking rules.

  • op (enum) – choices: [diversity] Reranking op

  • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

  • options (object) – Op-specific options

    Inner fields

    • activation_period (int) –

    • max_activation_count (int) –

    • default_malus (float) –

• exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY BODY

  {
      "context_items": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000"},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d"},
          {"item_id": "sdf33000-0011-5fh3-235a-sldkjflsjdcc"}
      ],
      "amt": 10,
      "filters": [
          {"property_name": "price", "op": "lt", "value": 10},
          {"property_name": "genres", "op": "eq", "value": "drama"},
          {"property_name": "tags", "op": "in", "value": ["family", "fiction"]},
          {"property_name": "poster", "op": "notempty"}
      ],
      "exclude_rated_items": true
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

• next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [{"scenario_type": "case", "scenario_name": "year_filters"}]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance

Get Precomputed Similar Items Recommendations

GET recommendation/precomputed/items/<str:item_id>/items/

Note

Authorized Roles: root, manager, backend, frontend

Get precomputed similar items. When using precomputed recommendations, recommendations are computed and stored in advance. All filtering and other business rules are already applied, and this endpoint simply retrieves stored recommendations.

Precomputed recommendations typically allow for more customization of business rules and of the final recommendations, but are not updated frequently. If you need real-time features such as:

• live filtering or live business rules;

• new items handling (you cannot wait a day for new items to have personalized recommendations, and for new items to appear in recommendations;

Then consider using the real-time endpoint. Internal notes: When using a custom table, the table should be with LOCAL connection, have no compressions and have resource equal to ITEM_TO_ITEMS_RECO. The table format must be indexed raw data file.

Query Parameters

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• table (string) – Optional. Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves

• user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Only used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics. NOT used to personalize recommendations. Cannot be used together with a session_id.

• session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Only used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics. NOT used to personalize recommendations. Cannot be used together with a user_id.

EXAMPLE QUERY PARAMS

?scenario=scenario_name

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "evaluated_scenarios": {
          "runtime": [{"scenario_type": "case", "scenario_name": "favorite_scenario"}]
      }
  }

Errors:

• WrongData with error name WRONG_DATA_TYPE if the table has wrong params or not compatible with this endpoint

• NotFoundError with error name TABLE_NOT_FOUND if the table name does not exist, with error name ITEM_NOT_FOUND if the item does not exist, with error name SCENARIO_NOT_FOUND` if the scenario does not exist

Get Precomputed Profile-Based Items Recommendations

GET recommendation/precomputed/users/<str:user_id>/items/

Note

Authorized Roles: root, manager, backend, frontend

Get item recommendations given a user profile, from a precomputed file.

When using precomputed recommendations, recommendations are computed and stored in advance. All filtering and other business rules are already applied, and this endpoint simply retrieves stored recommendations.

The main use-case for precomputed recommendations based on a user profile is emailing and other campaigns. While precomputed recommendations allow for more customization of business rules and of the final recommendations, they are not updated frequently and we typically recommend using live recommendations for use on your website or on your app for best results.

Internal notes: When using a custom table, the table should be with LOCAL connection, have no compressions and have resource equal to USER_TO_ITEMS_RECO. The table format must be indexed raw data file.

Query Parameters

• scenario (string) – Optional. Name of scenario to apply [see About Scenarios]

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• table (string) – Optional. Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves

EXAMPLE QUERY PARAMS

?scenario=scenario_name

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "evaluated_scenarios": {
          "runtime": [
              {"scenario_type": "ab_test", "scenario_name": "my_ab_test"},
              {"scenario_type": "case", "scenario_name": "year_filters"}
          ]
      }
  }

Errors:

• WrongData with error name WRONG_DATA_TYPE if the table has wrong params or not compatible with this endpoint

• NotFoundError with error name TABLE_NOT_FOUND if the table name does not exist, with error name USER_NOT_FOUND if the user does not exist