Amazon Bedrock Bedrock Prompts API

openapi: 3.1.0
info:
  title: Amazon Bedrock Prompts API
  version: '2023-04-20'
  description: Generated from AWS's published Smithy model for Amazon Bedrock. 5 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-agent.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /prompts/:
    post:
      operationId: CreatePrompt
      summary: Create Prompt
      description: Creates a prompt in your prompt library that you can add to a flow. For more information, see Prompt management
        in Amazon Bedrock, Create a prompt using Prompt management and Prompt flows in Amazon Bedrock in the Amazon Bedrock
        User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePromptResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockAgentValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePromptRequest'
      tags:
      - Prompts
    get:
      operationId: ListPrompts
      summary: List Prompts
      description: Returns either information about the working draft (DRAFT version) of each prompt in an account, or information
        about of all versions of a prompt, depending on whether you include the promptIdentifier field or not. For more information,
        see View information about prompts using Prompt management in the Amazon Bedrock User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPromptsResponse'
        '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/BedrockAgentValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListPromptsRequest'
      tags:
      - Prompts
  /prompts/{promptIdentifier}/:
    get:
      operationId: GetPrompt
      summary: Get Prompt
      description: Retrieves information about the working draft (DRAFT version) of a prompt or a version of it, depending
        on whether you include the promptVersion field or not. For more information, see View information about prompts using
        Prompt management and View information about a version of your prompt in the Amazon Bedrock User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPromptResponse'
        '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/BedrockAgentValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetPromptRequest'
      tags:
      - Prompts
    put:
      operationId: UpdatePrompt
      summary: Update Prompt
      description: Modifies a prompt in your prompt library. Include both fields that you want to keep and fields that you
        want to replace. For more information, see Prompt management in Amazon Bedrock and Edit prompts in your prompt library
        in the Amazon Bedrock User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePromptResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          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'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockAgentValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePromptRequest'
      tags:
      - Prompts
    delete:
      operationId: DeletePrompt
      summary: Delete Prompt
      description: Deletes a prompt or a version of it, depending on whether you include the promptVersion field or not. For
        more information, see Delete prompts from the Prompt management tool and Delete a version of a prompt from the Prompt
        management tool in the Amazon Bedrock User Guide.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePromptResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          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'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockAgentValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletePromptRequest'
      tags:
      - Prompts
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
    AnyToolChoice:
      type: object
      properties: {}
    AutoToolChoice:
      type: object
      properties: {}
    BedrockAgentCachePointBlock:
      type: object
      properties:
        type:
          type: string
          enum:
          - default
          description: Indicates that the CachePointBlock is of the default type
      required:
      - type
    BedrockAgentContentBlock:
      type: object
      properties:
        text:
          type: string
          description: The text in the message.
        cachePoint:
          $ref: '#/components/schemas/BedrockAgentCachePointBlock'
      description: Exactly one member is set.
    BedrockAgentMessage:
      type: object
      properties:
        role:
          type: string
          enum:
          - user
          - assistant
          description: The role that the message belongs to.
        content:
          type: array
          items:
            $ref: '#/components/schemas/BedrockAgentContentBlock'
          description: The content in the message.
      required:
      - role
      - content
    BedrockAgentSystemContentBlock:
      type: object
      properties:
        text:
          type: string
          description: The text in the system prompt.
        cachePoint:
          $ref: '#/components/schemas/BedrockAgentCachePointBlock'
      description: Exactly one member is set.
    BedrockAgentTool:
      type: object
      properties:
        toolSpec:
          $ref: '#/components/schemas/BedrockAgentToolSpecification'
        cachePoint:
          $ref: '#/components/schemas/BedrockAgentCachePointBlock'
      description: Exactly one member is set.
    BedrockAgentToolConfiguration:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/BedrockAgentTool'
          description: An array of tools to pass to a model.
        toolChoice:
          $ref: '#/components/schemas/ToolChoice'
      required:
      - tools
    BedrockAgentToolInputSchema:
      type: object
      properties:
        json:
          type: object
          description: A JSON object defining the input schema for the tool.
      description: Exactly one member is set.
    BedrockAgentToolSpecification:
      type: object
      properties:
        name:
          type: string
          description: The name of the tool.
        description:
          type: string
          description: The description of the tool.
        inputSchema:
          $ref: '#/components/schemas/BedrockAgentToolInputSchema'
        strict:
          type: boolean
          description: Whether the tool schema is strictly enforced.
      required:
      - name
      - inputSchema
    BedrockAgentValidationException:
      type: object
      properties:
        message:
          type: string
        fieldList:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
          description: A list of objects containing fields that caused validation errors and their corresponding validation
            error messages.
    ChatPromptTemplateConfiguration:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/BedrockAgentMessage'
          description: Contains messages in the chat for the prompt.
        system:
          type: array
          items:
            $ref: '#/components/schemas/BedrockAgentSystemContentBlock'
          description: Contains system prompts to provide context to the model or to describe how it should behave.
        inputVariables:
          type: array
          items:
            $ref: '#/components/schemas/PromptInputVariable'
          description: An array of the variables in the prompt template.
        toolConfiguration:
          $ref: '#/components/schemas/BedrockAgentToolConfiguration'
      required:
      - messages
    ConflictException:
      type: object
      properties:
        message:
          type: string
    CreatePromptRequest:
      type: object
      properties:
        name:
          type: string
          description: A name for the prompt.
        description:
          type: string
          description: A description for the prompt.
        customerEncryptionKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the KMS key to encrypt the prompt.
        defaultVariant:
          type: string
          description: The name of the default variant for the prompt. This value must match the name field in the relevant
            PromptVariant object.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariant'
          description: A list of objects, each containing details about a variant of the prompt.
        clientToken:
          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.
        tags:
          type: object
          additionalProperties:
            type: string
          description: Any tags that you want to attach to the prompt. For more information, see Tagging resources in Amazon
            Bedrock.
      required:
      - name
    CreatePromptResponse:
      type: object
      properties:
        name:
          type: string
          description: The name of the prompt.
        description:
          type: string
          description: The description of the prompt.
        customerEncryptionKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the KMS key that you encrypted the prompt with.
        defaultVariant:
          type: string
          description: The name of the default variant for your prompt.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariant'
          description: A list of objects, each containing details about a variant of the prompt.
        id:
          type: string
          description: The unique identifier of the prompt.
        arn:
          type: string
          description: The Amazon Resource Name (ARN) of the prompt.
        version:
          type: string
          description: The version of the prompt. When you create a prompt, the version created is the DRAFT version.
        createdAt:
          type: string
          format: date-time
          description: The time at which the prompt was created.
        updatedAt:
          type: string
          format: date-time
          description: The time at which the prompt was last updated.
      required:
      - name
      - id
      - arn
      - version
      - createdAt
      - updatedAt
    DeletePromptRequest:
      type: object
      properties:
        promptIdentifier:
          type: string
          description: The unique identifier of the prompt.
        promptVersion:
          type: string
          description: The version of the prompt to delete. To delete the prompt, omit this field.
      required:
      - promptIdentifier
    DeletePromptResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the prompt that was deleted.
        version:
          type: string
          description: The version of the prompt that was deleted.
      required:
      - id
    GetPromptRequest:
      type: object
      properties:
        promptIdentifier:
          type: string
          description: The unique identifier of the prompt.
        promptVersion:
          type: string
          description: The version of the prompt about which you want to retrieve information. Omit this field to return information
            about the working draft of the prompt.
        includedData:
          type: string
          enum:
          - ALL_DATA
          - METADATA_ONLY
          description: Controls the scope of data returned. Set to METADATA_ONLY to return only resource metadata. Set to
            ALL_DATA or omit this field to return the full response.
      required:
      - promptIdentifier
    GetPromptResponse:
      type: object
      properties:
        name:
          type: string
          description: The name of the prompt.
        description:
          type: string
          description: The descriptino of the prompt.
        customerEncryptionKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the KMS key that the prompt is encrypted with.
        defaultVariant:
          type: string
          description: The name of the default variant for the prompt. This value must match the name field in the relevant
            PromptVariant object.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariant'
          description: A list of objects, each containing details about a variant of the prompt.
        id:
          type: string
          description: The unique identifier of the prompt.
        arn:
          type: string
          description: The Amazon Resource Name (ARN) of the prompt or the prompt version (if you specified a version in the
            request).
        version:
          type: string
          description: The version of the prompt.
        createdAt:
          type: string
          format: date-time
          description: The time at which the prompt was created.
        updatedAt:
          type: string
          format: date-time
          description: The time at which the prompt was last updated.
      required:
      - name
      - id
      - arn
      - version
      - createdAt
      - updatedAt
    InternalServerException:
      type: object
      properties:
        message:
          type: string
    ListPromptsRequest:
      type: object
      properties:
        promptIdentifier:
          type: string
          description: The unique identifier of the prompt for whose versions you want to return information. Omit this field
            to list information about all prompts in an account.
        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.
    ListPromptsResponse:
      type: object
      properties:
        promptSummaries:
          type: array
          items:
            $ref: '#/components/schemas/PromptSummary'
          description: A list, each member of which contains information about a prompt using Prompt management.
        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.
      required:
      - promptSummaries
    PromptAgentResource:
      type: object
      properties:
        agentIdentifier:
          type: string
          description: The ARN of the agent with which to use the prompt.
      required:
      - agentIdentifier
    PromptGenAiResource:
      type: object
      properties:
        agent:
          $ref: '#/components/schemas/PromptAgentResource'
      description: Exactly one member is set.
    PromptInferenceConfiguration:
      type: object
      properties:
        text:
          $ref: '#/components/schemas/PromptModelInferenceConfiguration'
      description: Exactly one member is set.
    PromptInputVariable:
      type: object
      properties:
        name:
          type: string
          description: The name of the variable.
    PromptMetadataEntry:
      type: object
      properties:
        key:
          type: string
          description: The key of a metadata tag for a prompt variant.
        value:
          type: string
          description: The value of a metadata tag for a prompt variant.
      required:
      - key
      - value
    PromptModelInferenceConfiguration:
      type: object
      properties:
        temperature:
          type: number
          description: Controls the randomness of the response. Choose a lower value for more predictable outputs and a higher
            value for more surprising outputs.
        topP:
          type: number
          description: The percentage of most-likely candidates that the model considers for the next token.
        maxTokens:
          type: integer
          description: The maximum number of tokens to return in the response.
        stopSequences:
          type: array
          items:
            type: string
          description: A list of strings that define sequences after which the model will stop generating.
    PromptSummary:
      type: object
      properties:
        name:
          type: string
          description: The name of the prompt.
        description:
          type: string
          description: The description of the prompt.
        id:
          type: string
          description: The unique identifier of the prompt.
        arn:
          type: string
          description: The Amazon Resource Name (ARN) of the prompt or the prompt version (if you specified a version in the
            request).
        version:
          type: string
          description: The version of the prompt that this summary applies to.
        createdAt:
          type: string
          format: date-time
          description: The time at which the prompt was created.
        updatedAt:
          type: string
          format: date-time
          description: The time at which the prompt was last updated.
      required:
      - name
      - id
      - arn
      - version
      - createdAt
      - updatedAt
    PromptTemplateConfiguration:
      type: object
      properties:
        text:
          $ref: '#/components/schemas/TextPromptTemplateConfiguration'
        chat:
          $ref: '#/components/schemas/ChatPromptTemplateConfiguration'
      description: Exactly one member is set.
    PromptVariant:
      type: object
      properties:
        name:
          type: string
          description: The name of the prompt variant.
        templateType:
          type: string
          enum:
          - TEXT
          - CHAT
          description: The type of prompt template to use.
        templateConfiguration:
          $ref: '#/components/schemas/PromptTemplateConfiguration'
        modelId:
          type: string
          description: The unique identifier of the model or inference profile with which to run inference on the prompt.
        inferenceConfiguration:
          $ref: '#/components/schemas/PromptInferenceConfiguration'
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/PromptMetadataEntry'
          description: An array of objects, each containing a key-value pair that defines a metadata tag and value to attach
            to a prompt variant.
        additionalModelRequestFields:
          type: object
          description: Contains model-specific inference configurations that aren't in the inferenceConfiguration field. To
            see model-specific inference parameters, see Inference request parameters and response fields for foundation models.
        genAiResource:
          $ref: '#/components/schemas/PromptGenAiResource'
      required:
      - name
      - templateType
      - templateConfiguration
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
    SpecificToolChoice:
      type: object
      properties:
        name:
          type: string
          description: The name of the tool that the model must request.
      required:
      - name
    TextPromptTemplateConfiguration:
      type: object
      properties:
        text:
          type: string
          description: The message for the prompt.
        cachePoint:
          $ref: '#/components/schemas/BedrockAgentCachePointBlock'
        inputVariables:
          type: array
          items:
            $ref: '#/components/schemas/PromptInputVariable'
          description: An array of the variables in the prompt template.
      required:
      - text
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
    ToolChoice:
      type: object
      properties:
        auto:
          $ref: '#/components/schemas/AutoToolChoice'
        any:
          $ref: '#/components/schemas/AnyToolChoice'
        tool:
          $ref: '#/components/schemas/SpecificToolChoice'
      description: Exactly one member is set.
    UpdatePromptRequest:
      type: object
      properties:
        name:
          type: string
          description: A name for the prompt.
        description:
          type: string
          description: A description for the prompt.
        customerEncryptionKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the KMS key to encrypt the prompt.
        defaultVariant:
          type: string
          description: The name of the default variant for the prompt. This value must match the name field in the relevant
            PromptVariant object.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariant'
          description: A list of objects, each containing details about a variant of the prompt.
        promptIdentifier:
          type: string
          description: The unique identifier of the prompt.
      required:
      - name
      - promptIdentifier
    UpdatePromptResponse:
      type: object
      properties:
        name:
          type: string
          description: The name of the prompt.
        description:
          type: string
          description: The description of the prompt.
        customerEncryptionKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the KMS key to encrypt the prompt.
        defaultVariant:
          type: string
          description: The name of the default variant for the prompt. This value must match the name field in the relevant
            PromptVariant object.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/PromptVariant'
          description: A list of objects, each containing details about a variant of the prompt.
        id:
          type: string
          description: The unique identifier of the prompt.
        arn:
          type: string
          description: The Amazon Resource Name (ARN) of the prompt.
        version:
          type: string
          description: The version of the prompt. When you update a prompt, the version updated is the DRAFT version.
        createdAt:
          type: string
          format: date-time
          description: The time at which the prompt was created.
        updatedAt:
          type: string
          format: date-time
          description: The time at which the prompt was last updated.
      required:
      - name
      - id
      - arn
      - version
      - createdAt
      - updatedAt
    ValidationExceptionField:
      type: object
      properties:
        name:
          type: string
          description: The name of the field.
        message:
          type: string
          description: A message describing why this field failed validation.
      required:
      - name
      - message
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/bedrock-agent/service/2023-06-05/bedrock-agent-2023-06-05.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)