Microsoft Azure Personalizer Base is a service that uses machine learning algorithms to deliver personalized content recommendations. By analyzing user behavior and preferences, Personalizer Base can generate recommendations that are tailored to each individual's unique needs and interests. This service is particularly useful for companies looking to enhance their customer experience by providing personalized recommendations for products, services, or content.
swagger: '2.0'
info:
version: v1.1-preview.2
title: Microsoft Azure Personalizer Base
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 which content item to show to users in rewardActionId. As rewards
are sent in response to the use of rewardActionId, the reinforcement
learning algorithm will improve the model and improve performance of future
rank calls.
basePath: /personalizer/v1.1-preview.2
schemes:
- https
paths:
/configurations/service:
get:
tags:
- ConfigurationsV1Dot1Preview1
summary: 'Microsoft Azure Get Service Configuration'
description: Get the Personalizer service configuration.
operationId: microsoftAzureServiceconfigurationGet
consumes: []
produces:
- application/json
parameters: []
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ServiceConfiguration'
x-ms-examples:
Successful ServiceConfiguration_Get request:
$ref: ./examples/ServiceConfiguration_Get.json
put:
tags:
- ConfigurationsV1Dot1Preview1
summary: 'Microsoft Azure Update Service Configuration'
description: Update the Personalizer service configuration.
operationId: microsoftAzureServiceconfigurationUpdate
consumes:
- application/json
produces:
- application/json
parameters:
- name: config
in: body
description: The personalizer service configuration.
required: true
schema:
$ref: '#/definitions/ServiceConfiguration'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ServiceConfiguration'
default:
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.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful ServiceConfiguration_Update request:
$ref: ./examples/ServiceConfiguration_Update.json
/configurations/policy:
get:
tags:
- ConfigurationsV1Dot1Preview1
summary: 'Microsoft Azure Get Policy'
description: Get the Learning Settings currently used by the Personalizer service.
operationId: microsoftAzurePolicyGet
consumes: []
produces:
- application/json
parameters: []
responses:
'200':
description: Success
schema:
$ref: '#/definitions/PolicyContract'
x-ms-examples:
Successful Policy_Get request:
$ref: ./examples/Policy_Get.json
put:
tags:
- ConfigurationsV1Dot1Preview1
summary: 'Microsoft Azure Update Policy'
description: >-
Update the Learning Settings that the Personalizer service will use to
train models.
operationId: microsoftAzurePolicyUpdate
consumes:
- application/json
produces:
- application/json
parameters:
- name: policy
in: body
description: The learning settings.
required: true
schema:
$ref: '#/definitions/PolicyContract'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/PolicyContract'
default:
description: Invalid policy configuration.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Policy_Update request:
$ref: ./examples/Policy_Update.json
delete:
tags:
- ConfigurationsV1Dot1Preview1
summary: 'Microsoft Azure Reset Policy'
description: Resets the learning settings of the Personalizer service to default.
operationId: microsoftAzurePolicyReset
consumes: []
produces:
- application/json
parameters: []
responses:
'200':
description: Success
schema:
$ref: '#/definitions/PolicyContract'
x-ms-examples:
Successful Policy_Reset request:
$ref: ./examples/Policy_Reset.json
/evaluations/{evaluationId}:
get:
tags:
- EvaluationsV1Dot1Preview1
summary: 'Microsoft Azure Get Evaluation'
description: Get the Offline Evaluation associated with the Id.
operationId: microsoftAzureEvaluationsGet
consumes: []
produces:
- application/json
parameters:
- name: evaluationId
in: path
description: Id of the Offline Evaluation.
required: true
type: string
maxLength: 256
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Evaluation'
default:
description: Offline Evaluation not found.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Evaluations_Get request:
$ref: ./examples/Evaluations_Get.json
delete:
tags:
- EvaluationsV1Dot1Preview1
summary: 'Microsoft Azure Delete Evaluation'
description: Delete the Offline Evaluation associated with the Id.
operationId: microsoftAzureEvaluationsDelete
consumes: []
produces: []
parameters:
- name: evaluationId
in: path
description: Id of the Offline Evaluation to delete.
required: true
type: string
maxLength: 256
responses:
'204':
description: Success
x-ms-examples:
Successful Evaluations_Delete request:
$ref: ./examples/Evaluations_Delete.json
/evaluations:
get:
tags:
- EvaluationsV1Dot1Preview1
summary: 'Microsoft Azure List Offline Evaluations'
description: List of all Offline Evaluations.
operationId: microsoftAzureEvaluationsList
consumes: []
produces:
- application/json
parameters: []
responses:
'200':
description: Success
schema:
type: array
items:
$ref: '#/definitions/Evaluation'
x-ms-examples:
Successful Evaluations_List request:
$ref: ./examples/Evaluations_List.json
post:
tags:
- EvaluationsV1Dot1Preview1
summary: 'Microsoft Azure Create Offline Evaluation'
description: Submit a new Offline Evaluation job.
operationId: microsoftAzureEvaluationsCreate
consumes:
- application/json
produces:
- application/json
parameters:
- name: evaluation
in: body
description: The Offline Evaluation job definition.
required: true
schema:
$ref: '#/definitions/EvaluationContract'
responses:
'201':
description: Success
schema:
$ref: '#/definitions/Evaluation'
headers:
Location:
description: Location of the Offline Evaluation status and data.
type: string
default:
description: Invalid evaluation contract.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Evaluations_Create request:
$ref: ./examples/Evaluations_Create.json
/events/{eventId}/reward:
post:
tags:
- Events
summary: 'Microsoft Azure Post Reward'
description: >-
Report reward between 0 and 1 that resulted from using the action
specified in rewardActionId, for the specified event.
operationId: microsoftAzureEventsReward
consumes:
- application/json
produces:
- application/json
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, typically between 0
and 1.
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
/events/{eventId}/activate:
post:
tags:
- Events
summary: 'Microsoft Azure Activate Event'
description: >-
Report that the specified event was actually used (e.g. by being
displayed to the user) and a reward should be expected for it.
operationId: microsoftAzureEventsActivate
consumes: []
produces:
- application/json
parameters:
- name: eventId
in: path
description: The event ID to be activated.
required: true
type: string
maxLength: 256
responses:
'204':
description: Success
default:
description: Invalid activate event request.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Events_Activate request:
$ref: ./examples/Events_Activate.json
/configurations/applyFromEvaluation:
post:
tags:
- ConfigurationsV1Dot1Preview1
summary: >-
Microsoft Azure Apply Learning Settings And Model From A Pre Existing Offline Evaluation, Making Them The Current Online Learning Settings And Model And Replacing The Previous Ones
operationId: microsoftAzureServiceconfigurationApplyfromevaluation
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: Reference to the policy within the evaluation.
required: true
schema:
$ref: '#/definitions/PolicyReferenceContract'
responses:
'204':
description: Success
default:
description: Learning Settings not found in evaluation.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful ServiceConfiguration_ApplyFromEvaluation request:
$ref: ./examples/ServiceConfiguration_ApplyFromEvaluation.json
description: Needs a more full description created.
/logs/interactions:
post:
tags:
- LogsV1Dot1Preview2
summary: 'Microsoft Azure Post Interactions'
description: >-
The endpoint is intended to be used from within a SDK for logging
interactions and accepts specific format defined in
https://github.com/VowpalWabbit/reinforcement_learning. This endpoint
should not be used by the customer.
operationId: microsoftAzureLogInteractions
consumes:
- application/octet-stream
produces:
- application/json
parameters:
- in: body
name: body
description: Interactions binary payload.
required: true
schema:
format: binary
type: string
responses:
'204':
description: Success
default:
description: Invalid request.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Log_Interactions request:
$ref: ./examples/Log_Interactions.json
/logs/observations:
post:
tags:
- LogsV1Dot1Preview2
summary: 'Microsoft Azure Post Observations'
description: >-
The endpoint is intended to be used from within a SDK for logging
observations and accepts specific format defined in
https://github.com/VowpalWabbit/reinforcement_learning. This endpoint
should not be used by the customer.
operationId: microsoftAzureLogObservations
consumes:
- application/octet-stream
produces:
- application/json
parameters:
- in: body
name: body
description: Observations binary payload.
required: true
schema:
format: binary
type: string
responses:
'204':
description: Success
default:
description: Invalid request.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Log_Observations request:
$ref: ./examples/Log_Observations.json
/logs:
delete:
tags:
- LogsV1Dot1Preview2
summary: 'Microsoft Azure Deletes Logs'
description: Delete all logs of Rank and Reward calls stored by Personalizer.
operationId: microsoftAzureLogDelete
consumes: []
produces: []
parameters: []
responses:
'204':
description: Success
x-ms-examples:
Successful Log_Delete request:
$ref: ./examples/Log_Delete.json
/logs/properties:
get:
tags:
- LogsV1Dot1Preview2
summary: 'Microsoft Azure Get Log Properties'
description: Get properties of the Personalizer logs.
operationId: microsoftAzureLogGetproperties
consumes: []
produces:
- application/json
parameters: []
responses:
'200':
description: Success
schema:
$ref: '#/definitions/LogsProperties'
default:
description: Log properties not found.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Log_GetProperties request:
$ref: ./examples/Log_GetProperties.json
/model:
get:
tags:
- Model
summary: 'Microsoft Azure Get Model'
description: Get the model file generated by Personalizer service.
operationId: microsoftAzureModelGet
consumes: []
produces:
- application/octet-stream
parameters: []
responses:
'200':
description: Success
schema:
type: file
x-ms-examples:
Successful Model_Get request:
$ref: ./examples/Model_Get.json
delete:
tags:
- Model
summary: 'Microsoft Azure Reset Model'
description: Resets the model file generated by Personalizer service.
operationId: microsoftAzureModelReset
consumes: []
produces:
- application/json
parameters: []
responses:
'204':
description: Success
default:
description: Model reset failed.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Model_Reset request:
$ref: ./examples/Model_Reset.json
/model/properties:
get:
tags:
- Model
summary: 'Microsoft Azure Get Model Properties'
description: Get properties of the model file generated by Personalizer service.
operationId: microsoftAzureModelGetproperties
consumes: []
produces:
- application/json
parameters: []
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ModelProperties'
x-ms-examples:
Successful Model_GetProperties request:
$ref: ./examples/Model_GetProperties.json
/multislot/events/{eventId}/reward:
post:
tags:
- MultiSlotEvents
summary: 'Microsoft Azure Post Multi Slot Rewards'
description: >-
Report reward that resulted from using the action specified in
rewardActionId for the slot.
operationId: microsoftAzureMultisloteventsReward
consumes:
- application/json
produces:
- application/json
parameters:
- in: path
name: eventId
description: The event id this reward applies to.
required: true
type: string
maxLength: 256
- in: body
name: body
description: >-
List of slot id and reward values. The reward should be a floating
point number, typically between 0 and 1.
required: true
schema:
$ref: '#/definitions/MultiSlotRewardRequest'
responses:
'204':
description: Success
default:
description: Invalid reward request.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful MultiSlotEvents_Reward request:
$ref: ./examples/MultiSlotEvents_Reward.json
/multislot/events/{eventId}/activate:
post:
tags:
- MultiSlotEvents
summary: 'Microsoft Azure Activate Multi Slot Event'
description: >-
Report that the specified event was actually used or displayed to the
user and a rewards should be expected for it.
operationId: microsoftAzureMultisloteventsActivate
produces:
- application/json
parameters:
- in: path
name: eventId
description: The event ID this activation applies to.
required: true
type: string
maxLength: 256
responses:
'204':
description: Success
default:
description: Invalid activate event request.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful MultiSlotEvents_Activate request:
$ref: ./examples/MultiSlotEvents_Activate.json
/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
/rank:
post:
tags:
- Rank
summary: 'Microsoft Azure Post Rank'
description: >-
Submit a Personalizer rank request. Receives a context and a list of
actions. Returns which of the provided actions should be used by your
application, in rewardActionId.
operationId: microsoftAzureRank
consumes:
- application/json
produces:
- application/json
parameters:
- name: rankRequest
in: body
description: A Personalizer Rank request.
required: true
schema:
$ref: '#/definitions/RankRequest'
responses:
'201':
description: Success
schema:
$ref: '#/definitions/RankResponse'
default:
description: Invalid request.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful Rank request:
$ref: ./examples/Rank.json
definitions:
ServiceConfiguration:
description: The configuration of the service.
required:
- rewardWaitTime
- defaultReward
- rewardAggregation
- explorationPercentage
- modelExportFrequency
- logRetentionDays
type: object
properties:
rewardWaitTime:
format: duration
description: "The time span waited until a request is marked with the default reward\r\nand should be between 5 seconds and 2 days.\r\nFor example, PT5M (5 mins). For information about the time format,\r\nsee http://en.wikipedia.org/wiki/ISO_8601#Durations"
type: string
defaultReward:
format: float
description: >-
The reward given if a reward is not received within the specified wait
time.
maximum: 1
minimum: -1
type: number
rewardAggregation:
description: >-
The function used to process rewards, if multiple reward scores are
received before rewardWaitTime is over.
maxLength: 256
type: string
explorationPercentage:
format: float
description: The percentage of rank responses that will use exploration.
maximum: 1
minimum: 0
type: number
modelExportFrequency:
format: duration
description: "Personalizer will start using the most updated trained model for online ranks automatically every specified time period.\r\nFor example, PT5M (5 mins). For information about the time format,\r\nsee http://en.wikipedia.org/wiki/ISO_8601#Durations"
type: string
logMirrorEnabled:
description: Flag indicates whether log mirroring is enabled.
type: boolean
logMirrorSasUri:
description: Azure storage account container SAS URI for log mirroring.
type: string
logRetentionDays:
format: int32
description: >-
Number of days historical logs are to be maintained. -1 implies the
logs will never be deleted.
maximum: 2147483647
minimum: -1
type: integer
lastConfigurationEditDate:
format: date-time
description: Last time model training configuration was updated
type: string
learningMode:
description: Learning Modes for Personalizer
enum:
- Online
- Apprentice
- LoggingOnly
type: string
x-ms-enum:
name: LearningMode
modelAsString: true
isAutoOptimizationEnabled:
description: >-
Flag indicating whether Personalizer will automatically optimize
Learning Settings by running Offline Evaluations periodically.
type: boolean
autoOptimizationFrequency:
format: duration
description: "Frequency of automatic optimization. Only relevant if IsAutoOptimizationEnabled is true.\r\nFor example, PT5M (5 mins). For information about the time format,\r\n\\r\\nsee http://en.wikipedia.org/wiki/ISO_8601#Durations"
type: string
autoOptimizationStartDate:
format: date-time
description: >-
Date when the first automatic optimization evaluation must be
performed. Only relevant if IsAutoOptimizationEnabled is true.
type: string
ErrorResponse:
description: Used to return an error to the client
required:
- error
type: object
properties:
error:
$ref: '#/definitions/PersonalizerError'
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'
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'
PolicyContract:
description: Learning settings specifying how to train the model.
required:
- name
- arguments
type: object
properties:
name:
description: Name of the learning settings.
maxLength: 256
type: string
arguments:
description: Arguments of the learning settings.
maxLength: 1024
type: string
Evaluation:
description: A counterfactual evaluation.
type: object
properties:
id:
description: The ID of the evaluation.
maxLength: 256
type: string
readOnly: true
name:
description: The name of the evaluation.
maxLength: 256
type: string
readOnly: true
startTime:
format: date-time
description: The start time of the evaluation.
type: string
readOnly: true
endTime:
format: date-time
description: The end time of the evaluation.
type: string
readOnly: true
jobId:
description: The ID of the job processing the evaluation.
type: string
readOnly: true
status:
description: The status of the job processing the evaluation.
enum:
- completed
- pending
- failed
- notSubmitted
- timeout
- optimalPolicyApplied
- onlinePolicyRetained
type: string
readOnly: true
x-ms-enum:
name: EvaluationJobStatus
modelAsString: true
policyResults:
description: The results of the evaluation.
type: array
items:
$ref: '#/definitions/PolicyResult'
featureImportance:
description: Feature Importance.
type: array
items:
type: array
items:
type: string
evaluationType:
description: Evaluation type (manual or through Automatic Optimization).
enum:
- Manual
- Auto
type: string
x-ms-enum:
name: EvaluationType
modelAsString: true
optimalPolicy:
description: Thr optimal policy.
type: string
creationTime:
description: Creation time.
format: date-time
type: string
PolicyResult:
description: >-
This class contains the Learning Settings information and the resu
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/personalizer-base-openapi-original.yml