Amazon Bedrock Custom Models API

openapi: 3.1.0
info:
  title: Amazon Bedrock Custom Models API
  version: '2023-04-20'
  description: Generated from AWS's published Smithy model for Amazon Bedrock. 4 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://bedrock.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /custom-models/create-custom-model:
    post:
      operationId: CreateCustomModel
      summary: Create Custom Model
      description: 'Creates a new custom model in Amazon Bedrock. After the model is active, you can use it for inference.
        You can provide the model data source in one of the following ways: customModelDataSource — Specify a SageMaker AI
        model package ARN. Amazon Bedrock resolves the model package to retrieve the model artifacts. This is the preferred
        method for new SageMaker AI training outputs. modelSourceConfig — Specify an Amazon S3 URI pointing to the Amazon-managed
        Amazon S3 bucket containing your model artifacts. To use the model for inference, you must purchase Provisioned Throughput
        for it. You can''t use On-demand inference with these custom models. For more information about Provisioned Throughput,
        see Provisioned Throughput. The model appears in ListCustomModels with a customizationType of imported. To track the
        status of the new model, you use the GetCustomModel API operation. The model can be in the following states: Creating
        - Initial state during validation and registration Active - Model is ready for use in inference Failed - Creation
        process encountered an error Related APIs GetCustomModel ListCustomModels DeleteCustomModel'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomModelResponse'
              example:
                modelArn: arn:aws:bedrock:us-east-1:123456789012:custom-model/imported/abcdef123456
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '400':
          description: ConflictException; ServiceQuotaExceededException; TooManyTagsException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomModelRequest'
            example:
              modelName: SampleModel
              modelSourceConfig:
                s3DataSource:
                  s3Uri: s3://my-bucket/folder
              roleArn: arn:aws:iam::123456789012:role/SampleRole
              modelKmsKeyArn: arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab
              modelTags:
              - key: foo
                value: foo
              - key: foo
                value: foo
              clientRequestToken: foo
      tags:
      - Custom Models
  /custom-models/{modelIdentifier}:
    delete:
      operationId: DeleteCustomModel
      summary: Delete Custom Model
      description: Deletes a custom model that you created earlier. For more information, see Custom models in the Amazon
        Bedrock User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomModelResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '400':
          description: ConflictException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCustomModelRequest'
      tags:
      - Custom Models
    get:
      operationId: GetCustomModel
      summary: Get Custom Model
      description: Get the properties associated with a Amazon Bedrock custom model that you have created. For more information,
        see Custom models in the Amazon Bedrock User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomModelResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCustomModelRequest'
      tags:
      - Custom Models
  /custom-models:
    get:
      operationId: ListCustomModels
      summary: List Custom Models
      description: Returns a list of the custom models that you have created with the CreateModelCustomizationJob operation.
        For more information, see Custom models in the Amazon Bedrock User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomModelsResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCustomModelsRequest'
      tags:
      - Custom Models
components:
  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: bedrock
  schemas:
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
    ConflictException:
      type: object
      properties:
        message:
          type: string
    CreateCustomModelRequest:
      type: object
      properties:
        modelName:
          type: string
          description: A unique name for the custom model.
        modelSourceConfig:
          $ref: '#/components/schemas/ModelDataSource'
        customModelDataSource:
          $ref: '#/components/schemas/CustomModelDataSource'
        modelKmsKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the customer managed KMS key to encrypt the custom model. If you
            don't provide a KMS key, Amazon Bedrock uses an Amazon Web Services-managed KMS key to encrypt the model. If you
            provide a customer managed KMS key, your Amazon Bedrock service role must have permissions to use it. For more
            information see Encryption of imported models.
        roleArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM service role that Amazon Bedrock assumes to perform tasks
            on your behalf. This role must have permissions to access the Amazon S3 bucket containing your model artifacts
            and the KMS key (if specified). For more information, see Setting up an IAM service role for importing models
            in the Amazon Bedrock User Guide. This field is required when you use modelSourceConfig with an Amazon S3 data
            source. It is not required when you use customModelDataSource with a model package ARN, because Amazon Bedrock
            uses its own credentials to access the model artifacts.
        modelTags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: A list of key-value pairs to associate with the custom model resource. You can use these tags to organize
            and identify your resources. For more information, see Tagging resources in the Amazon Bedrock User Guide.
        clientRequestToken:
          type: string
          description: A unique, case-sensitive identifier to ensure that the API request completes no more than one time.
            If this token matches a previous request, Amazon Bedrock ignores the request, but does not return an error. For
            more information, see Ensuring idempotency.
      required:
      - modelName
    CreateCustomModelResponse:
      type: object
      properties:
        modelArn:
          type: string
          description: The Amazon Resource Name (ARN) of the new custom model.
      required:
      - modelArn
    CustomModelDataSource:
      type: object
      properties:
        modelPackageArnDataSource:
          $ref: '#/components/schemas/ModelPackageArnDataSource'
      description: Exactly one member is set.
    CustomModelSummary:
      type: object
      properties:
        modelArn:
          type: string
          description: The Amazon Resource Name (ARN) of the custom model.
        modelName:
          type: string
          description: The name of the custom model.
        creationTime:
          type: string
          format: date-time
          description: Creation time of the model.
        baseModelArn:
          type: string
          description: The base model Amazon Resource Name (ARN).
        baseModelName:
          type: string
          description: The base model name.
        customizationType:
          type: string
          enum:
          - FINE_TUNING
          - CONTINUED_PRE_TRAINING
          - DISTILLATION
          - REINFORCEMENT_FINE_TUNING
          - IMPORTED
          description: Specifies whether to carry out continued pre-training of a model or whether to fine-tune it. For more
            information, see Custom models.
        ownerAccountId:
          type: string
          description: The unique identifier of the account that owns the model.
        modelStatus:
          type: string
          enum:
          - Active
          - Creating
          - Failed
          description: 'The current status of the custom model. Possible values include: Creating - The model is being created
            and validated. Active - The model has been successfully created and is ready for use. Failed - The model creation
            process failed.'
      required:
      - modelArn
      - modelName
      - creationTime
      - baseModelArn
      - baseModelName
    CustomizationConfig:
      type: object
      properties:
        distillationConfig:
          $ref: '#/components/schemas/DistillationConfig'
        rftConfig:
          $ref: '#/components/schemas/RFTConfig'
      description: Exactly one member is set.
    DeleteCustomModelRequest:
      type: object
      properties:
        modelIdentifier:
          type: string
          description: Name of the model to delete.
      required:
      - modelIdentifier
    DeleteCustomModelResponse:
      type: object
      properties: {}
    DistillationConfig:
      type: object
      properties:
        teacherModelConfig:
          $ref: '#/components/schemas/TeacherModelConfig'
      required:
      - teacherModelConfig
    GetCustomModelRequest:
      type: object
      properties:
        modelIdentifier:
          type: string
          description: Name or Amazon Resource Name (ARN) of the custom model.
      required:
      - modelIdentifier
    GetCustomModelResponse:
      type: object
      properties:
        modelArn:
          type: string
          description: Amazon Resource Name (ARN) associated with this model.
        modelName:
          type: string
          description: Model name associated with this model.
        jobName:
          type: string
          description: Job name associated with this model.
        jobArn:
          type: string
          description: Job Amazon Resource Name (ARN) associated with this model. For models that you create with the CreateCustomModel
            API operation, this is NULL.
        baseModelArn:
          type: string
          description: Amazon Resource Name (ARN) of the base model.
        customizationType:
          type: string
          enum:
          - FINE_TUNING
          - CONTINUED_PRE_TRAINING
          - DISTILLATION
          - REINFORCEMENT_FINE_TUNING
          - IMPORTED
          description: The type of model customization.
        modelKmsKeyArn:
          type: string
          description: The custom model is encrypted at rest using this key.
        hyperParameters:
          type: object
          additionalProperties:
            type: string
          description: Hyperparameter values associated with this model. For details on the format for different models, see
            Custom model hyperparameters.
        trainingDataConfig:
          $ref: '#/components/schemas/TrainingDataConfig'
        validationDataConfig:
          $ref: '#/components/schemas/ValidationDataConfig'
        outputDataConfig:
          $ref: '#/components/schemas/OutputDataConfig'
        trainingMetrics:
          $ref: '#/components/schemas/TrainingMetrics'
        validationMetrics:
          type: array
          items:
            $ref: '#/components/schemas/ValidatorMetric'
          description: The validation metrics from the job creation.
        creationTime:
          type: string
          format: date-time
          description: Creation time of the model.
        customizationConfig:
          $ref: '#/components/schemas/CustomizationConfig'
        modelStatus:
          type: string
          enum:
          - Active
          - Creating
          - Failed
          description: 'The current status of the custom model. Possible values include: Creating - The model is being created
            and validated. Active - The model has been successfully created and is ready for use. Failed - The model creation
            process failed. Check the failureMessage field for details.'
        failureMessage:
          type: string
          description: A failure message for any issues that occurred when creating the custom model. This is included for
            only a failed CreateCustomModel operation.
      required:
      - modelArn
      - modelName
      - creationTime
    GraderConfig:
      type: object
      properties:
        lambdaGrader:
          $ref: '#/components/schemas/LambdaGraderConfig'
      description: Exactly one member is set.
    InternalServerException:
      type: object
      properties:
        message:
          type: string
    InvocationLogSource:
      type: object
      properties:
        s3Uri:
          type: string
          description: The URI of an invocation log in a bucket.
      description: Exactly one member is set.
    InvocationLogsConfig:
      type: object
      properties:
        usePromptResponse:
          type: boolean
          description: Whether to use the model's response for training, or just the prompt. The default value is False.
        invocationLogSource:
          $ref: '#/components/schemas/InvocationLogSource'
        requestMetadataFilters:
          $ref: '#/components/schemas/RequestMetadataFilters'
      required:
      - invocationLogSource
    LambdaGraderConfig:
      type: object
      properties:
        lambdaArn:
          type: string
          description: ARN of the AWS Lambda function that will evaluate model responses and return reward scores for RFT
            training.
      required:
      - lambdaArn
    ListCustomModelsRequest:
      type: object
      properties:
        creationTimeBefore:
          type: string
          format: date-time
          description: Return custom models created before the specified time.
        creationTimeAfter:
          type: string
          format: date-time
          description: Return custom models created after the specified time.
        nameContains:
          type: string
          description: Return custom models only if the job name contains these characters.
        baseModelArnEquals:
          type: string
          description: Return custom models only if the base model Amazon Resource Name (ARN) matches this parameter.
        foundationModelArnEquals:
          type: string
          description: Return custom models only if the foundation model Amazon Resource Name (ARN) matches this parameter.
        maxResults:
          type: integer
          description: The maximum number of results to return in the response. If the total number of results is greater
            than this value, use the token returned in the response in the nextToken field when making another request to
            return the next batch of results.
        nextToken:
          type: string
          description: If the total number of results is greater than the maxResults value provided in the request, enter
            the token returned in the nextToken field in the response in this field to return the next batch of results.
        sortBy:
          type: string
          enum:
          - CreationTime
          description: The field to sort by in the returned list of models.
        sortOrder:
          type: string
          enum:
          - Ascending
          - Descending
          description: The sort order of the results.
        isOwned:
          type: boolean
          description: Return custom models depending on if the current account owns them (true) or if they were shared with
            the current account (false).
        modelStatus:
          type: string
          enum:
          - Active
          - Creating
          - Failed
          description: 'The status of them model to filter results by. Possible values include: Creating - Include only models
            that are currently being created and validated. Active - Include only models that have been successfully created
            and are ready for use. Failed - Include only models where the creation process failed. If you don''t specify a
            status, the API returns models in all states.'
    ListCustomModelsResponse:
      type: object
      properties:
        nextToken:
          type: string
          description: If the total number of results is greater than the maxResults value provided in the request, use this
            token when making another request in the nextToken field to return the next batch of results.
        modelSummaries:
          type: array
          items:
            $ref: '#/components/schemas/CustomModelSummary'
          description: Model summaries.
    ModelDataSource:
      type: object
      properties:
        s3DataSource:
          $ref: '#/components/schemas/S3DataSource'
      description: Exactly one member is set.
    ModelPackageArnDataSource:
      type: object
      properties:
        modelPackageArn:
          type: string
          description: The Amazon Resource Name (ARN) of the SageMaker AI model package. The ARN must be for a model package
            of restricted type. To use a model package ARN, you must have the sagemaker:DescribeModelPackage and sagemaker:AccessModelPackageData
            permissions on the model package resource.
      required:
      - modelPackageArn
    OutputDataConfig:
      type: object
      properties:
        s3Uri:
          type: string
          description: The S3 URI where the output data is stored.
      required:
      - s3Uri
    RFTConfig:
      type: object
      properties:
        graderConfig:
          $ref: '#/components/schemas/GraderConfig'
        hyperParameters:
          $ref: '#/components/schemas/RFTHyperParameters'
    RFTHyperParameters:
      type: object
      properties:
        epochCount:
          type: integer
          description: Number of training epochs to run during reinforcement fine-tuning. Higher values may improve performance
            but increase training time.
        batchSize:
          type: integer
          description: Number of training samples processed in each batch during reinforcement fine-tuning (RFT) training.
            Larger batches may improve training stability.
        learningRate:
          type: number
          description: Learning rate for the reinforcement fine-tuning. Controls how quickly the model adapts to reward signals.
        maxPromptLength:
          type: integer
          description: Maximum length of input prompts during RFT training, measured in tokens. Longer prompts allow more
            context but increase memory usage and training-time.
        trainingSamplePerPrompt:
          type: integer
          description: Number of response samples generated per prompt during RFT training. More samples provide better reward
            signal estimation.
        inferenceMaxTokens:
          type: integer
          description: Maximum number of tokens the model can generate in response to each prompt during RFT training.
        reasoningEffort:
          type: string
          enum:
          - low
          - medium
          - high
          description: Level of reasoning effort applied during RFT training. Higher values may improve response quality but
            increase training time.
        evalInterval:
          type: integer
          description: Interval between evaluation runs during RFT training, measured in training steps. More frequent evaluation
            provides better monitoring.
    RequestMetadataBaseFilters:
      type: object
      properties:
        equals:
          type: object
          additionalProperties:
            type: string
          description: Include results where the key equals the value.
        notEquals:
          type: object
          additionalProperties:
            type: string
          description: Include results where the key does not equal the value.
    RequestMetadataFilters:
      type: object
      properties:
        equals:
          type: object
          additionalProperties:
            type: string
          description: Include results where the key equals the value.
        notEquals:
          type: object
          additionalProperties:
            type: string
          description: Include results where the key does not equal the value.
        andAll:
          type: array
          items:
            $ref: '#/components/schemas/RequestMetadataBaseFilters'
          description: Include results where all of the based filters match.
        orAll:
          type: array
          items:
            $ref: '#/components/schemas/RequestMetadataBaseFilters'
          description: Include results where any of the base filters match.
      description: Exactly one member is set.
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
    S3DataSource:
      type: object
      properties:
        s3Uri:
          type: string
          description: The URI of the Amazon S3 data source.
      required:
      - s3Uri
    Tag:
      type: object
      properties:
        key:
          type: string
          description: Key for the tag.
        value:
          type: string
          description: Value for the tag.
      required:
      - key
      - value
    TeacherModelConfig:
      type: object
      properties:
        teacherModelIdentifier:
          type: string
          description: The identifier of the teacher model.
        maxResponseLengthForInference:
          type: integer
          description: The maximum number of tokens requested when the customization job invokes the teacher model.
      required:
      - teacherModelIdentifier
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
    TrainingDataConfig:
      type: object
      properties:
        s3Uri:
          type: string
          description: The S3 URI where the training data is stored.
        invocationLogsConfig:
          $ref: '#/components/schemas/InvocationLogsConfig'
    TrainingMetrics:
      type: object
      properties:
        trainingLoss:
          type: number
          description: Loss metric associated with the custom job.
    ValidationDataConfig:
      type: object
      properties:
        validators:
          type: array
          items:
            $ref: '#/components/schemas/Validator'
          description: Information about the validators.
      required:
      - validators
    ValidationException:
      type: object
      properties:
        message:
          type: string
    Validator:
      type: object
      properties:
        s3Uri:
          type: string
          description: The S3 URI where the validation data is stored.
      required:
      - s3Uri
    ValidatorMetric:
      type: object
      properties:
        validationLoss:
          type: number
          description: The validation loss associated with this validator.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/bedrock/service/2023-04-20/bedrock-2023-04-20.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)