Amazon Bedrock Bedrock Recommendations API
The Bedrock Recommendations API from Amazon Bedrock — 2 operation(s) for bedrock recommendations.
The Bedrock Recommendations API from Amazon Bedrock — 2 operation(s) for bedrock recommendations.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/amazon-bedrock:amazon-bedrock-recommendations-api"
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.
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: 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)