Amazon Bedrock Bedrock Recommendations API

The Bedrock Recommendations API from Amazon Bedrock — 2 operation(s) for bedrock recommendations.

GitHub OpenAPI

Operations 4

DELETE /recommendations/{recommendationId} Delete Recommendation #
GET /recommendations/{recommendationId} Get Recommendation #
GET /recommendations List Recommendations #
POST /recommendations Start Recommendation #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/amazon-bedrock:amazon-bedrock-recommendations-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

amazon-bedrock-recommendations-api-openapi.yml Raw ↑
openapi: 3.1.0
info:
  title: Amazon Bedrock Recommendations 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-agentcore.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /recommendations/{recommendationId}:
    delete:
      operationId: DeleteRecommendation
      summary: Delete Recommendation
      description: Deletes a recommendation and its associated results.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRecommendationResponse'
        '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/BedrockAgentcoreValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteRecommendationRequest'
      tags:
      - Recommendations
    get:
      operationId: GetRecommendation
      summary: Get Recommendation
      description: Retrieves detailed information about a recommendation, including its configuration, status, and results.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRecommendationResponse'
        '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/BedrockAgentcoreValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRecommendationRequest'
      tags:
      - Recommendations
  /recommendations:
    get:
      operationId: ListRecommendations
      summary: List Recommendations
      description: Lists all recommendations in the account, with optional filtering by status.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRecommendationsResponse'
        '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/BedrockAgentcoreValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRecommendationsRequest'
      tags:
      - Recommendations
    post:
      operationId: StartRecommendation
      summary: Start Recommendation
      description: Starts a recommendation job that analyzes agent traces and generates optimization suggestions for system
        prompts or tool descriptions to improve agent performance.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartRecommendationResponse'
        '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/BedrockAgentcoreValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartRecommendationRequest'
      tags:
      - Recommendations
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-agentcore
  schemas:
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
    AgentTracesConfig:
      type: object
      properties:
        sessionSpans:
          type: array
          items:
            type: object
          description: Agent traces provided as inline session spans in OpenTelemetry format.
        cloudwatchLogs:
          $ref: '#/components/schemas/CloudWatchLogsTraceConfig'
        batchEvaluation:
          $ref: '#/components/schemas/BatchEvaluationTraceConfig'
        onlineEvaluation:
          $ref: '#/components/schemas/OnlineEvaluationTraceConfig'
      description: Exactly one member is set.
    BatchEvaluationTraceConfig:
      type: object
      properties:
        batchEvaluationArn:
          type: string
          description: The ARN of the completed batch evaluation to use as the trace source.
      required:
      - batchEvaluationArn
    BedrockAgentcoreValidationException:
      type: object
      properties:
        message:
          type: string
        reason:
          type: string
          enum:
          - CannotParse
          - FieldValidationFailed
          - IdempotentParameterMismatchException
          - EventInOtherSession
          - ResourceConflict
        fieldList:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
      required:
      - message
      - reason
    CloudWatchLogsFilter:
      type: object
      properties:
        key:
          type: string
          description: The key or field name to filter on within the agent trace data.
        operator:
          type: string
          enum:
          - Equals
          - NotEquals
          - GreaterThan
          - LessThan
          - GreaterThanOrEqual
          - LessThanOrEqual
          - Contains
          - NotContains
          description: The comparison operator to use for filtering.
        value:
          $ref: '#/components/schemas/FilterValue'
      required:
      - key
      - operator
      - value
    CloudWatchLogsRule:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/CloudWatchLogsFilter'
          description: The list of filters to apply when reading agent traces.
    CloudWatchLogsTraceConfig:
      type: object
      properties:
        logGroupArns:
          type: array
          items:
            type: string
          description: The list of CloudWatch log group ARNs to read agent traces from.
        serviceNames:
          type: array
          items:
            type: string
          description: The list of service names to filter traces within the specified log groups.
        startTime:
          type: string
          description: The start time of the time range to read traces from.
        endTime:
          type: string
          description: The end time of the time range to read traces from.
        rule:
          $ref: '#/components/schemas/CloudWatchLogsRule'
      required:
      - logGroupArns
      - serviceNames
      - startTime
      - endTime
    ConfigurationBundleToolEntry:
      type: object
      properties:
        toolName:
          type: string
          description: The name of the tool.
        toolDescriptionJsonPath:
          type: string
          description: The JSON path within the configuration bundle's components that contains the tool description.
      required:
      - toolName
      - toolDescriptionJsonPath
    ConflictException:
      type: object
      properties:
        message:
          type: string
    DeleteRecommendationRequest:
      type: object
      properties:
        recommendationId:
          type: string
          description: The unique identifier of the recommendation to delete.
      required:
      - recommendationId
    DeleteRecommendationResponse:
      type: object
      properties:
        recommendationId:
          type: string
          description: The unique identifier of the deleted recommendation.
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          - DELETING
          description: The status of the recommendation deletion operation.
      required:
      - recommendationId
      - status
    FilterValue:
      type: object
      properties:
        stringValue:
          type: string
          description: A string value for text-based filtering.
        doubleValue:
          type: number
          description: A numeric value for numerical filtering and comparisons.
        booleanValue:
          type: boolean
          description: A boolean value for true/false filtering conditions.
      description: Exactly one member is set.
    GetRecommendationRequest:
      type: object
      properties:
        recommendationId:
          type: string
          description: The unique identifier of the recommendation to retrieve.
      required:
      - recommendationId
    GetRecommendationResponse:
      type: object
      properties:
        recommendationId:
          type: string
          description: The unique identifier of the recommendation.
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommendation.
        name:
          type: string
          description: The name of the recommendation.
        description:
          type: string
          description: The description of the recommendation.
        type:
          type: string
          enum:
          - SYSTEM_PROMPT_RECOMMENDATION
          - TOOL_DESCRIPTION_RECOMMENDATION
          description: The type of recommendation.
        recommendationConfig:
          $ref: '#/components/schemas/RecommendationConfig'
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          - DELETING
          description: The current status of the recommendation.
        createdAt:
          type: string
          description: The timestamp when the recommendation was created.
        updatedAt:
          type: string
          description: The timestamp when the recommendation was last updated.
        recommendationResult:
          $ref: '#/components/schemas/RecommendationResult'
        kmsKeyArn:
          type: string
          description: The ARN of the KMS key used to encrypt recommendation data.
      required:
      - recommendationId
      - recommendationArn
      - name
      - type
      - recommendationConfig
      - status
      - createdAt
      - updatedAt
    InternalServerException:
      type: object
      properties:
        message:
          type: string
    ListRecommendationsRequest:
      type: object
      properties:
        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.
        statusFilter:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          - DELETING
          description: Optional filter to return only recommendations with the specified status.
    ListRecommendationsResponse:
      type: object
      properties:
        recommendationSummaries:
          type: array
          items:
            $ref: '#/components/schemas/RecommendationSummary'
          description: The list of recommendation summaries.
        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:
      - recommendationSummaries
    OnlineEvaluationTraceConfig:
      type: object
      properties:
        onlineEvaluationConfigArn:
          type: string
          description: The ARN of the online evaluation configuration to reuse sessions from.
        startTime:
          type: string
          description: The start time of the time range. Only sessions evaluated at or after this timestamp are included.
        endTime:
          type: string
          description: The end time of the time range. Only sessions evaluated before this timestamp are included.
      required:
      - onlineEvaluationConfigArn
      - startTime
      - endTime
    RecommendationConfig:
      type: object
      properties:
        systemPromptRecommendationConfig:
          $ref: '#/components/schemas/SystemPromptRecommendationConfig'
        toolDescriptionRecommendationConfig:
          $ref: '#/components/schemas/ToolDescriptionRecommendationConfig'
      description: Exactly one member is set.
    RecommendationEvaluationConfig:
      type: object
      properties:
        evaluators:
          type: array
          items:
            $ref: '#/components/schemas/RecommendationEvaluatorReference'
          description: The list of evaluators to use for assessing recommendation quality.
      required:
      - evaluators
    RecommendationEvaluatorReference:
      type: object
      properties:
        evaluatorArn:
          type: string
          description: The Amazon Resource Name (ARN) of the evaluator.
      required:
      - evaluatorArn
    RecommendationResult:
      type: object
      properties:
        systemPromptRecommendationResult:
          $ref: '#/components/schemas/SystemPromptRecommendationResult'
        toolDescriptionRecommendationResult:
          $ref: '#/components/schemas/ToolDescriptionRecommendationResult'
      description: Exactly one member is set.
    RecommendationResultConfigurationBundle:
      type: object
      properties:
        bundleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the configuration bundle.
        versionId:
          type: string
          description: The version identifier of the configuration bundle containing the recommendation.
      required:
      - bundleArn
      - versionId
    RecommendationSummary:
      type: object
      properties:
        recommendationId:
          type: string
          description: The unique identifier of the recommendation.
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommendation.
        name:
          type: string
          description: The name of the recommendation.
        description:
          type: string
          description: The description of the recommendation.
        type:
          type: string
          enum:
          - SYSTEM_PROMPT_RECOMMENDATION
          - TOOL_DESCRIPTION_RECOMMENDATION
          description: The type of recommendation.
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          - DELETING
          description: The current status of the recommendation.
        createdAt:
          type: string
          description: The timestamp when the recommendation was created.
        updatedAt:
          type: string
          description: The timestamp when the recommendation was last updated.
      required:
      - recommendationId
      - recommendationArn
      - name
      - type
      - status
      - createdAt
      - updatedAt
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
    StartRecommendationRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the recommendation. Must be unique within your account.
        description:
          type: string
          description: The description of the recommendation.
        type:
          type: string
          enum:
          - SYSTEM_PROMPT_RECOMMENDATION
          - TOOL_DESCRIPTION_RECOMMENDATION
          description: The type of recommendation to generate. Valid values are SYSTEM_PROMPT_RECOMMENDATION for system prompt
            optimization or TOOL_DESCRIPTION_RECOMMENDATION for tool description optimization.
        recommendationConfig:
          $ref: '#/components/schemas/RecommendationConfig'
        kmsKeyArn:
          type: string
          description: The ARN of the KMS key used to encrypt recommendation data. If provided, customer data is encrypted
            at rest with the specified key.
        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, the service ignores the request, but does not return an error.
        tags:
          type: object
          additionalProperties:
            type: string
          description: A map of tag keys and values to associate with the recommendation.
      required:
      - name
      - type
      - recommendationConfig
    StartRecommendationResponse:
      type: object
      properties:
        recommendationId:
          type: string
          description: The unique identifier of the created recommendation.
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the created recommendation.
        name:
          type: string
          description: The name of the recommendation.
        description:
          type: string
          description: The description of the recommendation.
        type:
          type: string
          enum:
          - SYSTEM_PROMPT_RECOMMENDATION
          - TOOL_DESCRIPTION_RECOMMENDATION
          description: The type of recommendation.
        recommendationConfig:
          $ref: '#/components/schemas/RecommendationConfig'
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          - DELETING
          description: The status of the recommendation.
        createdAt:
          type: string
          description: The timestamp when the recommendation was created.
        updatedAt:
          type: string
          description: The timestamp when the recommendation was last updated.
      required:
      - recommendationId
      - recommendationArn
      - name
      - type
      - recommendationConfig
      - status
      - createdAt
      - updatedAt
    SystemPromptConfig:
      type: object
      properties:
        text:
          type: string
          description: The system prompt text provided inline.
        configurationBundle:
          $ref: '#/components/schemas/SystemPromptConfigurationBundle'
      description: Exactly one member is set.
    SystemPromptConfigurationBundle:
      type: object
      properties:
        bundleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the configuration bundle.
        versionId:
          type: string
          description: The version identifier of the configuration bundle.
        systemPromptJsonPath:
          type: string
          description: The JSON path within the configuration bundle that contains the system prompt.
      required:
      - bundleArn
      - versionId
      - systemPromptJsonPath
    SystemPromptRecommendationConfig:
      type: object
      properties:
        systemPrompt:
          $ref: '#/components/schemas/SystemPromptConfig'
        agentTraces:
          $ref: '#/components/schemas/AgentTracesConfig'
        evaluationConfig:
          $ref: '#/components/schemas/RecommendationEvaluationConfig'
      required:
      - systemPrompt
      - agentTraces
    SystemPromptRecommendationResult:
      type: object
      properties:
        recommendedSystemPrompt:
          type: string
          description: The optimized system prompt text generated by the recommendation.
        configurationBundle:
          $ref: '#/components/schemas/RecommendationResultConfigurationBundle'
        explanation:
          type: string
          description: An explanation of why the recommendation was generated and what patterns were identified in the agent
            traces.
        errorCode:
          type: string
          description: The error code if the recommendation failed.
        errorMessage:
          type: string
          description: The error message if the recommendation failed.
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
    ToolDescriptionConfig:
      type: object
      properties:
        text:
          type: string
          description: The tool description as inline text.
      description: Exactly one member is set.
    ToolDescriptionConfigurationBundle:
      type: object
      properties:
        bundleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the configuration bundle.
        versionId:
          type: string
          description: The version identifier of the configuration bundle.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationBundleToolEntry'
          description: The list of tool entries mapping tool names to their JSON paths within the bundle.
      required:
      - bundleArn
      - versionId
      - tools
    ToolDescriptionInput:
      type: object
      properties:
        toolName:
          type: string
          description: The name of the tool.
        toolDescription:
          $ref: '#/components/schemas/ToolDescriptionConfig'
      required:
      - toolName
      - toolDescription
    ToolDescriptionOutput:
      type: object
      properties:
        toolName:
          type: string
          description: The name of the tool.
        recommendedToolDescription:
          type: string
          description: The optimized tool description text generated by the recommendation.
        explanation:
          type: string
          description: An explanation of why the recommendation was generated for this tool and what patterns were identified
            in the agent traces.
      required:
      - toolName
    ToolDescriptionRecommendationConfig:
      type: object
      properties:
        toolDescription:
          $ref: '#/components/schemas/ToolDescriptionSource'
        agentTraces:
          $ref: '#/components/schemas/AgentTracesConfig'
      required:
      - toolDescription
      - agentTraces
    ToolDescriptionRecommendationResult:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolDescriptionOutput'
          description: The list of tools with their recommended descriptions.
        configurationBundle:
          $ref: '#/components/schemas/RecommendationResultConfigurationBundle'
        errorCode:
          type: string
          description: The error code if the recommendation failed.
        errorMessage:
          type: string
          description: The error message if the recommendation failed.
    ToolDescriptionSource:
      type: object
      properties:
        toolDescriptionText:
          $ref: '#/components/schemas/ToolDescriptionTextInput'
        configurationBundle:
          $ref: '#/components/schemas/ToolDescriptionConfigurationBundle'
      description: Exactly one member is set.
    ToolDescriptionTextInput:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolDescriptionInput'
          description: The list of tool descriptions to optimize.
      required:
      - tools
    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-agentcore/service/2024-02-28/bedrock-agentcore-2024-02-28.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)