swagger: '2.0'
info:
  version: v1.0
  title: Microsoft Azure Personalizer Client
  description: >-
    Personalizer Service is an Azure Cognitive Service that makes it easy to
    target content and experiences without complex pre-analysis or cleanup of
    past data. Given a context and featurized content, the Personalizer Service
    returns your content in a ranked list. As rewards are sent in response to
    the ranked list, the reinforcement learning algorithm will improve the model
    and improve performance of future rank calls.
basePath: /personalizer/v1.0
paths:
  /events/{eventId}/reward:
    post:
      tags:
        - Events
      summary: >-
        Microsoft Azure Report Reward To Allocate To The Top Ranked Action For The Specified Event
      operationId: microsoftAzureEventsReward
      consumes:
        - application/json
      produces: []
      parameters:
        - name: eventId
          in: path
          description: The event id this reward applies to.
          required: true
          type: string
          maxLength: 256
        - name: reward
          in: body
          description: The reward should be a floating point number.
          required: true
          schema:
            $ref: '#/definitions/RewardRequest'
      responses:
        '204':
          description: Success
        default:
          description: Invalid reward request.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Successful Events_Reward request:
          $ref: ./examples/Events_Reward.json
      description: Needs a more full description created.
  /events/{eventId}/activate:
    post:
      tags:
        - Events
      summary: >-
        Microsoft Azure Report That The Specified Event Was Actually Displayed To The User And A Reward Should Be Expected For It
      operationId: microsoftAzureEventsActivate
      consumes: []
      produces: []
      parameters:
        - name: eventId
          in: path
          description: The event ID this activation applies to.
          required: true
          type: string
          maxLength: 256
      responses:
        '204':
          description: Success
        default:
          description: Invalid reward request.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Successful Events_Activate request:
          $ref: ./examples/Events_Activate.json
      description: Needs a more full description created.
  /rank:
    post:
      tags:
        - Rank
      summary: 'Microsoft Azure A Personalizer Rank Request'
      operationId: microsoftAzureRank
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: rankRequest
          in: body
          description: A Personalizer request.
          required: true
          schema:
            $ref: '#/definitions/RankRequest'
      responses:
        '201':
          description: Success
          schema:
            $ref: '#/definitions/RankResponse'
        default:
          description: Invalid rank request.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Successful Rank request:
          $ref: ./examples/Rank.json
      description: Needs a more full description created.
definitions:
  ErrorResponse:
    description: Used to return an error to the client
    required:
      - error
    type: object
    properties:
      error:
        $ref: '#/definitions/PersonalizerError'
        description: The error object.
  PersonalizerError:
    description: The error object.
    required:
      - code
      - message
    type: object
    properties:
      code:
        description: High level error code.
        enum:
          - BadRequest
          - ResourceNotFound
          - InternalServerError
        type: string
        x-ms-enum:
          name: ErrorCode
          modelAsString: true
          values:
            - value: BadRequest
              description: Request could not be understood by the server.
            - value: ResourceNotFound
              description: Requested resource does not exist on the server.
            - value: InternalServerError
              description: A generic error has occurred on the server.
      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'
        description: Finer error details.
  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'
        description: The error object.
  RewardRequest:
    description: Reward given to a rank response.
    required:
      - value
    type: object
    properties:
      value:
        format: float
        description: >-
          Reward to be assigned to an action. Value should be between -1 and 1
          inclusive.
        type: number
  RankRequest:
    description: Request a set of actions to be ranked by the Personalizer service.
    required:
      - actions
    type: object
    properties:
      contextFeatures:
        description: "Features of the context used for Personalizer as a\r\ndictionary of dictionaries. This depends on the application, and\r\ntypically includes features about the current user, their\r\ndevice, profile information, data about time and date, etc."
        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."
        type: array
        items:
          $ref: '#/definitions/RankableAction'
      excludedActions:
        description: The set of action ids to exclude from ranking.
        type: array
        items:
          type: string
      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 the user will see the rank results, 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\r\nrank results, because the page is rendering later, or the Rank results may be\r\noverridden by code further downstream."
        default: false
        type: boolean
  RankableAction:
    description: An action with it's 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
  RankResponse:
    description: A resulting ordered list of actions that result from a rank request.
    type: object
    properties:
      ranking:
        description: The calculated ranking for the current request.
        type: array
        items:
          $ref: '#/definitions/RankedAction'
        readOnly: true
      eventId:
        description: The eventId for the round trip from request to response.
        maxLength: 256
        type: string
        readOnly: true
      rewardActionId:
        description: "The action chosen by the Personalizer service. This is the action for which to report the reward. This might not be the \r\nfirst found in 'ranking' if an action in the request in first position was part of the excluded ids."
        maxLength: 256
        type: string
        readOnly: true
  RankedAction:
    description: A ranked action with its resulting probability.
    type: object
    properties:
      id:
        description: Id of the action
        maxLength: 256
        type: string
        readOnly: true
      probability:
        format: float
        description: Probability of the action
        maximum: 1
        minimum: 0
        type: number
        readOnly: true
parameters:
  Endpoint:
    name: Endpoint
    in: path
    description: Supported Cognitive Services endpoint.
    required: true
    type: string
    x-ms-parameter-location: client
    x-ms-skip-url-encoding: true
    maxLength: 1024
securityDefinitions:
  apim_key:
    name: Ocp-Apim-Subscription-Key
    in: header
    type: apiKey
security:
  - apim_key: []
tags:
  - name: Events
    description: Manages event operations.
  - name: Rank
    description: Manages ranking operations.
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}'
  useSchemePrefix: false
  parameters:
    - $ref: '#/parameters/Endpoint'