MoEngage Recommendations API

openapi: 3.2.0
info:
  title: MoEngage Recommendation Recommendations API
  description: 'This API lets you fetch/retrieve the metadata associated with a recommendation using the recommendation ID. The metadata can include the recommendation name, model type, status, creation and update time, and so on.


    Authentication is via Basic Auth.

    '
  version: '1.0'
servers:
- url: https://api-{dc}.moengage.com/v1
  variables:
    dc:
      default: '01'
      description: The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101.
security:
- basicAuth: []
tags:
- name: Recommendations
  description: Operations related to fetching recommendation configurations and results.
paths:
  /recommendations/{recommendations_id}:
    get:
      tags:
      - Recommendations
      summary: Fetch Recommendation Details
      operationId: fetchRecommendationMetadata
      description: 'This API retrieves the metadata associated with a specific recommendation setup using its unique ID. The metadata can include the recommendation name, model type, status, creation and update time, and so on.

        '
      x-mint:
        content: '#### Rate Limit

          You can fetch 1,000 recommendations per minute.

          '
      parameters:
      - $ref: '#/components/parameters/AppKeyHeader'
      - $ref: '#/components/parameters/RecommendationIdPath'
      responses:
        '200':
          description: Indicates that the request is successful and a recommendation is fetched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationMetadata'
        '400':
          description: Bad request. Possible issues include a recommendation, the user does not exist, or the wrong format provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                recommendation_not_found:
                  summary: Recommendation Not Found
                  value:
                    error-code: recommendation does not exist
                    message: Recommendation does not exist or archived. Please check recommendation_id.
                invalid_format:
                  summary: Invalid Format
                  value:
                    error-code: invalid-request-format
                    message: Invalid format provided for recommendation_id.
        '401':
          description: Unauthenticated. Your request is unauthorized. Verify your credentials and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error-code: request-unauthenticated
                message: Your request is unauthorized. Please verify your credentials and try again.
        '413':
          description: Request entity too large. The request body can be large in terms of size (bytes) or length of items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error-code: payload-size-exceeded
                message: Your payload size exceeds the 1MB limit. Please reduce the payload size and try again.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error-code: unexpected-error
                message: Something went wrong with your request. Please contact the MoEngage team for further assistance.
  /recommendations/{recommendations_id}/items:
    post:
      tags:
      - Recommendations
      summary: Fetch Recommendation Results
      operationId: fetchRecommendationResults
      description: 'This API fetches/retrieves the metadata results of any recommendations for a user based on their user ID and item ID.

        '
      x-mint:
        content: '#### Rate Limit

          You can fetch 10,000 recommendations per minute.

          '
      parameters:
      - $ref: '#/components/parameters/AppKeyHeader'
      - $ref: '#/components/parameters/RecommendationIdPath'
      - name: RECOMMENDATION-TYPE
        in: header
        required: true
        description: It represents the type of recommendations from which the results are fetched.
        schema:
          type: string
          enum:
          - user_action
          - item_attribute
          - catalog_alert
          - similar_item
          - frequently_viewed_together
          - frequently_bought_together
          - trending_item
          - user_personalization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchResultsRequest'
            example:
              user_id: user123@example.com
              item_id: product_sku_abc
              include_fields:
              - title
              - image_link
              - price
      responses:
        '200':
          description: Indicates that the request is successful and a recommendation is fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecommendationResultItem'
        '400':
          description: Bad request. Possible issues include a recommendation, the user does not exist, or the wrong format provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error-code: recommendation does not exist
                message: Recommendation does not exist or archived. Please check recommendation_id.
        '401':
          description: Unauthenticated. Your request is unauthorized. Verify your credentials and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error-code: request-unauthenticated
                message: Your request is unauthorized. Please verify your credentials and try again.
        '413':
          description: Request entity too large. The request body can be large in terms of size (bytes) or length of items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error-code: payload-size-exceeded
                message: Your payload size exceeds the 1MB limit. Please reduce the payload size and try again.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error-code: unexpected-error
                message: Something went wrong with your request. Please contact the MoEngage team for further assistance.
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error-code:
          type: string
          description: Each error code is unique and serves as a shorthand representation for the type of error.
        message:
          type: string
          description: With the error code, a detailed message is also provided in the response describing the specifics of the request failure and the nature of the error.
    Filter:
      type: object
      properties:
        executed:
          type: boolean
        filter_type:
          type: string
          example: product_filter
        operator_fe:
          type: string
          example: exists
        name:
          type: string
          example: product_id
        data_type:
          type: string
          example: string
        operator:
          type: string
          example: exists
        value:
          type:
          - string
          - 'null'
        negate:
          type: boolean
        case_sensitive:
          type: boolean
        hasError:
          type: boolean
    IncludeExcludeFilters:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
        filter_operator:
          type: string
          enum:
          - and
          - or
    TrendSettings:
      type: object
      description: Defines the trend type and duration (Specific fields depend on implementation).
      properties: {}
      example:
        trend_type: most_viewed
        duration_days: 7
    SortCriteria:
      type: object
      properties:
        data_type:
          type: string
          example: double
        param_type:
          type: string
          example: product_attribute
        param:
          type: string
          example: price
        direction:
          type: string
          enum:
          - '1'
          - '-1'
          description: 1 for ascending, -1 for descending
    CustomSettings:
      type: object
      properties:
        item_filters:
          type: object
          properties:
            user_actions:
              type: object
      description: Defines custom filters applied to recommendations.
    RecommendationResultItem:
      type: object
      description: The items JSON object contains the key-value pairs of all the requested attributes.
      properties:
        item_id:
          type: string
          description: This field shows the ID of the item.
        title:
          type: string
          description: This field shows the title of the item.
        link:
          type: string
          format: uri
          description: This field shows a link to the item.
        image_link:
          type: string
          format: uri
          description: This field shows a link to the image.
        catalog_id:
          type: string
        feed_id:
          type: string
        description:
          type: string
        price_currency:
          type: string
        creation_date:
          type: string
          format: date-time
        last_updated:
          type: string
          format: date-time
        price:
          type: number
          format: double
        date:
          type: string
          format: date
      additionalProperties: true
      example:
        item_id: prod_xyz
        title: Stylish Red Scarf
        link: https://example.com/products/prod_xyz
        image_link: https://example.com/images/prod_xyz.jpg
        price: 19.99
    FetchResultsRequest:
      type: object
      required:
      - user_id
      properties:
        user_id:
          type: string
          description: 'A user ID is a unique identifier that represents a user. You can obtain the user_id from the user info page. For more information, refer to [User Identity Management](/user-guide/data/user-data/unified-identity-identity-resolution).

            '
        item_id:
          type:
          - string
          - 'null'
          description: 'An `item_id` is a unique identifier assigned to each item in the catalog.


            If the `RECOMMENDATION-TYPE` is any of the `similar_item`, `frequently_viewed_together`, or `frequently_bought_together`, you must provide the `item_id`.


            This `item_id` acts as the anchor to serve recommended items based on the `RECOMMENDATION-TYPE`.


            We expect the user''s most recently interacted `item_id` to serve contextually recommended items.

            '
        include_fields:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'You can define the attributes of items you require from the catalog in the recommendation response. For example, `title`, `price`, `link`, `image_link`, and so on.


            If the attributes above are not defined, all item attributes in the catalog will be included in the response. The response size may increase depending on the number of attributes in the catalog. Therefore, it is recommended that only the necessary attributes be specified.

            '
          example:
          - title
          - price
          - image_link
    RecommendationMetadata:
      type: object
      properties:
        id:
          type: string
          description: It is the unique recommendation ID.
        db_name:
          type: string
          description: This is your workspace name.
        recommendation_type:
          type: string
          description: 'It represents the type of recommendations from which the results will be fetched.

            The supported values are: `user_action`, `item_attribute`, `similar_item`, `frequently_viewed_together`, `frequently_bought_together`, `trending_item`, `user_personalization`.

            '
        name:
          type: string
          description: This field represents the name of the recommendation for which you want to fetch the details.
        description:
          type:
          - string
          - 'null'
          description: This field describes the recommendation given at the time of its creation.
        catalog:
          type: string
          description: This is the unique identifier of the catalog assigned to the requested recommendation.
        status:
          type: string
          description: The recommendation's status indicates whether it is active or archived.
        created_time:
          type: string
          format: date-time
          description: This field shows the timestamp when a recommendation was created.
        updated_time:
          type: string
          format: date-time
          description: This field shows the timestamp when a recommendation setting was last modified.
        all_user_actions:
          type:
          - boolean
          - 'null'
          description: 'This key represents whether all user actions are being considered to find the most recently interacted item. If this is true, the most recently interacted ID from any of the user action set-ups will be considered to find the related items as per the recommendation type.


            **Note**: This key is available with the `similar_item`, `frequently_viewed_together`, and `frequently_bought_together` recommendation types.

            '
        include_filters:
          $ref: '#/components/schemas/IncludeExcludeFilters'
        exclude_filters:
          $ref: '#/components/schemas/IncludeExcludeFilters'
        custom_settings:
          $ref: '#/components/schemas/CustomSettings'
          description: This key defines the customization applied to the recommendation results as per the recommendation setup. Currently, you can apply the user action and item attribute filters over recommendations.
        sort:
          $ref: '#/components/schemas/SortCriteria'
          description: 'This key defines the sorting logic based on which recommendation results will be ordered. This object''s value provides the attributes'' details and sorting order.


            **Note**: This key is available with the `user_action` and `item_attribute` recommendation types.

            '
        trends:
          $ref: '#/components/schemas/TrendSettings'
          description: 'This key defines the trend type for `trending_item` recommendations and the duration of trend computation.


            **Note**: This key is available with the `trending_item` recommendation type.

            '
  responses:
    TooManyRequests:
      description: Too Many Requests. There won't be any response body for this request.
      headers:
        x-ratelimit-limit:
          schema:
            type: integer
          description: The maximum number of requests that the consumer is permitted to make in a given time window.
        x-ratelimit-remaining:
          schema:
            type: integer
          description: The number of requests remaining in the current rate limit window.
        x-ratelimit-reset:
          schema:
            type: integer
          description: The time at which the current rate limit window resets in UTC epoch seconds.
  parameters:
    AppKeyHeader:
      name: MOE-APPKEY
      in: header
      required: true
      description: 'This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.

        '
      schema:
        type: string
    RecommendationIdPath:
      name: recommendations_id
      in: path
      required: true
      description: 'This parameter indicates the unique identifier associated with the recommendation created in the recommendation module.


        You can obtain the `recommendation_id` from the recommendation you created on the recommendation page.

        '
      schema:
        type: string
      example: a1b2c3d4e5f6a7b8c9d0e1f2
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format ''username:password''.


        - **Username**: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.

        - **Password**: Use your API Key, which you can find within the **Campaign report/Business events/Custom templates/Catalog API/Inform Report** tile.


        For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).

        '