BlueConic Recommendations API

openapi: 3.2.0
info:
  title: BlueConic REST API v2 Recommendations API
  description: Welcome to the BlueConic REST API v2.
  termsOfService: https://www.blueconic.com/blueconic-terms-and-conditions
  contact:
    name: Contact us
    url: https://support.blueconic.com/hc/en-us/requests/new
  license:
    name: BlueConic
    url: https://github.com/blueconic/openapi/blob/main/LICENSE.MD
  version: '100.0'
servers:
- url: https://{blueconicHostname}/rest/v2
  description: The BlueConic server
  variables:
    blueconicHostname:
      description: BlueConic server hostname, e.g. 'tenant.blueconic.net'
      default: tenantname
tags:
- name: Recommendations
  description: Generate individualized content and product recommendations for a given profile. Read more. To work with recommendations, you have to set up a content collector or a product collector.
paths:
  /recommendations:
    post:
      tags:
      - Recommendations
      summary: Generate recommendations
      description: Generate BlueConic recommendations for a specific profile based on the provided parameters.
      operationId: getRecommendationsPostJsonpAsync
      parameters:
      - name: profileId
        in: query
        description: The ID of the BlueConic profile. Note that the profile ID is required when you use a [recommendation algorithm](https://support.blueconic.com/hc/en-us/articles/360022093313-BlueConic-recommendation-algorithms) that depends on the profile, such as 'Collaborative filtering' or 'Seen articles / Seen products'.
        schema:
          type: string
        example: 640d01c7-1c30-4085-adf9-afad6560ec99
      - name: storeId
        in: query
        description: The ID of the content store to get the items from.
        required: true
        schema:
          type: string
        example: 0693330e-679a-48db-b94f-a8921b76149e
      - name: itemId
        in: query
        description: ID of the current item being shown. Some algorithms are based on this information. It also excludes this item from being returned in the result.
        schema:
          type: string
      - name: frequencyCap
        in: query
        description: The number of times an item can be recommended to a profile before being hidden from future recommendations.
        schema:
          type: integer
          format: int32
        example: 5
      - name: imageWidth
        in: query
        description: Width of the images to return.
        schema:
          type: integer
          format: int32
        example: 100
      - name: imageHeight
        in: query
        description: Height of the images to return.
        schema:
          type: integer
          format: int32
        example: 100
      - name: manualViewCounting
        in: query
        description: Prevent updating recommendation statistics for the recommended items. Can be used to generate offline recommendation items without influencing the profile.
        schema:
          type: boolean
          default: false
        example: true
      requestBody:
        description: "The body of a recommendations request consists of a JSON array that holds one or more sets of recommendation definition objects. Each recommendation definition object contains a combination of algorithms and filters and a number of items that should be returned. This allows you to return items based on different mixes of algorithms. You can also define a default to fall back to when not enough matching recommendations can be found.\n\nThe following [boosting algorithms](https://support.blueconic.com/hc/en-us/articles/360022093313-BlueConic-recommendation-algorithms#breaking-news-top-products-based-on-the-recent-view-field--0-0) are supported:\n\n|Name|Description|Example|\n|:----|:----|:----|\n|Breaking news|Items most viewed by all visitors in the time frame defined in the collector.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENT_VIEW\"}]`\n|Top carted items|Items most added to shopping carts by all visitors in the time frame defined in the collector.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENT_SHOPPINGCART\"}]`\n|Top ordered items|Items most ordered by all visitors in the time frame defined in the collector.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENT_ORDER\"}]`\n|Viral news|Items most used as a landing page by all visitors in the time frame defined in the collector.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENT_ENTRYPAGE\"}]`\n|Recency|Items most recently added items based on the publication date property.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENCY\"}]`\n|Recent high CTRs|Items most clicked-through from BlueConic recommendations by all visitors in the time frame defined in the collector.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENT_CTR\"}]`\n|Recently bought items|Items recently bought by the provided profileId.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENTLY_BOUGHT\"}]`\n|Recently carted items|Items recently put in the shopping cart by the provided profileId.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"RECENTLY_SHOPPINGCART\"}]`\n|Same category|Items of the same category as the item with the provided itemId.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"SAME_CATEGORY\" }]`\n|Look-alike-articles|Items that have similar content to the item with the provided itemId.|`\"boosts\": [{\"value\": 1, \"algorithm\": \" LOOK_ALIKE\" }]`\n|Seen articles|Items the provided profileId recently viewed.|`\"boosts\": [{\"value\": 1, \"algorithm\": \" RECENTLY_VIEWED\" }]`\n|Same interest|Items that look similar to the items already viewed by the provided profileId.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"INTEREST\", \"rampUp\": \"FAST\"}]`\n|Collaborative filtering|Items popular with other profiles who viewed the same items as the provided profileId.|`\"boosts\": [{\"value\": 1, \"algorithm\": \"COLLABORATIVE_FILTERING\", \"rampUp\": \"FAST\"}]`|\n\nRecommendation definition objects may contain filters that restrict the items that will be returned. \n\nFormat:  \n`\"filters\": [\"<property ID>\":<absolute literal value>,<absolute literal value2>\"]`  \nto only include items that have a specific value for a specific profile property.\n\nUse the `!` before the property to **exclude** items. Format:  \n`\"filters\": [\"!<property ID>\":<absolute literal value>,<absolute literal value2>\"]`  \n\nYou can also use the comparison operators `<`, `>`, `<=`, `>=` for data type number, date time, currency, and decimal properties. \nFor example `\"filters\": [\"<property ID>\">=<absolute literal value>,<absolute literal value2>\"]`\n\nWhen combining multiple filters, these have an implicit AND relation.  \nTo combine filters, follow the format `\"filters\": [\"<property ID>\":<absolute literal value>,<absolute literal value2>\", \"<property ID2>\":<absolute literal value3>,<absolute literal value4>\"].`\n\nProfile property value filtering can be done by explicitly passing an absolute literal value. You can’t reference another profile property in the filter or use relative dates (for example, 14 days ago).\n\nSee examples below.\n\n| Example                                                  | Description                                                                                                                                                                          |\n|:---------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `\"filters\": [\"VIEWED\"]`                                  | Exclude the items already viewed by the provided profileId.                                                                                                                          |\n| `\"filters\": [\"SHOPPINGCART\"]`                            | Exclude the items in the shopping cart of the provided profileId.                                                                                                                    |\n| `\"filters\": [\"BOUGHT\"]`                                  | Exclude the items already bought by the provided profileId.                                                                                                                          |\n| `\"filters\": [\"VIEWED_ONLY\"]`                             | Include only items that were viewed by the provided profileId.                                                                                                                       |\n| `\"filters\": [\"SHOPPINGCART_ONLY\"]`                       | Include only items that were in the shopping cart of the provided profileId.                                                                                                         |\n| `\"filters\": [\"BOUGHT_ONLY\"]`                             | Include only items that were bought by the provided profileId.                                                                                                                       |\n| `\"filters\": [\"SAME_CATEGORY\"]`                           | Include only items that have the same category as the provided itemId.                                                                                                               |\n| `\"filters\": [\"IN_STOCK\"]`                                | Include only items that are in stock.                                                                                                                                                |\n| `\"filters\": [\"publicationDate>2023-06-01T00:00+02:00\"]`  | Include only items with a publication date after June 1<sup>st</sup> 2023. The format of publicationDate is `2023-01-01T00:00Z` or with a time zone offset `2023-01-01T00:00+05:00`  |\n| `\"filters\": [\"publicationDate<=2023-06-01T00:00+02:00\"]` | Include only items with a publication date before June 1<sup>st</sup> 2023. The format of publicationDate is `2023-01-01T00:00Z` or with a time zone offset `2023-01-01T00:00+05:00` |\n| `\"filters\": [\"category:politics\"]`                       | Include only items that have a specific value for a specific property, e.g. “politics” for property “category”.                                                                      |\n| `\"filters\": [\"!category:politics\"]`                      | Exclude items that do not have a specific value, e.g. “politics” for property “category”.                                                                                            |\n| `\"filters\": [\"category:politics\",\"category:sports\"]`     | Include only items that have all specific values, e.g. “politics” and “sports” for property “category”.                                                                              |\n| `\"filters\": [\"category:politics,sports\"]`                | Include only items that have any of the specified values, e.g. “politics” or “sports” for property “category”.                                                                       |\n| `\"filters\": [\"!category:politics\",\"!category:sports\"]`   | Include only items that do not have any of the specified values, e.g. “politics” or “sports” for property “category”.                                                                |\n| `\"filters\": [\"!category:politics,sports\"]`               | Include only items that do not have all of the specified values, e.g. “politics” and “sports” for property “category”.                                                               |\n| `\"filters\": [\"hasproperty:image\"]`                       | Include only items that have an image.                                                                                                                                               |\n"
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RecommendationRequest'
            examples:
              Example body:
                description: Example body
                value: "[{\n        \"id\": \"first\",\n        \"boosts\": [{\n                \"value\": \"1\",\n                \"algorithm\": \"RECENCY\"\n            },\n            {\n                \"value\": \"2\",\n                \"algorithm\": \"COLLABORATIVE_FILTERING\",\n                \"rampUp\": \"FAST\"\n            },\n            {\n                \"value\": \"1\",\n                \"algorithm\": \"RECENT_VIEW\"\n            },\n            {\n                \"value\": \"1\",\n                \"algorithm\": \"RECENT_CTR\"\n            }\n        ],\n        \"filters\": [\n            \"category:politics\",\n            \"viewed\"\n        ],\n        \"count\": 3\n    },\n    {\n        \"id\": \"second\",\n        \"boosts\": [{\n                \"value\": \"2\",\n                \"algorithm\": \" COLLABORATIVE_FILTERING \",\n                \"rampup\": \"SLOW\"\n            },\n            {\n                \"value\": \"1\",\n                \"algorithm\": \" RECENT_CTR\"\n            }\n        ],\n        \"filters\": [\n            \"category:politics\",\n            \"!category:economie\",\n            \"VIEWED\"\n        ],\n        \"count\": 3\n    },\n    {\n        \"id\": \"default\",\n        \"filters\": [\n            \"publicationDate>2023-04-17T14:30+02:00\",\n            \"!category:economie\",\n            \"VIEWED\"\n        ],\n        \"boosts\": [{\n            \"value\": \"1\",\n            \"algorithm\": \"RECENT_CTR\"\n        }]\n    }\n]"
        required: true
      responses:
        '200':
          description: The generated recommendations, based on the given request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationResponse'
              examples:
                Example recommendation response:
                  description: Example recommendation response
                  value: "{\n    \"recommendationBlock\": [{\n            \"id\": \"first\",\n            \"recommendations\": [{\n                    \"score\": 0.12063565363854145,\n                    \"trackingUrl\": \"http://taylor-news.com/1\",\n                    \"id\": \"www.taylor-news.com/news/1111\",\n                    \"url\": \"https://www.taylor-news.com/news/1111\",\n                    \"name\": \"Name 1\",\n                    \"description\": \"Description 1.\",\n                    \"category\": [\"sport\", \"baseball\"],\n                    \"image\": \"https://img.taylor-news.com/img1.jpg\",\n                    \"customProperties\": {\n                        \"pubdate\": [\"tuesday 12 june 2023, 09:45\"],\n                        \"story\": []\n                    }\n                },\n                {\n                    \"score\": 0.001113261296046081,\n                    \"trackingUrl\": \"http://taylor-news.com/2\",\n                    \"id\": \"www.taylor-news.com/news/2222\",\n                    \"url\": \"https://www.taylor-news.com/news/2222\",\n                    \"name\": \"Name 2\",\n                    \"description\": \"Description 2.\",\n                    \"category\": [\"news\", \"politics\"],\n                    \"image\": \"https://img.taylor-news.com/img2.jpg\",\n                    \"customProperties\": {\n                        \"pubdate\": [\"wednesday 13 june 2023, 09:45\"],\n                        \"story\": []\n                    }\n                }\n            ]\n        },\n        {\n            \"id\": \"second\",\n            \"recommendations\": [{\n                    \"score\": 1.0,\n                    \"trackingUrl\": \"http://taylor-news.com/3\",\n                    \"id\": \"www.taylor-news.com/news/3333\",\n                    \"url\": \"https://www.taylor-news.com/news/2317578\",\n                    \"name\": \"Name 3\",\n                    \"description\": \"Description 3.\",\n                    \"category\": [\"sport\", \"basketball\"],\n                    \"image\": \"https://img.taylor-news.com/img3.jpg\",\n                    \"customProperties\": {\n                        \"pubdate\": [\"tuesday 12 june 2023, 09:45\"],\n                        \"story\": []\n                    }\n                },\n                {\n                    \"score\": 1.0,\n                    \"trackingUrl\": \"http://taylor-news.com/4\",\n                    \"id\": \"www.taylor-news.com/news/4444\",\n                    \"url\": \"https://www.taylor-news.com/news/2317578\",\n                    \"name\": \"Name 4\",\n                    \"description\": \"Description 4.\",\n                    \"category\": [],\n                    \"image\": \"https://img.taylor-news.com/img4.jpg\",\n                    \"customProperties\": {\n                        \"pubdate\": [\"tuesday 12 june 2023, 09:45\"],\n                        \"story\": []\n                    }\n                }\n            ]\n        }\n    ],\n    \"recommendationId\": \"97258279-baf7-45de-aab3-457dc42904be\",\n    \"trackingPixel\": \"http://track.com\"\n}"
        '400':
          description: One or more required parameters are missing or invalid.
        '503':
          description: The server is too busy to handle the request.
components:
  schemas:
    RecommendationSubResponse:
      type: object
      description: The recommendation blocks as defined in the request body.
      properties:
        id:
          type: string
          description: The ID for this recommendation block, as defined in the request body.
        recommendations:
          type: array
          description: The recommendations of this block.
          items:
            $ref: '#/components/schemas/RecommendationItem'
    Boost:
      type: object
      description: The algorithms that will be executed to determine the recommendations with their boost value and parameters.
      example:
      - value: '1.5'
        algorithm: RECENCY
      properties:
        algorithm:
          type: string
          description: Available boosting algorithms
          enum:
          - COLLABORATIVE_FILTERING
          - INTEREST
          - LOOK_ALIKE
          - RECENCY
          - RECENT_CTR
          - RECENT_ENTRYPAGE
          - RECENT_ORDER
          - RECENT_SHOPPINGCART
          - RECENT_VIEW
          - RECENTLY_BOUGHT
          - RECENTLY_SHOPPINGCART
          - RECENTLY_VIEWED
          - SAME_CATEGORY
        rampUp:
          type: string
          description: Ramp up value for algorithms that use it
          enum:
          - INSTANT
          - VERY_SLOW
          - SLOW
          - NORMAL
          - FAST
        value:
          type: number
          format: double
          description: 'Boost value can be a whole or half number: 1, 1.5, 2, 2.5, …, 9.5, 10.'
      required:
      - algorithm
      - value
    RecommendationRequest:
      type: object
      properties:
        boosts:
          type: array
          description: The algorithms that will be executed to determine the recommendations with their boost value and parameters.
          example:
          - value: '1.5'
            algorithm: RECENCY
          items:
            $ref: '#/components/schemas/Boost'
        count:
          type: integer
          format: int32
          description: The maximum number of items that should be returned for this definition.
          example: 5
        filters:
          type: array
          description: Item filters, see description.
          example:
          - category:news
          - viewed
          items:
            type: string
            description: Item filters, see description.
            example: '["category:news","viewed"]'
        id:
          type: string
          description: 'The order of execution of the definition objects: ''first'' will be executed first, ''second'' will be executed next. If the total count has not been reached, the remainder items will be from the ''default'' definition.'
          example: first
      required:
      - boosts
      - id
    RecommendationItem:
      type: object
      description: The recommendations of this block.
      properties:
        category:
          type: array
          items:
            type: string
        customProperties:
          type: object
          additionalProperties:
            type: array
            description: The properties of this item.
            items:
              type: string
              description: The properties of this item.
          description: The properties of this item.
        description:
          type: string
        id:
          type: string
          description: The ID of this item.
        image:
          type: string
          description: The image of this item.
        name:
          type: string
        publicationDate:
          type: string
          description: The publication date of this item.
        score:
          type: number
          format: double
          description: The recommendation score.
        trackingUrl:
          type: string
          description: The recommendation tracking url.
        url:
          type: string
          description: The url of this item.
    RecommendationResponse:
      type: object
      properties:
        recommendationBlock:
          type: array
          description: The recommendation blocks as defined in the request body.
          items:
            $ref: '#/components/schemas/RecommendationSubResponse'
        recommendationId:
          type: string
          description: The unique ID for this recommendation request.
        trackingPixel:
          type: string
          description: The tracking pixel to track this recommendation request.
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Authenticates a registered OAuth 2.0 client. The Authorization code flow and Client credentials flow are supported. Make sure to select the correct flow based on which flow the registered client supports. The client id and client secret can be found in BlueConic by opening the registered client under *Settings* > *Access management* > *Applications*.<br/>**NOTE:** When using the Authorization code flow, the redirect URL of the registered client in BlueConic must be set to `https://rest.apidoc.blueconic.com/oauth-receiver.html` and ''Send Proof Key for Code Exchange'' must be enabled.<br/><br/>To use a Bearer token for authentication, follow these steps: <br/>1. Acquire the token through authentication.<br/>2. Include the token in the request''s Authorization header as Bearer \<token\>.<br/>3. Send the request to access protected resources.<br/>4. Handle token expiration by refreshing or obtaining a new token.'
      flows:
        clientCredentials:
          tokenUrl: /rest/v2/oauth/token
        authorizationCode:
          authorizationUrl: /rest/v2/oauth/authorize
          tokenUrl: /rest/v2/oauth/token
          refreshUrl: /rest/v2/oauth/token