Optimizely Recommendations API

openapi: 3.2.0
info:
  title: Optimizely Recommendations API
  version: '1.0'
  description: 'Operations tagged Recommendations across 3 of this provider''s published API definitions: optimizely-data-platform-recommendations-openapi.json, optimizely-recommendations-public-api-spec-openapi.yaml, optimizely-web-experimentation-optimizely-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.us1.odp.optimizely.com/v3
  description: United States
- url: https://api.eu1.odp.optimizely.com/v3
  description: Europe
- url: https://api.au1.odp.optimizely.com/v3
  description: Asia-Pacific
- url: https://{hostname}/1.0
  description: Primary API server
  variables:
    hostname:
      default: api.usea01.idio.episerver.net
      enum:
      - api.apac01.idio.episerver.net
      - api.caea01.idio.episerver.net
      - api.emea01.idio.episerver.net
      - api.usea01.idio.episerver.net
- url: https://api.optimizely.com/v2
tags:
- name: Recommendations
paths:
  /recommendations/products:
    get:
      tags:
      - Recommendations
      summary: Get Recommended Products
      description: Get recommendations for a customer or product.
      operationId: get-recommended-products
      parameters:
      - name: '{identifier}=identifier_value'
        in: query
        description: 'The identifier type and its value. Acceptable identifier types include: `vuid`, `email`, `zaiusalias`, and `customer_id`.'
        schema:
          type: string
        examples:
          Email Identifier:
            description: Email Identifier
            value:
              email: sample@test.com
      - name: product_ids
        in: query
        description: A comma-separated list of product IDs. Using the `product_ids` parameter allows you to generate recommended products based on the product IDs passed in.
        schema:
          type: string
      - name: type
        in: query
        description: 'The type of recommendation requested. Acceptable values are: `personal` and `contextual`.'
        schema:
          type: string
          enum:
          - personal
          - contextual
      - name: criteria
        in: query
        description: Filter criteria applied to the recommendations returned. you can use any field on the product schema to filter. See above for the filter construct.
        schema:
          type: object
      - name: sort_by
        in: query
        description: Product field to sort by, which can be any base or custom field defined in your Product schema. Default sort is highest to lowest recommendation rank. Changing this will not change which products are returned, only the order in which they display in the array.
        schema:
          type: string
      - name: order
        in: query
        description: Options are `asc` and `desc`. Order in which to sort the resulting products. Changing this will not change which products are returned, only the order in which they display in the array. This will not change the order of products if there is no sort specified.
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: limit
        in: query
        description: The number of products to return. Must be an integer value from 1 to 100. Default is 10.
        schema:
          type: string
          default: 10
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recommendation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                example: '{"title":"Bad Request","status":400,"timestamp":"2018-09-10T21:07:10-05:00","detail":{"invalids":[{"field":"delimiter","reason":"Unrecognized delimiter, valid options are comma, tab or pipe"}]}}'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                example: '{  "message": "Forbidden"}'
      security:
      - x-api-key: []
    servers:
    - url: https://api.us1.odp.optimizely.com/v3
      description: United States
    - url: https://api.eu1.odp.optimizely.com/v3
      description: Europe
    - url: https://api.au1.odp.optimizely.com/v3
      description: Asia-Pacific
  /recommendations/{id}:
    parameters:
    - $ref: '#/components/parameters/recommendationGUID'
    patch:
      operationId: recommendationUpdate
      summary: Update recommendation
      description: Mark a pending recommendation as read.
      tags:
      - Recommendations
      requestBody:
        required: true
        description: New pending state
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendationFlag'
      responses:
        '202':
          description: Recommendation update accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              example:
                message: ''
        '404':
          description: Recommendation does not exist.
      security:
      - key: []
    servers:
    - url: https://{hostname}/1.0
      description: Primary API server
      variables:
        hostname:
          default: api.usea01.idio.episerver.net
          enum:
          - api.apac01.idio.episerver.net
          - api.caea01.idio.episerver.net
          - api.emea01.idio.episerver.net
          - api.usea01.idio.episerver.net
  /recommendations/catalogs/{catalog_id}/catalog/{date}:
    get:
      description: Download a CSV with all current catalog data
      operationId: get_recs_catalog_csv
      parameters:
      - description: A string in JSON format that includes all the fields to create a Custom Event
        in: path
        name: date
        required: true
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
      - description: The Catalog ID of the Catalog you want to download
        in: path
        name: catalog_id
        required: true
        schema:
          pattern: ^\d+$
          type: string
      responses:
        '200':
          description: Return the CSV with correct headers to force download
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid request body supplied
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid credentials
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: You do not have access to the specified Project
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download a CSV with all current catalog data
      tags:
      - Recommendations
      security:
      - apiKey: []
      - OAuth2:
        - read
        - write
    servers:
    - url: https://api.optimizely.com/v2
  /recommendations/catalogs/{catalog_id}/recommenders/{recommender_id}/{date}:
    get:
      description: Download a CSV with all computed recommendations output data
      operationId: get_recs_output_csv
      parameters:
      - description: A string in JSON format that includes all the fields to create a Custom Event
        in: path
        name: date
        required: true
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
      - description: The Catalog ID of the Catalog which contains the Recommender
        in: path
        name: catalog_id
        required: true
        schema:
          pattern: ^\d+$
          type: string
      - description: The Recommender ID of the Recommender you want to get output from
        in: path
        name: recommender_id
        required: true
        schema:
          pattern: ^\d+$
          type: string
      responses:
        '200':
          description: Return the CSV with correct headers to force download
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid request body supplied
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid credentials
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: You do not have access to the specified Project
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download a CSV with all computed recommendations output data
      tags:
      - Recommendations
      security:
      - apiKey: []
      - OAuth2:
        - read
        - write
    servers:
    - url: https://api.optimizely.com/v2
  /recommendations/catalogs/{catalog_id}/stats/{date}:
    get:
      description: Download a CSV with summary stats data
      operationId: get_recs_stats_csv
      parameters:
      - description: A string in JSON format that includes all the fields to create a Custom Event
        in: path
        name: date
        required: true
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
      - description: The Catalog ID of the Catalog you want to download stats for
        in: path
        name: catalog_id
        required: true
        schema:
          pattern: ^\d+$
          type: string
      responses:
        '200':
          description: Return the CSV with correct headers to force download
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid request body supplied
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid credentials
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: You do not have access to the specified Project
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download a CSV with summary stats data
      tags:
      - Recommendations
      security:
      - apiKey: []
      - OAuth2:
        - read
        - write
    servers:
    - url: https://api.optimizely.com/v2
components:
  schemas:
    Recommendation:
      type: object
      properties:
        product_id:
          type: string
          example: 1234BLK
        name:
          type: string
          example: Basics - Black
        brand:
          type: string
          example: Jungle James Basics
        sku:
          type: string
          example: 1234BLK
        upc:
          type: string
          example: '042100005264'
        image_url:
          type: string
          example: https://http.cat/404
        price:
          type: number
          example: 25.99
          default: 0
        parent_product_id:
          type: string
          example: '1234'
        recommendation_type:
          type: string
          example: contextual
      example: '[ { "product_id": "1234BLK", "name": "Basics - Black", "brand": "Jungle James Basics", "sku": "1234BLK", "upc": "042100005264", "image_url": "https://http.cat/404", "price": 25.99, "parent_product_id": "1234", "recommendation_type": "contextual" }, { "product_id": "1234BLU", "name": "Basics - Blue", "brand": "Jungle James Basics", "sku": "1234BLU", "upc": "042100005265", "image_url": "https://http.cat/404", "price": 25.99, "parent_product_id": "1234", "recommendation_type": "contextual" } ]'
    Message:
      type: object
      additionalProperties: false
      required:
      - message
      description: Generic message response object returned by the API.
      properties:
        message:
          type: string
          description: The message content.
          example: User updated successfully.
    RecommendationFlag:
      type: object
      additionalProperties: false
      required:
      - pending
      description: Flag indicating the status of a recommendation.
      properties:
        pending:
          type: boolean
          description: True if the recommendation is still pending, false if it has been processed.
    Error:
      properties:
        code:
          type: string
        message:
          type: string
        messages:
          type: object
        uuid:
          format: uuid
          type: string
      type: object
  parameters:
    recommendationGUID:
      name: id
      in: path
      required: true
      description: Unique GUID of the recommendation.
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    x-api-key:
      type: apiKey
      name: x-api-key
      in: header
    key:
      type: apiKey
      in: query
      name: key
      description: API key required for authentication. Must be provided as a query parameter, for example, `?key=YOUR_API_KEY`.
    OAuth2:
      description: Write applications that authenticate with the REST API via OAuth 2.0. Or, to authenticate using a personal token, see https://docs.developers.optimizely.com/web/docs/personal-token
      flows:
        authorizationCode:
          authorizationUrl: https://app.optimizely.com/oauth2/authorize
          scopes:
            all: Full access to your account
          tokenUrl: https://app.optimizely.com/oauth2/token
      type: oauth2
    apiKey:
      scheme: bearer
      type: http
x-refined-from:
- optimizely-data-platform-recommendations-openapi.json
- optimizely-recommendations-public-api-spec-openapi.yaml
- optimizely-web-experimentation-optimizely-api-openapi.json