swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector MultiSlotRank API
  description: Manages multi-slot ranking operations.
schemes:
- https
tags:
- name: MultiSlotRank
  description: Manages multi-slot ranking operations.
paths:
  /multislot/rank:
    post:
      tags:
      - MultiSlotRank
      summary: Microsoft Azure Post Multi Slot Rank
      description: Submit a Personalizer multi-slot rank request. Receives a context, a list of actions, and a list of slots. Returns which of the provided actions should be used in each slot, in each rewardActionId.
      operationId: microsoftAzureMultislotRank
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: A Personalizer multi-slot Rank request.
        required: true
        schema:
          $ref: '#/definitions/MultiSlotRankRequest'
      responses:
        '201':
          description: Success
          schema:
            $ref: '#/definitions/MultiSlotRankResponse'
        default:
          description: Invalid request.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Successful MultiSlot_Rank request:
          $ref: ./examples/MultiSlot_Rank.json
definitions:
  ErrorResponse:
    description: Used to return an error to the client
    required:
    - error
    type: object
    properties:
      error:
        $ref: '#/definitions/PersonalizerError'
  MultiSlotRankRequest:
    required:
    - actions
    - slots
    type: object
    properties:
      contextFeatures:
        description: "Features of the context used for Personalizer as a\r\ndictionary of dictionaries. This is determined by your application, and\r\ntypically includes features about the current user, their\r\ndevice, profile information, aggregated data about time and date, etc.\r\nFeatures should not include personally identifiable information (PII),\r\nunique UserIDs, or precise timestamps."
        type: array
        items:
          type: object
      actions:
        description: "The set of actions the Personalizer service can pick from.\r\nThe set should not contain more than 50 actions.\r\nThe order of the actions does not affect the rank result but the order\r\nshould match the sequence your application would have used to display them.\r\nThe first item in the array will be used as Baseline item in Offline Evaluations."
        type: array
        items:
          $ref: '#/definitions/RankableAction'
      slots:
        description: "The set of slots the Personalizer service should select actions for.\r\nThe set should not contain more than 50 slots."
        type: array
        items:
          $ref: '#/definitions/SlotRequest'
      eventId:
        description: "Optionally pass an eventId that uniquely identifies this Rank event.\r\nIf null, the service generates a unique eventId. The eventId will be used for\r\nassociating this request with its reward, as well as seeding the pseudo-random\r\ngenerator when making a Personalizer call."
        maxLength: 256
        type: string
      deferActivation:
        description: "Send false if it is certain the rewardActionId in rank results will be shown to the user, therefore\r\nPersonalizer will expect a Reward call, otherwise it will assign the default\r\nReward to the event. Send true if it is possible the user will not see the action specified in the rank results,\r\n(e.g. because the page is rendering later, or the Rank results may be overridden by code further downstream).\r\nYou must call the Activate Event API if the event output is shown to users, otherwise Rewards will be ignored."
        default: false
        type: boolean
  InternalError:
    description: An object containing more specific information than the parent object about the error.
    type: object
    properties:
      code:
        description: Detailed error code.
        type: string
      innererror:
        $ref: '#/definitions/InternalError'
  SlotRequest:
    description: A slot with it's associated features and list of excluded actions
    required:
    - baselineAction
    - id
    type: object
    properties:
      id:
        description: Slot ID
        type: string
      features:
        description: List of dictionaries containing slot features.
        type: array
        items:
          type: object
      excludedActions:
        description: List of excluded action Ids.
        type: array
        items:
          type: string
      baselineAction:
        description: "The 'baseline action' ID for the slot.\r\nThe BaselineAction is the Id of the Action your application would use in that slot if Personalizer didn't exist.\r\nBaselineAction must be defined for every slot.\r\nBaselineAction should never be part of ExcludedActions.\r\nEach slot must have a unique BaselineAction which corresponds to an an action from the event's Actions list."
        type: string
  PersonalizerError:
    description: The error object.
    required:
    - code
    - message
    type: object
    properties:
      code:
        description: Error Codes returned by Personalizer
        enum:
        - BadRequest
        - InvalidServiceConfiguration
        - InvalidLearningModeServiceConfiguration
        - InvalidPolicyConfiguration
        - InvalidPolicyContract
        - InvalidEvaluationContract
        - DuplicateCustomPolicyNames
        - NoLogsExistInDateRange
        - LogsSizeExceedAllowedLimit
        - InvalidRewardRequest
        - InvalidEventIdToActivate
        - InvalidRankRequest
        - InvalidExportLogsRequest
        - InvalidRequest
        - InvalidContainer
        - InvalidModelMetadata
        - ApprenticeModeNeverTurnedOn
        - MissingAppId
        - InvalidRewardWaitTime
        - InvalidMultiSlotApiAccess
        - ModelFileAccessDenied
        - ProblemTypeIncompatibleWithAutoOptimization
        - ResourceNotFound
        - FrontEndNotFound
        - EvaluationNotFound
        - LearningSettingsNotFound
        - EvaluationModelNotFound
        - LogsPropertiesNotFound
        - ModelRankingError
        - InternalServerError
        - RankNullResponse
        - UpdateConfigurationFailed
        - ModelResetFailed
        - ModelPublishFailed
        - ModelMetadataUpdateFailed
        - OperationNotAllowed
        type: string
        x-ms-enum:
          name: PersonalizerErrorCode
          modelAsString: true
          values:
          - value: BadRequest
            description: Request could not be understood by the server.
          - value: InvalidServiceConfiguration
            description: Invalid service configuration.
          - value: InvalidLearningModeServiceConfiguration
            description: Updating defaultReward, rewardWaitTime and rewardAggregation when changing learning mode from Online to Apprentice mode and vice versa is not allowed. Make the mode change and then change the additional settings with an additional API call.
          - value: InvalidPolicyConfiguration
            description: Invalid policy configuration.
          - value: InvalidPolicyContract
            description: Invalid policy contract.
          - value: InvalidEvaluationContract
            description: Invalid evaluation contract.
          - value: DuplicateCustomPolicyNames
            description: Custom policy names should be unique.
          - value: NoLogsExistInDateRange
            description: No logs exist in date range.
          - value: LogsSizeExceedAllowedLimit
            description: Total size of logs exceed allowed limit.
          - value: InvalidRewardRequest
            description: Invalid reward request.
          - value: InvalidEventIdToActivate
            description: Invalid activate event request.
          - value: InvalidRankRequest
            description: Invalid request.
          - value: InvalidExportLogsRequest
            description: Invalid request.
          - value: InvalidRequest
            description: Invalid request.
          - value: InvalidContainer
            description: SAS Uri must be the Uri to a container that has write permissions.
          - value: InvalidModelMetadata
            description: Invalid model metadata.
          - value: ApprenticeModeNeverTurnedOn
            description: Apprentice mode never turned on.
          - value: MissingAppId
            description: AppId is missing in the header.
          - value: InvalidRewardWaitTime
            description: Reward wait time should be between 5 seconds and 2 days
          - value: InvalidMultiSlotApiAccess
            description: Multi-slot feature is currently disabled. Please follow multi-slot Personalizer documentation to update your loop settings to enable multi-slot functionality.
          - value: ModelFileAccessDenied
            description: Key vault Key used for customer managed key cannot be accessed.
          - value: ProblemTypeIncompatibleWithAutoOptimization
            description: Auto-optimization is not compatible with multi-slot personalization.
          - value: ResourceNotFound
            description: Requested resource does not exist on the server.
          - value: FrontEndNotFound
            description: Front end not found.
          - value: EvaluationNotFound
            description: Offline Evaluation not found.
          - value: LearningSettingsNotFound
            description: Learning Settings not found in evaluation.
          - value: EvaluationModelNotFound
            description: Model not found in evaluation.
          - value: LogsPropertiesNotFound
            description: Log properties not found.
          - value: ModelRankingError
            description: Error while ranking actions using model. Please verify the learning settings are valid.
          - value: InternalServerError
            description: A generic error has occurred on the server.
          - value: RankNullResponse
            description: Rank call returned null response.
          - value: UpdateConfigurationFailed
            description: Failed to update configuration.
          - value: ModelResetFailed
            description: Model reset failed.
          - value: ModelPublishFailed
            description: Model publish failed.
          - value: ModelMetadataUpdateFailed
            description: Model metadata update failed.
          - value: OperationNotAllowed
            description: This operation is not allowed at this time.
      message:
        description: A message explaining the error reported by the service.
        type: string
      target:
        description: Error source element.
        type: string
      details:
        description: An array of details about specific errors that led to this reported error.
        type: array
        items:
          $ref: '#/definitions/PersonalizerError'
      innerError:
        $ref: '#/definitions/InternalError'
  SlotResponse:
    required:
    - id
    type: object
    properties:
      id:
        description: Id is the slot ID.
        maxLength: 256
        type: string
      rewardActionId:
        description: RewardActionID is the action ID recommended by Personalizer.
        maxLength: 256
        type: string
        readOnly: true
  MultiSlotRankResponse:
    type: object
    properties:
      slots:
        description: Each slot has a corresponding rewardActionID which is the action ID recommended by Personalizer.
        type: array
        items:
          $ref: '#/definitions/SlotResponse'
        readOnly: true
      eventId:
        description: The eventId for the round trip from request to response.
        maxLength: 256
        type: string
        readOnly: true
  RankableAction:
    description: An action with its associated features used for ranking.
    required:
    - id
    - features
    type: object
    properties:
      id:
        description: Id of the action.
        maxLength: 256
        type: string
      features:
        description: List of dictionaries containing features.
        type: array
        items:
          type: object
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'