Amazon Personalize Personalize Solution Version API

openapi: 3.2.0
info:
  title: Amazon Personalize Solution Version API
  version: '2018-05-22'
  description: Generated from AWS's published Smithy model for Amazon Personalize. 3 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://personalize.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Solution Version
paths:
  /#CreateSolutionVersion:
    post:
      operationId: CreateSolutionVersion
      summary: Create Solution Version
      description: 'Trains or retrains an active solution in a Custom dataset group. A solution is created using the CreateSolution operation and must be in the ACTIVE state before calling CreateSolutionVersion. A new version of the solution is created every time you call this operation. Status A solution version can be in one of the following states: CREATE PENDING CREATE IN_PROGRESS ACTIVE CREATE FAILED CREATE STOPPING CREATE STOPPED To get the status of the version, call DescribeSolutionVersion. Wait until the status shows as ACTIVE before calling CreateCampaign. If the status shows as CREATE FAILED, the response includes a failureReason key, which describes why the job failed. Related APIs ListSolutionVersions DescribeSolutionVersion ListSolutions CreateSolution DescribeSolution DeleteSolution'
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateSolutionVersionResponse'
        '400':
          description: InvalidInputException; TooManyTagsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '409':
          description: LimitExceededException; ResourceInUseException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '403':
          description: ResourceAlreadyExistsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceAlreadyExistsException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonPersonalize.CreateSolutionVersion
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateSolutionVersionRequest'
      tags:
      - Solution Version
  /#DescribeSolutionVersion:
    post:
      operationId: DescribeSolutionVersion
      summary: Describe Solution Version
      description: Describes a specific version of a solution. For more information on solutions, see CreateSolution
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeSolutionVersionResponse'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonPersonalize.DescribeSolutionVersion
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeSolutionVersionRequest'
      tags:
      - Solution Version
  /#ListSolutionVersions:
    post:
      operationId: ListSolutionVersions
      summary: List Solution Versions
      description: Returns a list of solution versions for the given solution. When a solution is not specified, all the solution versions associated with the account are listed. The response provides the properties for each solution version, including the Amazon Resource Name (ARN).
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListSolutionVersionsResponse'
        '400':
          description: InvalidInputException; InvalidNextTokenException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonPersonalize.ListSolutionVersions
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListSolutionVersionsRequest'
      tags:
      - Solution Version
components:
  schemas:
    EventsConfig:
      type: object
      properties:
        eventParametersList:
          type: array
          items:
            $ref: '#/components/schemas/EventParameters'
          description: A list of event parameters, which includes event types and their event value thresholds and weights.
    IntegerHyperParameterRange:
      type: object
      properties:
        name:
          type: string
          description: The name of the hyperparameter.
        minValue:
          type: integer
          description: The minimum allowable value for the hyperparameter.
        maxValue:
          type: integer
          description: The maximum allowable value for the hyperparameter.
    SolutionVersionSummary:
      type: object
      properties:
        solutionVersionArn:
          type: string
          description: The Amazon Resource Name (ARN) of the solution version.
        status:
          type: string
          description: 'The status of the solution version. A solution version can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED'
        trainingMode:
          type: string
          enum:
          - FULL
          - UPDATE
          - AUTOTRAIN
          description: The scope of training to be performed when creating the solution version. A FULL training considers all of the data in your dataset group. An UPDATE processes only the data that has changed since the latest training. Only solution versions created with the User-Personalization recipe can use UPDATE.
        trainingType:
          type: string
          enum:
          - AUTOMATIC
          - MANUAL
          description: Whether the solution version was created automatically or manually.
        creationDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix time) that this version of a solution was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix time) that the solution version was last updated.
        failureReason:
          type: string
          description: If a solution version fails, the reason behind the failure.
    HPOConfig:
      type: object
      properties:
        hpoObjective:
          $ref: '#/components/schemas/HPOObjective'
        hpoResourceConfig:
          $ref: '#/components/schemas/HPOResourceConfig'
        algorithmHyperParameterRanges:
          $ref: '#/components/schemas/HyperParameterRanges'
    CreateSolutionVersionRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the solution version.
        solutionArn:
          type: string
          description: The Amazon Resource Name (ARN) of the solution containing the training configuration information.
        trainingMode:
          type: string
          enum:
          - FULL
          - UPDATE
          - AUTOTRAIN
          description: The scope of training to be performed when creating the solution version. The default is FULL. This creates a completely new model based on the entirety of the training data from the datasets in your dataset group. If you use User-Personalization, you can specify a training mode of UPDATE. This updates the model to consider new items for recommendations. It is not a full retraining. You should still complete a full retraining weekly. If you specify UPDATE, Amazon Personalize will stop automatic updates for the solution version. To resume updates, create a new solution with training mode set to
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: A list of tags to apply to the solution version.
      required:
      - solutionArn
    TunedHPOParams:
      type: object
      properties:
        algorithmHyperParameters:
          type: object
          additionalProperties:
            type: string
          description: A list of the hyperparameter values of the best performing model.
    SolutionVersion:
      type: object
      properties:
        name:
          type: string
          description: The name of the solution version.
        solutionVersionArn:
          type: string
          description: The ARN of the solution version.
        solutionArn:
          type: string
          description: The ARN of the solution.
        performHPO:
          type: boolean
          description: Whether to perform hyperparameter optimization (HPO) on the chosen recipe. The default is false.
        performAutoML:
          type: boolean
          description: When true, Amazon Personalize searches for the most optimal recipe according to the solution configuration. When false (the default), Amazon Personalize uses recipeArn.
        performIncrementalUpdate:
          type: boolean
          description: Whether the solution version should perform an incremental update. When set to true, the training will process only the data that has changed since the latest training, similar to when trainingMode is set to UPDATE. This can only be used with solution versions that use the User-Personalization recipe.
        recipeArn:
          type: string
          description: The ARN of the recipe used in the solution.
        eventType:
          type: string
          description: The event type (for example, 'click' or 'like') that is used for training the model.
        datasetGroupArn:
          type: string
          description: The Amazon Resource Name (ARN) of the dataset group providing the training data.
        solutionConfig:
          $ref: '#/components/schemas/SolutionConfig'
        trainingHours:
          type: number
          description: The time used to train the model. You are billed for the time it takes to train a model. This field is visible only after Amazon Personalize successfully trains a model.
        trainingMode:
          type: string
          enum:
          - FULL
          - UPDATE
          - AUTOTRAIN
          description: The scope of training to be performed when creating the solution version. A FULL training considers all of the data in your dataset group. An UPDATE processes only the data that has changed since the latest training. Only solution versions created with the User-Personalization recipe can use UPDATE.
        tunedHPOParams:
          $ref: '#/components/schemas/TunedHPOParams'
        status:
          type: string
          description: 'The status of the solution version. A solution version can be in one of the following states: CREATE PENDING CREATE IN_PROGRESS ACTIVE CREATE FAILED CREATE STOPPING CREATE STOPPED'
        failureReason:
          type: string
          description: If training a solution version fails, the reason for the failure.
        creationDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix time) that this version of the solution was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix time) that the solution was last updated.
        trainingType:
          type: string
          enum:
          - AUTOMATIC
          - MANUAL
          description: Whether the solution version was created automatically or manually.
    TrainingDataConfig:
      type: object
      properties:
        excludedDatasetColumns:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.
        includedDatasetColumns:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: A map that specifies which columns to include from each dataset during training. The map can contain up to 3 entries, where each key is a dataset name (maximum length of 256 characters, must contain only letters and underscores) and each value is an array of up to 50 column names. Column names can be up to 150 characters long, must start with a letter or underscore, and can contain only letters, numbers, and underscores.
    OptimizationObjective:
      type: object
      properties:
        itemAttribute:
          type: string
          description: The numerical metadata column in an Items dataset related to the optimization objective. For example, VIDEO_LENGTH (to maximize streaming minutes), or PRICE (to maximize revenue).
        objectiveSensitivity:
          type: string
          enum:
          - LOW
          - MEDIUM
          - HIGH
          - 'OFF'
          description: Specifies how Amazon Personalize balances the importance of your optimization objective versus relevance.
    ResourceAlreadyExistsException:
      type: object
      properties:
        message:
          type: string
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
    EventParameters:
      type: object
      properties:
        eventType:
          type: string
          description: The name of the event type to be considered for solution creation.
        eventValueThreshold:
          type: number
          description: The threshold of the event type. Only events with a value greater or equal to this threshold will be considered for solution creation.
        weight:
          type: number
          description: The weight of the event type. A higher weight means higher importance of the event type for the created solution.
    HPOResourceConfig:
      type: object
      properties:
        maxNumberOfTrainingJobs:
          type: string
          description: The maximum number of training jobs when you create a solution version. The maximum value for maxNumberOfTrainingJobs is 40.
        maxParallelTrainingJobs:
          type: string
          description: The maximum number of parallel training jobs when you create a solution version. The maximum value for maxParallelTrainingJobs is 10.
    ContinuousHyperParameterRange:
      type: object
      properties:
        name:
          type: string
          description: The name of the hyperparameter.
        minValue:
          type: number
          description: The minimum allowable value for the hyperparameter.
        maxValue:
          type: number
          description: The maximum allowable value for the hyperparameter.
    DescribeSolutionVersionResponse:
      type: object
      properties:
        solutionVersion:
          $ref: '#/components/schemas/SolutionVersion'
    SolutionConfig:
      type: object
      properties:
        eventValueThreshold:
          type: string
          description: Only events with a value greater than or equal to this threshold are used for training a model.
        hpoConfig:
          $ref: '#/components/schemas/HPOConfig'
        algorithmHyperParameters:
          type: object
          additionalProperties:
            type: string
          description: Lists the algorithm hyperparameters and their values.
        featureTransformationParameters:
          type: object
          additionalProperties:
            type: string
          description: Lists the feature transformation parameters.
        autoMLConfig:
          $ref: '#/components/schemas/AutoMLConfig'
        eventsConfig:
          $ref: '#/components/schemas/EventsConfig'
        optimizationObjective:
          $ref: '#/components/schemas/OptimizationObjective'
        trainingDataConfig:
          $ref: '#/components/schemas/TrainingDataConfig'
        autoTrainingConfig:
          $ref: '#/components/schemas/AutoTrainingConfig'
    HPOObjective:
      type: object
      properties:
        type:
          type: string
          description: The type of the metric. Valid values are Maximize and Minimize.
        metricName:
          type: string
          description: The name of the metric.
        metricRegex:
          type: string
          description: A regular expression for finding the metric in the training job logs.
    LimitExceededException:
      type: object
      properties:
        message:
          type: string
    Tag:
      type: object
      properties:
        tagKey:
          type: string
          description: One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.
        tagValue:
          type: string
          description: The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).
      required:
      - tagKey
      - tagValue
    ListSolutionVersionsRequest:
      type: object
      properties:
        solutionArn:
          type: string
          description: The Amazon Resource Name (ARN) of the solution.
        nextToken:
          type: string
          description: A token returned from the previous call to ListSolutionVersions for getting the next set of solution versions (if they exist).
        maxResults:
          type: integer
          description: The maximum number of solution versions to return.
    InvalidInputException:
      type: object
      properties:
        message:
          type: string
    CreateSolutionVersionResponse:
      type: object
      properties:
        solutionVersionArn:
          type: string
          description: The ARN of the new solution version.
    DescribeSolutionVersionRequest:
      type: object
      properties:
        solutionVersionArn:
          type: string
          description: The Amazon Resource Name (ARN) of the solution version.
      required:
      - solutionVersionArn
    AutoTrainingConfig:
      type: object
      properties:
        schedulingExpression:
          type: string
          description: Specifies how often to automatically train new solution versions. Specify a rate expression in rate(value unit) format. For value, specify a number between 1 and 30. For unit, specify day or days. For example, to automatically create a new solution version every 5 days, specify rate(5 days). The default is every 7 days. For more information about auto training, see Creating and configuring a solution.
    AutoMLConfig:
      type: object
      properties:
        metricName:
          type: string
          description: The metric to optimize.
        recipeList:
          type: array
          items:
            type: string
          description: The list of candidate recipes.
    HyperParameterRanges:
      type: object
      properties:
        integerHyperParameterRanges:
          type: array
          items:
            $ref: '#/components/schemas/IntegerHyperParameterRange'
          description: The integer-valued hyperparameters and their ranges.
        continuousHyperParameterRanges:
          type: array
          items:
            $ref: '#/components/schemas/ContinuousHyperParameterRange'
          description: The continuous hyperparameters and their ranges.
        categoricalHyperParameterRanges:
          type: array
          items:
            $ref: '#/components/schemas/CategoricalHyperParameterRange'
          description: The categorical hyperparameters and their ranges.
    CategoricalHyperParameterRange:
      type: object
      properties:
        name:
          type: string
          description: The name of the hyperparameter.
        values:
          type: array
          items:
            type: string
          description: A list of the categories for the hyperparameter.
    ListSolutionVersionsResponse:
      type: object
      properties:
        solutionVersions:
          type: array
          items:
            $ref: '#/components/schemas/SolutionVersionSummary'
          description: A list of solution versions describing the version properties.
        nextToken:
          type: string
          description: A token for getting the next set of solution versions (if they exist).
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: personalize
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/personalize/service/2018-05-22/personalize-2018-05-22.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)