Amazon Personalize Personalize Recommender API

openapi: 3.2.0
info:
  title: Amazon Personalize Recommender API
  version: '2018-05-22'
  description: Generated from AWS's published Smithy model for Amazon Personalize. 7 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: Recommender
paths:
  /#CreateRecommender:
    post:
      operationId: CreateRecommender
      summary: Create Recommender
      description: Creates a recommender with the recipe (a Domain dataset group use case) you specify. You create recommenders for a Domain dataset group and specify the recommender's Amazon Resource Name (ARN) when you make a GetRecommendations request. Minimum recommendation requests per second A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary. When you create a recommender, you can configure the recommender's minimum recommendation requests per second. The minimum recommendation requests per second (minRecommendationRequestsPerSecond) specifies the baseline recommendation request throughput provisioned by Amazon Personalize. The default minRecommendationRequestsPerSecond is 1. A recommendation request is a single GetRecommendations operation. Request throughput is measured in requests per second and Amazon Personalize uses your requests per second to derive your requests per hour and the price of your recommender usage. If your requests per second increases beyond minRecommendationRequ
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateRecommenderResponse'
        '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.CreateRecommender
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateRecommenderRequest'
      tags:
      - Recommender
  /#DeleteRecommender:
    post:
      operationId: DeleteRecommender
      summary: Delete Recommender
      description: Deactivates and removes a recommender. A deleted recommender can no longer be specified in a GetRecommendations request.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                type: string
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '409':
          description: ResourceInUseException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceInUseException'
        '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.DeleteRecommender
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteRecommenderRequest'
      tags:
      - Recommender
  /#DescribeRecommender:
    post:
      operationId: DescribeRecommender
      summary: Describe Recommender
      description: 'Describes the given recommender, including its status. A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS When the status is CREATE FAILED, the response includes the failureReason key, which describes why. The modelMetrics key is null when the recommender is being created or deleted. For more information on recommenders, see CreateRecommender.'
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeRecommenderResponse'
        '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.DescribeRecommender
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeRecommenderRequest'
      tags:
      - Recommender
  /#ListRecommenders:
    post:
      operationId: ListRecommenders
      summary: List Recommenders
      description: Returns a list of recommenders in a given Domain dataset group. When a Domain dataset group is not specified, all the recommenders associated with the account are listed. The response provides the properties for each recommender, including the Amazon Resource Name (ARN). For more information on recommenders, see CreateRecommender.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListRecommendersResponse'
        '400':
          description: InvalidInputException; InvalidNextTokenException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonPersonalize.ListRecommenders
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListRecommendersRequest'
      tags:
      - Recommender
  /#StartRecommender:
    post:
      operationId: StartRecommender
      summary: Start Recommender
      description: Starts a recommender that is INACTIVE. Starting a recommender does not create any new models, but resumes billing and automatic retraining for the recommender.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartRecommenderResponse'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '409':
          description: ResourceInUseException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceInUseException'
        '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.StartRecommender
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartRecommenderRequest'
      tags:
      - Recommender
  /#StopRecommender:
    post:
      operationId: StopRecommender
      summary: Stop Recommender
      description: Stops a recommender that is ACTIVE. Stopping a recommender halts billing and automatic retraining for the recommender.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StopRecommenderResponse'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '409':
          description: ResourceInUseException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceInUseException'
        '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.StopRecommender
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StopRecommenderRequest'
      tags:
      - Recommender
  /#UpdateRecommender:
    post:
      operationId: UpdateRecommender
      summary: Update Recommender
      description: Updates the recommender to modify the recommender configuration. If you update the recommender to modify the columns used in training, Amazon Personalize automatically starts a full retraining of the models backing your recommender. While the update completes, you can still get recommendations from the recommender. The recommender uses the previous configuration until the update completes. To track the status of this update, use the latestRecommenderUpdate returned in the DescribeRecommender operation.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/UpdateRecommenderResponse'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '409':
          description: ResourceInUseException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceInUseException'
        '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.UpdateRecommender
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UpdateRecommenderRequest'
      tags:
      - Recommender
components:
  schemas:
    CreateRecommenderRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the recommender.
        datasetGroupArn:
          type: string
          description: The Amazon Resource Name (ARN) of the destination domain dataset group for the recommender.
        recipeArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recipe that the recommender will use. For a recommender, a recipe is a Domain dataset group use case. Only Domain dataset group use cases can be used to create a recommender. For information about use cases see Choosing recommender use cases.
        recommenderConfig:
          $ref: '#/components/schemas/RecommenderConfig'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: A list of tags to apply to the recommender.
      required:
      - name
      - datasetGroupArn
      - recipeArn
    StartRecommenderResponse:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender you started.
    UpdateRecommenderResponse:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The same recommender Amazon Resource Name (ARN) as given in the request.
    ListRecommendersResponse:
      type: object
      properties:
        recommenders:
          type: array
          items:
            $ref: '#/components/schemas/RecommenderSummary'
          description: A list of the recommenders.
        nextToken:
          type: string
          description: A token for getting the next set of recommenders (if they exist).
    DeleteRecommenderRequest:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender to delete.
      required:
      - recommenderArn
    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.
    ResourceAlreadyExistsException:
      type: object
      properties:
        message:
          type: string
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
    StopRecommenderRequest:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender to stop.
      required:
      - recommenderArn
    UpdateRecommenderRequest:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender to modify.
        recommenderConfig:
          $ref: '#/components/schemas/RecommenderConfig'
      required:
      - recommenderArn
      - recommenderConfig
    ListRecommendersRequest:
      type: object
      properties:
        datasetGroupArn:
          type: string
          description: The Amazon Resource Name (ARN) of the Domain dataset group to list the recommenders for. When a Domain dataset group is not specified, all the recommenders associated with the account are listed.
        nextToken:
          type: string
          description: A token returned from the previous call to ListRecommenders for getting the next set of recommenders (if they exist).
        maxResults:
          type: integer
          description: The maximum number of recommenders to return.
    LimitExceededException:
      type: object
      properties:
        message:
          type: string
    Recommender:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender.
        datasetGroupArn:
          type: string
          description: The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender.
        name:
          type: string
          description: The name of the recommender.
        recipeArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for.
        recommenderConfig:
          $ref: '#/components/schemas/RecommenderConfig'
        creationDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix format) that the recommender was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix format) that the recommender was last updated.
        status:
          type: string
          description: 'The status of the recommender. A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS'
        failureReason:
          type: string
          description: If a recommender fails, the reason behind the failure.
        latestRecommenderUpdate:
          $ref: '#/components/schemas/RecommenderUpdateSummary'
        modelMetrics:
          type: object
          additionalProperties:
            type: number
          description: Provides evaluation metrics that help you determine the performance of a recommender. For more information, see Evaluating a recommender.
    StopRecommenderResponse:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender you stopped.
    RecommenderSummary:
      type: object
      properties:
        name:
          type: string
          description: The name of the recommender.
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender.
        datasetGroupArn:
          type: string
          description: The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender.
        recipeArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for.
        recommenderConfig:
          $ref: '#/components/schemas/RecommenderConfig'
        status:
          type: string
          description: 'The status of the recommender. A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS'
        creationDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix format) that the recommender was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix format) that the recommender was last updated.
    DescribeRecommenderRequest:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender to describe.
      required:
      - recommenderArn
    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
    RecommenderConfig:
      type: object
      properties:
        itemExplorationConfig:
          type: object
          additionalProperties:
            type: string
          description: Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff, you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).
        minRecommendationRequestsPerSecond:
          type: integer
          description: Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.
        trainingDataConfig:
          $ref: '#/components/schemas/TrainingDataConfig'
        enableMetadataWithRecommendations:
          type: boolean
          description: Whether metadata with recommendations is enabled for the recommender. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response. For information about enabling metadata for a recommender, see Enabling metadata in recommendations for a recommender. If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
    InvalidInputException:
      type: object
      properties:
        message:
          type: string
    StartRecommenderRequest:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender to start.
      required:
      - recommenderArn
    CreateRecommenderResponse:
      type: object
      properties:
        recommenderArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommender.
    DescribeRecommenderResponse:
      type: object
      properties:
        recommender:
          $ref: '#/components/schemas/Recommender'
    ResourceInUseException:
      type: object
      properties:
        message:
          type: string
    RecommenderUpdateSummary:
      type: object
      properties:
        recommenderConfig:
          $ref: '#/components/schemas/RecommenderConfig'
        creationDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix format) that the recommender update was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: The date and time (in Unix time) that the recommender update was last updated.
        status:
          type: string
          description: 'The status of the recommender update. A recommender update can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED'
        failureReason:
          type: string
          description: If a recommender update fails, the reason behind the failure.
  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)