API Reference

Amazon Q Business

API Version 2023-11-27

Copyright © 2024 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon Q Business API Reference

Amazon Q Business: API Reference

Copyright © 2024 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service
that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any
manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are
the property of their respective owners, who may or may not be affiliated with, connected to, or
sponsored by Amazon.
Amazon Q Business API Reference

Table of Contents
Welcome ........................................................................................................................................... 1
QBusiness ....................................................................................................................................................... 1
QApps .............................................................................................................................................................. 1
Actions .............................................................................................................................................. 3
QBusiness ....................................................................................................................................................... 5
BatchDeleteDocument ............................................................................................................................ 8
BatchPutDocument ............................................................................................................................... 12
Chat .......................................................................................................................................................... 18
ChatSync ................................................................................................................................................. 27
CreateApplication .................................................................................................................................. 37
CreateDataSource .................................................................................................................................. 44
CreateIndex ............................................................................................................................................. 52
CreatePlugin ........................................................................................................................................... 58
CreateRetriever ...................................................................................................................................... 64
CreateUser .............................................................................................................................................. 69
CreateWebExperience ........................................................................................................................... 73
DeleteApplication .................................................................................................................................. 79
DeleteChatControlsConfiguration ...................................................................................................... 82
DeleteConversation ............................................................................................................................... 85
DeleteDataSource .................................................................................................................................. 88
DeleteGroup ........................................................................................................................................... 91
DeleteIndex ............................................................................................................................................. 95
DeletePlugin ........................................................................................................................................... 98
DeleteRetriever .................................................................................................................................... 101
DeleteUser ............................................................................................................................................ 104
DeleteWebExperience ........................................................................................................................ 107
GetApplication ..................................................................................................................................... 110
GetChatControlsConfiguration ......................................................................................................... 116
GetDataSource ..................................................................................................................................... 121
GetGroup .............................................................................................................................................. 129
GetIndex ................................................................................................................................................ 133
GetPlugin .............................................................................................................................................. 139
GetRetriever ......................................................................................................................................... 145
GetUser ................................................................................................................................................. 150

API Version 2023-11-27 iii

Amazon Q Business API Reference

GetWebExperience .............................................................................................................................. 153

ListApplications ................................................................................................................................... 159
ListConversations ................................................................................................................................ 162
ListDataSources ................................................................................................................................... 166
ListDataSourceSyncJobs .................................................................................................................... 170
ListDocuments ..................................................................................................................................... 175
ListGroups ............................................................................................................................................ 179
ListIndices ............................................................................................................................................. 183
ListMessages ........................................................................................................................................ 187
ListPlugins ............................................................................................................................................ 192
ListRetrievers ....................................................................................................................................... 196
ListTagsForResource ........................................................................................................................... 200
ListWebExperiences ............................................................................................................................ 203
PutFeedback ......................................................................................................................................... 207
PutGroup .............................................................................................................................................. 211
StartDataSourceSyncJob ................................................................................................................... 216
StopDataSourceSyncJob .................................................................................................................... 220
TagResource ......................................................................................................................................... 223
UntagResource .................................................................................................................................... 226
UpdateApplication .............................................................................................................................. 229
UpdateChatControlsConfiguration .................................................................................................. 234
UpdateDataSource .............................................................................................................................. 240
UpdateIndex ......................................................................................................................................... 246
UpdatePlugin ....................................................................................................................................... 251
UpdateRetriever .................................................................................................................................. 256
UpdateUser .......................................................................................................................................... 260
UpdateWebExperience ....................................................................................................................... 265
QApps ......................................................................................................................................................... 269
AssociateLibraryItemReview ............................................................................................................. 271
AssociateQAppWithUser .................................................................................................................... 274
CreateLibraryItem ............................................................................................................................... 277
CreateQApp .......................................................................................................................................... 282
DeleteLibraryItem ............................................................................................................................... 288
DeleteQApp .......................................................................................................................................... 291
DisassociateLibraryItemReview ........................................................................................................ 294
DisassociateQAppFromUser .............................................................................................................. 297

API Version 2023-11-27 iv

Amazon Q Business API Reference

GetLibraryItem .................................................................................................................................... 300

GetQApp ............................................................................................................................................... 305
GetQAppSession .................................................................................................................................. 310
ImportDocument ................................................................................................................................ 314
ListLibraryItems ................................................................................................................................... 319
ListQApps ............................................................................................................................................. 323
ListTagsForResource ........................................................................................................................... 326
PredictQApp ......................................................................................................................................... 329
StartQAppSession ............................................................................................................................... 333
StopQAppSession ............................................................................................................................... 338
TagResource ......................................................................................................................................... 341
UntagResource .................................................................................................................................... 344
UpdateLibraryItem ............................................................................................................................. 347
UpdateQApp ........................................................................................................................................ 353
UpdateQAppSession ........................................................................................................................... 359
Data Types ................................................................................................................................... 363
QBusiness ................................................................................................................................................... 367
AccessConfiguration ........................................................................................................................... 371
AccessControl ....................................................................................................................................... 372
ActionExecution ................................................................................................................................... 373
ActionExecutionEvent ........................................................................................................................ 375
ActionExecutionPayloadField ........................................................................................................... 377
ActionReview ....................................................................................................................................... 378
ActionReviewEvent ............................................................................................................................. 380
ActionReviewPayloadField ................................................................................................................ 383
ActionReviewPayloadFieldAllowedValue ........................................................................................ 386
APISchema ........................................................................................................................................... 387
Application ........................................................................................................................................... 389
AppliedAttachmentsConfiguration .................................................................................................. 391
AppliedCreatorModeConfiguration ................................................................................................. 392
AttachmentInput ................................................................................................................................. 393
AttachmentInputEvent ...................................................................................................................... 394
AttachmentOutput ............................................................................................................................. 395
AttachmentsConfiguration ............................................................................................................... 397
AttributeFilter ...................................................................................................................................... 398
AuthChallengeRequest ...................................................................................................................... 401

API Version 2023-11-27 v

Amazon Q Business API Reference

AuthChallengeRequestEvent ............................................................................................................ 402

AuthChallengeResponse .................................................................................................................... 403
AuthChallengeResponseEvent .......................................................................................................... 404
BasicAuthConfiguration ..................................................................................................................... 405
BlockedPhrasesConfiguration ........................................................................................................... 407
BlockedPhrasesConfigurationUpdate ............................................................................................. 409
ChatInputStream ................................................................................................................................. 411
ChatModeConfiguration .................................................................................................................... 413
ChatOutputStream ............................................................................................................................. 414
ConfigurationEvent ............................................................................................................................. 416
ContentBlockerRule ............................................................................................................................ 418
ContentRetrievalRule ......................................................................................................................... 419
Conversation ........................................................................................................................................ 420
CreatorModeConfiguration ............................................................................................................... 422
CustomPluginConfiguration ............................................................................................................. 423
DataSource ........................................................................................................................................... 425
DataSourceSyncJob ............................................................................................................................ 427
DataSourceSyncJobMetrics ............................................................................................................... 429
DataSourceVpcConfiguration ........................................................................................................... 431
DateAttributeBoostingConfiguration .............................................................................................. 433
DeleteDocument ................................................................................................................................. 434
Document ............................................................................................................................................. 435
DocumentAttribute ............................................................................................................................. 438
DocumentAttributeBoostingConfiguration ................................................................................... 439
DocumentAttributeCondition ........................................................................................................... 441
DocumentAttributeConfiguration ................................................................................................... 443
DocumentAttributeTarget ................................................................................................................. 445
DocumentAttributeValue .................................................................................................................. 447
DocumentContent .............................................................................................................................. 449
DocumentDetails ................................................................................................................................. 451
DocumentEnrichmentConfiguration ............................................................................................... 453
EligibleDataSource .............................................................................................................................. 455
EncryptionConfiguration ................................................................................................................... 456
EndOfInputEvent ................................................................................................................................ 457
ErrorDetail ............................................................................................................................................ 458
FailedAttachmentEvent ..................................................................................................................... 459

API Version 2023-11-27 vi

Amazon Q Business API Reference

FailedDocument .................................................................................................................................. 461

GroupMembers .................................................................................................................................... 463
GroupStatusDetail .............................................................................................................................. 464
GroupSummary ................................................................................................................................... 465
HookConfiguration ............................................................................................................................. 466
Index ...................................................................................................................................................... 468
IndexCapacityConfiguration ............................................................................................................. 470
IndexStatistics ...................................................................................................................................... 471
InlineDocumentEnrichmentConfiguration ..................................................................................... 472
KendraIndexConfiguration ................................................................................................................ 474
MemberGroup ...................................................................................................................................... 475
MemberUser ......................................................................................................................................... 476
Message ................................................................................................................................................ 477
MessageUsefulnessFeedback ............................................................................................................ 480
MetadataEvent .................................................................................................................................... 482
NativeIndexConfiguration ................................................................................................................. 484
NoAuthConfiguration ......................................................................................................................... 486
NumberAttributeBoostingConfiguration ........................................................................................ 487
OAuth2ClientCredentialConfiguration ........................................................................................... 488
PersonalizationConfiguration ........................................................................................................... 490
Plugin .................................................................................................................................................... 491
PluginAuthConfiguration .................................................................................................................. 494
PluginConfiguration ........................................................................................................................... 496
Principal ................................................................................................................................................ 497
PrincipalGroup ..................................................................................................................................... 498
PrincipalUser ........................................................................................................................................ 500
QAppsConfiguration ........................................................................................................................... 502
Retriever ................................................................................................................................................ 503
RetrieverConfiguration ...................................................................................................................... 505
Rule ........................................................................................................................................................ 507
RuleConfiguration ............................................................................................................................... 509
S3 ........................................................................................................................................................... 510
SamlConfiguration .............................................................................................................................. 511
SnippetExcerpt .................................................................................................................................... 513
SourceAttribution ............................................................................................................................... 514
StringAttributeBoostingConfiguration ........................................................................................... 516

API Version 2023-11-27 vii

Amazon Q Business API Reference

StringListAttributeBoostingConfiguration ..................................................................................... 518

Tag ......................................................................................................................................................... 519
TextDocumentStatistics ..................................................................................................................... 520
TextInputEvent .................................................................................................................................... 521
TextOutputEvent ................................................................................................................................. 522
TextSegment ........................................................................................................................................ 524
TopicConfiguration ............................................................................................................................. 525
UserAlias ............................................................................................................................................... 527
UsersAndGroups .................................................................................................................................. 529
ValidationExceptionField ................................................................................................................... 530
WebExperience .................................................................................................................................... 531
WebExperienceAuthConfiguration .................................................................................................. 533
QApps ......................................................................................................................................................... 533
AppDefinition ....................................................................................................................................... 535
AppDefinitionInput ............................................................................................................................. 536
AttributeFilter ...................................................................................................................................... 537
Card ....................................................................................................................................................... 540
CardInput .............................................................................................................................................. 542
CardStatus ............................................................................................................................................ 544
CardValue ............................................................................................................................................. 545
Category ............................................................................................................................................... 546
ConversationMessage ......................................................................................................................... 547
DocumentAttribute ............................................................................................................................. 548
DocumentAttributeValue .................................................................................................................. 549
FileUploadCard .................................................................................................................................... 551
FileUploadCardInput .......................................................................................................................... 553
LibraryItemMember ............................................................................................................................ 555
PredictAppDefinition .......................................................................................................................... 558
PredictQAppInputOptions ................................................................................................................. 560
QPluginCard ......................................................................................................................................... 562
QPluginCardInput ............................................................................................................................... 564
QQueryCard ......................................................................................................................................... 566
QQueryCardInput ............................................................................................................................... 568
TextInputCard ...................................................................................................................................... 570
TextInputCardInput ............................................................................................................................ 572
UserAppItem ........................................................................................................................................ 574

API Version 2023-11-27 viii

Amazon Q Business API Reference

Common Parameters ................................................................................................................... 576

Common Errors ............................................................................................................................ 579

API Version 2023-11-27 ix

Amazon Q Business API Reference

Welcome

QBusiness
This is the Amazon Q Business API Reference. Amazon Q Business is a fully managed, generative-
AI powered enterprise chat assistant that you can deploy within your organization. Amazon Q
Business enhances employee productivity by supporting key tasks such as question-answering,
knowledge discovery, writing email messages, summarizing text, drafting document outlines, and
brainstorming ideas. Users ask questions of Amazon Q Business and get answers that are presented
in a conversational manner. For an introduction to the service, see the Amazon Q Business User
Guide.

For an overview of the Amazon Q Business APIs, see Overview of Amazon Q Business API
operations.

For information about the IAM access control permissions you need to use this API, see IAM roles
for Amazon Q Business in the Amazon Q Business User Guide.

The following resources provide additional information about using the Amazon Q Business API:

• Setting up for Amazon Q Business

• Amazon Q Business CLI Reference

• AWS General Reference

QApps
The Amazon Q Apps feature capability within Amazon Q Business allows web experience users to
create lightweight, purpose-built AI apps to fulfill specific tasks from within their web experience.
For example, users can create a Q App that exclusively generates marketing-related content to
improve your marketing team's productivity or a Q App for writing customer emails and creating
promotional content using a certain style of voice, tone, and branding. For more information on
the capabilities, see Amazon Q Apps capabilities in the Amazon Q Business User Guide.

For an overview of the Amazon Q App APIs, see Overview of Amazon Q Apps API operations.

QBusiness API Version 2023-11-27 1

Amazon Q Business API Reference

For information about the IAM access control permissions you need to use the Amazon Q Apps API,
see IAM role for the Amazon Q Business web experience including Amazon Q Apps in the Amazon
Q Business User Guide.

QApps API Version 2023-11-27 2

Amazon Q Business API Reference

Actions
The following actions are supported by QBusiness:

• BatchDeleteDocument
• BatchPutDocument
• Chat
• ChatSync
• CreateApplication
• CreateDataSource
• CreateIndex
• CreatePlugin
• CreateRetriever
• CreateUser
• CreateWebExperience
• DeleteApplication
• DeleteChatControlsConfiguration
• DeleteConversation
• DeleteDataSource
• DeleteGroup
• DeleteIndex
• DeletePlugin
• DeleteRetriever
• DeleteUser
• DeleteWebExperience
• GetApplication
• GetChatControlsConfiguration
• GetDataSource
• GetGroup
• GetIndex
• GetPlugin

API Version 2023-11-27 3

Amazon Q Business API Reference

• GetRetriever
• GetUser
• GetWebExperience
• ListApplications
• ListConversations
• ListDataSources
• ListDataSourceSyncJobs
• ListDocuments
• ListGroups
• ListIndices
• ListMessages
• ListPlugins
• ListRetrievers
• ListTagsForResource
• ListWebExperiences
• PutFeedback
• PutGroup
• StartDataSourceSyncJob
• StopDataSourceSyncJob
• TagResource
• UntagResource
• UpdateApplication
• UpdateChatControlsConfiguration
• UpdateDataSource
• UpdateIndex
• UpdatePlugin
• UpdateRetriever
• UpdateUser
• UpdateWebExperience

The following actions are supported by QApps:

API Version 2023-11-27 4

Amazon Q Business API Reference

• AssociateLibraryItemReview
• AssociateQAppWithUser
• CreateLibraryItem
• CreateQApp
• DeleteLibraryItem
• DeleteQApp
• DisassociateLibraryItemReview
• DisassociateQAppFromUser
• GetLibraryItem
• GetQApp
• GetQAppSession
• ImportDocument
• ListLibraryItems
• ListQApps
• ListTagsForResource
• PredictQApp
• StartQAppSession
• StopQAppSession
• TagResource
• UntagResource
• UpdateLibraryItem
• UpdateQApp
• UpdateQAppSession

QBusiness
The following actions are supported by QBusiness:

• BatchDeleteDocument
• BatchPutDocument
• Chat

QBusiness API Version 2023-11-27 5

Amazon Q Business API Reference

• ChatSync
• CreateApplication
• CreateDataSource
• CreateIndex
• CreatePlugin
• CreateRetriever
• CreateUser
• CreateWebExperience
• DeleteApplication
• DeleteChatControlsConfiguration
• DeleteConversation
• DeleteDataSource
• DeleteGroup
• DeleteIndex
• DeletePlugin
• DeleteRetriever
• DeleteUser
• DeleteWebExperience
• GetApplication
• GetChatControlsConfiguration
• GetDataSource
• GetGroup
• GetIndex
• GetPlugin
• GetRetriever
• GetUser
• GetWebExperience
• ListApplications
• ListConversations
• ListDataSources

QBusiness API Version 2023-11-27 6

Amazon Q Business API Reference

• ListDataSourceSyncJobs
• ListDocuments
• ListGroups
• ListIndices
• ListMessages
• ListPlugins
• ListRetrievers
• ListTagsForResource
• ListWebExperiences
• PutFeedback
• PutGroup
• StartDataSourceSyncJob
• StopDataSourceSyncJob
• TagResource
• UntagResource
• UpdateApplication
• UpdateChatControlsConfiguration
• UpdateDataSource
• UpdateIndex
• UpdatePlugin
• UpdateRetriever
• UpdateUser
• UpdateWebExperience

QBusiness API Version 2023-11-27 7

Amazon Q Business API Reference

BatchDeleteDocument
Service: QBusiness

Asynchronously deletes one or more documents added using the BatchPutDocument API from an
Amazon Q Business index.

You can see the progress of the deletion, and any error messages related to the process, by using
CloudWatch.

Request Syntax

POST /applications/applicationId/indices/indexId/documents/delete HTTP/1.1

Content-type: application/json

{
"dataSourceSyncId": "string",
"documents": [
{
"documentId": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the Amazon Q Business index that contains the documents to delete.

Length Constraints: Fixed length of 36.

BatchDeleteDocument API Version 2023-11-27 8

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

dataSourceSyncId

The identifier of the data source sync during which the documents were deleted.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
documents

Documents deleted from the Amazon Q Business index.

Type: Array of DeleteDocument objects

Required: Yes

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"failedDocuments": [
{
"dataSourceId": "string",
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"id": "string"

BatchDeleteDocument API Version 2023-11-27 9

Amazon Q Business API Reference

}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

failedDocuments

A list of documents that couldn't be removed from the Amazon Q Business index. Each entry
contains an error message that indicates why the document couldn't be removed from the
index.

Type: Array of FailedDocument objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

BatchDeleteDocument API Version 2023-11-27 10

Amazon Q Business API Reference

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

BatchDeleteDocument API Version 2023-11-27 11

Amazon Q Business API Reference

BatchPutDocument
Service: QBusiness

Adds one or more documents to an Amazon Q Business index.

You use this API to:

• ingest your structured and unstructured documents and documents stored in an Amazon S3
bucket into an Amazon Q Business index.
• add custom attributes to documents in an Amazon Q Business index.
• attach an access control list to the documents added to an Amazon Q Business index.

You can see the progress of the deletion, and any error messages related to the process, by using
CloudWatch.

Request Syntax

POST /applications/applicationId/indices/indexId/documents HTTP/1.1

Content-type: application/json

{
"dataSourceSyncId": "string",
"documents": [
{
"accessConfiguration": {
"accessControls": [
{
"memberRelation": "string",
"principals": [
{ ... }
]
}
],
"memberRelation": "string"
},
"attributes": [
{
"name": "string",
"value": { ... }
}
],

BatchPutDocument API Version 2023-11-27 12

Amazon Q Business API Reference

"content": { ... },
"contentType": "string",
"documentEnrichmentConfiguration": {
"inlineConfigurations": [
{
"condition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"documentContentOperator": "string",
"target": {
"attributeValueOperator": "string",
"key": "string",
"value": { ... }
}
}
],
"postExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"
},
"preExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"
}
},
"id": "string",
"title": "string"
}
],
"roleArn": "string"

BatchPutDocument API Version 2023-11-27 13

Amazon Q Business API Reference

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the Amazon Q Business index to add the documents to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

dataSourceSyncId

The identifier of the data source sync during which the documents were added.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
documents

One or more documents to add to the index.

BatchPutDocument API Version 2023-11-27 14

Amazon Q Business API Reference

Type: Array of Document objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: Yes
roleArn

The Amazon Resource Name (ARN) of an IAM role with permission to access your S3 bucket.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"failedDocuments": [
{
"dataSourceId": "string",
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"id": "string"
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

BatchPutDocument API Version 2023-11-27 15

Amazon Q Business API Reference

failedDocuments

A list of documents that were not added to the Amazon Q Business index because the
document failed a validation check. Each document contains an error message that indicates
why the document couldn't be added to the index.

Type: Array of FailedDocument objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

BatchPutDocument API Version 2023-11-27 16

Amazon Q Business API Reference

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

BatchPutDocument API Version 2023-11-27 17

Amazon Q Business API Reference

Chat
Service: QBusiness

Starts or continues a streaming Amazon Q Business conversation.

Request Syntax

POST /applications/applicationId/conversations?
clientToken=clientToken&conversationId=conversationId&parentMessageId=parentMessageId&userGroup
HTTP/1.1
Content-type: application/json

{
"actionExecutionEvent": {
"payload": {
"string" : {
"value": JSON value
}
},
"payloadFieldNameSeparator": "string",
"pluginId": "string"
},
"attachmentEvent": {
"attachment": {
"data": blob,
"name": "string"
}
},
"authChallengeResponseEvent": {
"responseMap": {
"string" : "string"
}
},
"configurationEvent": {
"attributeFilter": {
"andAllFilters": [
"AttributeFilter"
],
"containsAll": {
"name": "string",
"value": { ... }
},
"containsAny": {

Chat API Version 2023-11-27 18

Amazon Q Business API Reference

"name": "string",
"value": { ... }
},
"equalsTo": {
"name": "string",
"value": { ... }
},
"greaterThan": {
"name": "string",
"value": { ... }
},
"greaterThanOrEquals": {
"name": "string",
"value": { ... }
},
"lessThan": {
"name": "string",
"value": { ... }
},
"lessThanOrEquals": {
"name": "string",
"value": { ... }
},
"notFilter": "AttributeFilter",
"orAllFilters": [
"AttributeFilter"
]
},
"chatMode": "string",
"chatModeConfiguration": { ... }
},
"endOfInputEvent": {
},
"textEvent": {
"userMessage": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

Chat API Version 2023-11-27 19

Amazon Q Business API Reference

applicationId

The identifier of the Amazon Q Business application linked to a streaming Amazon Q Business
conversation.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
clientToken

A token that you provide to identify the chat input.

Length Constraints: Minimum length of 1. Maximum length of 100.

conversationId

The identifier of the Amazon Q Business conversation.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
parentMessageId

The identifier used to associate a user message with a AI generated response.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
userGroups

The groups that a user associated with the chat input belongs to.

Length Constraints: Minimum length of 1. Maximum length of 2048.

userId

The identifier of the user attached to the chat input.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Chat API Version 2023-11-27 20

Amazon Q Business API Reference

Request Body

The request accepts the following data in JSON format.

actionExecutionEvent

A request from an end user to perform an Amazon Q Business plugin action.

Type: ActionExecutionEvent object

Required: No
attachmentEvent

A request by an end user to upload a file during chat.

Type: AttachmentInputEvent object

Required: No
authChallengeResponseEvent

An authentication verification event response by a third party authentication server to Amazon

Q Business.

Type: AuthChallengeResponseEvent object

Required: No
configurationEvent

A configuration event activated by an end user request to select a specific chat mode.

Type: ConfigurationEvent object

Required: No
endOfInputEvent

The end of the streaming input for the Chat API.

Type: EndOfInputEvent object

Required: No
textEvent

Information about the payload of the ChatInputStream event containing the end user
message input.

Chat API Version 2023-11-27 21

Amazon Q Business API Reference

Type: TextInputEvent object

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"actionReviewEvent": {
"conversationId": "string",
"payload": {
"string" : {
"allowedFormat": "string",
"allowedValues": [
{
"displayValue": JSON value,
"value": JSON value
}
],
"displayDescription": "string",
"displayName": "string",
"displayOrder": number,
"required": boolean,
"type": "string",
"value": JSON value
}
},
"payloadFieldNameSeparator": "string",
"pluginId": "string",
"pluginType": "string",
"systemMessageId": "string",
"userMessageId": "string"
},
"authChallengeRequestEvent": {
"authorizationUrl": "string"
},
"failedAttachmentEvent": {
"attachment": {
"error": {
"errorCode": "string",
"errorMessage": "string"

Chat API Version 2023-11-27 22

Amazon Q Business API Reference

},
"name": "string",
"status": "string"
},
"conversationId": "string",
"systemMessageId": "string",
"userMessageId": "string"
},
"metadataEvent": {
"conversationId": "string",
"finalTextMessage": "string",
"sourceAttributions": [
{
"citationNumber": number,
"snippet": "string",
"textMessageSegments": [
{
"beginOffset": number,
"endOffset": number,
"snippetExcerpt": {
"text": "string"
}
}
],
"title": "string",
"updatedAt": number,
"url": "string"
}
],
"systemMessageId": "string",
"userMessageId": "string"
},
"textEvent": {
"conversationId": "string",
"systemMessage": "string",
"systemMessageId": "string",
"userMessageId": "string"
}
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

Chat API Version 2023-11-27 23

Amazon Q Business API Reference

The following data is returned in JSON format by the service.

actionReviewEvent

A request from Amazon Q Business to the end user for information Amazon Q Business needs
to successfully complete a requested plugin action.

Type: ActionReviewEvent object

authChallengeRequestEvent

An authentication verification event activated by an end user request to use a custom plugin.

Type: AuthChallengeRequestEvent object

failedAttachmentEvent

A failed file upload event during a web experience chat.

Type: FailedAttachmentEvent object

metadataEvent

A metadata event for a AI-generated text output message in a Amazon Q Business conversation.

Type: MetadataEvent object

textEvent

Information about the payload of the ChatOutputStream event containing the AI-generated
message output.

Type: TextOutputEvent object

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

Chat API Version 2023-11-27 24

Amazon Q Business API Reference

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

LicenseNotFoundException

You don't have permissions to perform the action because your license is inactive. Ask your
admin to activate your license and try again after your licence is active.

HTTP Status Code: 400

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

Chat API Version 2023-11-27 25

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

Chat API Version 2023-11-27 26

Amazon Q Business API Reference

ChatSync
Service: QBusiness

Starts or continues a non-streaming Amazon Q Business conversation.

Request Syntax

POST /applications/applicationId/conversations?sync&userGroups=userGroups&userId=userId
HTTP/1.1
Content-type: application/json

{
"actionExecution": {
"payload": {
"string" : {
"value": JSON value
}
},
"payloadFieldNameSeparator": "string",
"pluginId": "string"
},
"attachments": [
{
"data": blob,
"name": "string"
}
],
"attributeFilter": {
"andAllFilters": [
"AttributeFilter"
],
"containsAll": {
"name": "string",
"value": { ... }
},
"containsAny": {
"name": "string",
"value": { ... }
},
"equalsTo": {
"name": "string",
"value": { ... }
},

ChatSync API Version 2023-11-27 27

Amazon Q Business API Reference

"greaterThan": {
"name": "string",
"value": { ... }
},
"greaterThanOrEquals": {
"name": "string",
"value": { ... }
},
"lessThan": {
"name": "string",
"value": { ... }
},
"lessThanOrEquals": {
"name": "string",
"value": { ... }
},
"notFilter": "AttributeFilter",
"orAllFilters": [
"AttributeFilter"
]
},
"authChallengeResponse": {
"responseMap": {
"string" : "string"
}
},
"chatMode": "string",
"chatModeConfiguration": { ... },
"clientToken": "string",
"conversationId": "string",
"parentMessageId": "string",
"userMessage": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application linked to the Amazon Q Business
conversation.

Length Constraints: Fixed length of 36.

ChatSync API Version 2023-11-27 28

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
userGroups

The groups that a user associated with the chat input belongs to.

Length Constraints: Minimum length of 1. Maximum length of 2048.

userId

The identifier of the user attached to the chat input.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Request Body

The request accepts the following data in JSON format.

actionExecution

A request from an end user to perform an Amazon Q Business plugin action.

Type: ActionExecution object

Required: No
attachments

A list of files uploaded directly during chat. You can upload a maximum of 5 files of upto 10 MB
each.

Type: Array of AttachmentInput objects

Array Members: Minimum number of 1 item.

Required: No
attributeFilter

Enables filtering of Amazon Q Business web experience responses based on document

attributes or metadata fields.

Type: AttributeFilter object

ChatSync API Version 2023-11-27 29

Amazon Q Business API Reference

Required: No
authChallengeResponse

An authentication verification event response by a third party authentication server to Amazon

Q Business.

Type: AuthChallengeResponse object

Required: No
chatMode

The chat modes available to an Amazon Q Business end user.

• RETRIEVAL_MODE - The default chat mode for an Amazon Q Business application. When this
mode is enabled, Amazon Q Business generates responses only from data sources connected
to an Amazon Q Business application.
• CREATOR_MODE - By selecting this mode, users can choose to generate responses only from
the LLM knowledge, without consulting connected data sources, for a chat request.
• PLUGIN_MODE - By selecting this mode, users can choose to use plugins in chat.

For more information, see Admin controls and guardrails, Plugins, and Conversation settings.

Type: String

Valid Values: RETRIEVAL_MODE | CREATOR_MODE | PLUGIN_MODE

Required: No
chatModeConfiguration

The chat mode configuration for an Amazon Q Business application.

Type: ChatModeConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No
clientToken

A token that you provide to identify a chat request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

ChatSync API Version 2023-11-27 30

Amazon Q Business API Reference

Required: No
conversationId

The identifier of the Amazon Q Business conversation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
parentMessageId

The identifier of the previous system message in a conversation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
userMessage

A end user message in a conversation.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 7000.

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"actionReview": {
"payload": {
"string" : {
"allowedFormat": "string",

ChatSync API Version 2023-11-27 31

Amazon Q Business API Reference

"allowedValues": [
{
"displayValue": JSON value,
"value": JSON value
}
],
"displayDescription": "string",
"displayName": "string",
"displayOrder": number,
"required": boolean,
"type": "string",
"value": JSON value
}
},
"payloadFieldNameSeparator": "string",
"pluginId": "string",
"pluginType": "string"
},
"authChallengeRequest": {
"authorizationUrl": "string"
},
"conversationId": "string",
"failedAttachments": [
{
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"name": "string",
"status": "string"
}
],
"sourceAttributions": [
{
"citationNumber": number,
"snippet": "string",
"textMessageSegments": [
{
"beginOffset": number,
"endOffset": number,
"snippetExcerpt": {
"text": "string"
}
}

ChatSync API Version 2023-11-27 32

Amazon Q Business API Reference

],
"title": "string",
"updatedAt": number,
"url": "string"
}
],
"systemMessage": "string",
"systemMessageId": "string",
"userMessageId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

actionReview

A request from Amazon Q Business to the end user for information Amazon Q Business needs
to successfully complete a requested plugin action.

Type: ActionReview object

authChallengeRequest

An authentication verification event activated by an end user request to use a custom plugin.

Type: AuthChallengeRequest object

conversationId

The identifier of the Amazon Q Business conversation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
failedAttachments

A list of files which failed to upload during chat.

Type: Array of AttachmentOutput objects

ChatSync API Version 2023-11-27 33

Amazon Q Business API Reference

sourceAttributions

The source documents used to generate the conversation response.

Type: Array of SourceAttribution objects

systemMessage

An AI-generated message in a conversation.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

systemMessageId

The identifier of an Amazon Q Business AI generated message within the conversation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
userMessageId

The identifier of an Amazon Q Business end user text input message within the conversation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ChatSync API Version 2023-11-27 34

Amazon Q Business API Reference

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

LicenseNotFoundException

You don't have permissions to perform the action because your license is inactive. Ask your
admin to activate your license and try again after your licence is active.

HTTP Status Code: 400

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

ChatSync API Version 2023-11-27 35

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ChatSync API Version 2023-11-27 36

Amazon Q Business API Reference

CreateApplication
Service: QBusiness

Creates an Amazon Q Business application.

Note
There are new tiers for Amazon Q Business. Not all features in Amazon Q Business Pro are
also available in Amazon Q Business Lite. For information on what's included in Amazon Q
Business Lite and what's included in Amazon Q Business Pro, see Amazon Q Business tiers.
You must use the Amazon Q Business console to assign subscription tiers to users.

Request Syntax

POST /applications HTTP/1.1

Content-type: application/json

{
"attachmentsConfiguration": {
"attachmentsControlMode": "string"
},
"clientToken": "string",
"description": "string",
"displayName": "string",
"encryptionConfiguration": {
"kmsKeyId": "string"
},
"identityCenterInstanceArn": "string",
"personalizationConfiguration": {
"personalizationControlMode": "string"
},
"qAppsConfiguration": {
"qAppsControlMode": "string"
},
"roleArn": "string",
"tags": [
{
"key": "string",
"value": "string"
}
]

CreateApplication API Version 2023-11-27 37

Amazon Q Business API Reference

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

attachmentsConfiguration

An option to allow end users to upload files directly during chat.

Type: AttachmentsConfiguration object

Required: No
clientToken

A token that you provide to identify the request to create your Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
description

A description for the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
displayName

A name for the Amazon Q Business application.

Type: String

CreateApplication API Version 2023-11-27 38

Amazon Q Business API Reference

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: Yes
encryptionConfiguration

The identifier of the AWS KMS key that is used to encrypt your data. Amazon Q Business doesn't
support asymmetric keys.

Type: EncryptionConfiguration object

Required: No
identityCenterInstanceArn

The Amazon Resource Name (ARN) of the IAM Identity Center instance you are either creating
for—or connecting to—your Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 10. Maximum length of 1224.

Pattern: ^arn:(aws|aws-us-gov|aws-cn|aws-iso|aws-iso-b):sso:::instance/
(sso)?ins-[a-zA-Z0-9-.]{16}$

Required: No
personalizationConfiguration

Configuration information about chat response personalization. For more information, see
Personalizing chat responses

Type: PersonalizationConfiguration object

Required: No
qAppsConfiguration

An option to allow end users to create and use Amazon Q Apps in the web experience.

Type: QAppsConfiguration object

Required: No

CreateApplication API Version 2023-11-27 39

Amazon Q Business API Reference

roleArn

The Amazon Resource Name (ARN) of an IAM role with permissions to access your Amazon
CloudWatch logs and metrics.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No
tags

A list of key-value pairs that identify or categorize your Amazon Q Business application. You
can also use tags to help control access to the application. Tag keys and values can consist of
Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"applicationArn": "string",
"applicationId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

CreateApplication API Version 2023-11-27 40

Amazon Q Business API Reference

applicationArn

The Amazon Resource Name (ARN) of the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
applicationId

The identifier of the Amazon Q Business application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

CreateApplication API Version 2023-11-27 41

Amazon Q Business API Reference

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python

CreateApplication API Version 2023-11-27 42

Amazon Q Business API Reference

• AWS SDK for Ruby V3

CreateApplication API Version 2023-11-27 43

Amazon Q Business API Reference

CreateDataSource
Service: QBusiness

Creates a data source connector for an Amazon Q Business application.

CreateDataSource is a synchronous operation. The operation returns 200 if the data source was
successfully created. Otherwise, an exception is raised.

Request Syntax

POST /applications/applicationId/indices/indexId/datasources HTTP/1.1

Content-type: application/json

{
"clientToken": "string",
"configuration": JSON value,
"description": "string",
"displayName": "string",
"documentEnrichmentConfiguration": {
"inlineConfigurations": [
{
"condition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"documentContentOperator": "string",
"target": {
"attributeValueOperator": "string",
"key": "string",
"value": { ... }
}
}
],
"postExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"

CreateDataSource API Version 2023-11-27 44

Amazon Q Business API Reference

},
"preExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"
}
},
"roleArn": "string",
"syncSchedule": "string",
"tags": [
{
"key": "string",
"value": "string"
}
],
"vpcConfiguration": {
"securityGroupIds": [ "string" ],
"subnetIds": [ "string" ]
}
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application the data source will be attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the index that you want to use with the data source connector.

Length Constraints: Fixed length of 36.

CreateDataSource API Version 2023-11-27 45

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

clientToken

A token you provide to identify a request to create a data source connector. Multiple calls to the
CreateDataSource API with the same client token will create only one data source connector.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
configuration

Configuration information to connect your data source repository to Amazon Q Business. Use
this parameter to provide a JSON schema with configuration information specific to your data
source connector.

Each data source has a JSON schema provided by Amazon Q Business that you must use. For
example, the Amazon S3 and Web Crawler connectors require the following JSON schemas:
• Amazon S3 JSON schema
• Web Crawler JSON schema

You can find configuration templates for your specific data source using the following steps:
1. Navigate to the Supported connectors page in the Amazon Q Business User Guide, and select
the data source of your choice.
2. Then, from your specific data source connector page, select Using the API. You will find the
JSON schema for your data source, including parameter descriptions, in this section.

Type: JSON value

Required: Yes

CreateDataSource API Version 2023-11-27 46

Amazon Q Business API Reference

description

A description for the data source connector.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
displayName

A name for the data source connector.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: Yes
documentEnrichmentConfiguration

Provides the configuration information for altering document metadata and content during the
document ingestion process.

For more information, see Custom document enrichment.

Type: DocumentEnrichmentConfiguration object

Required: No
roleArn

The Amazon Resource Name (ARN) of an IAM role with permission to access the data source and
required resources.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

CreateDataSource API Version 2023-11-27 47

Amazon Q Business API Reference

Required: No
syncSchedule

Sets the frequency for Amazon Q Business to check the documents in your data source
repository and update your index. If you don't set a schedule, Amazon Q Business won't
periodically update the index.

Specify a cron- format schedule string or an empty string to indicate that the index is updated
on demand. You can't specify the Schedule parameter when the Type parameter is set to
CUSTOM. If you do, you receive a ValidationException exception.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 998.

Pattern: ^\P{C}*$

Required: No
tags

A list of key-value pairs that identify or categorize the data source connector. You can also use
tags to help control access to the data source connector. Tag keys and values can consist of
Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No
vpcConfiguration

Configuration information for an Amazon VPC (Virtual Private Cloud) to connect to your data
source. For more information, see Using Amazon VPC with Amazon Q Business connectors.

Type: DataSourceVpcConfiguration object

Required: No

Response Syntax

HTTP/1.1 200

CreateDataSource API Version 2023-11-27 48

Amazon Q Business API Reference

Content-type: application/json

{
"dataSourceArn": "string",
"dataSourceId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

dataSourceArn

The Amazon Resource Name (ARN) of a data source in an Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
dataSourceId

The identifier of the data source connector.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

CreateDataSource API Version 2023-11-27 49

Amazon Q Business API Reference

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

CreateDataSource API Version 2023-11-27 50

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

CreateDataSource API Version 2023-11-27 51

Amazon Q Business API Reference

CreateIndex
Service: QBusiness

Creates an Amazon Q Business index.

To determine if index creation has completed, check the Status field returned from a call to
DescribeIndex. The Status field is set to ACTIVE when the index is ready to use.

Once the index is active, you can index your documents using the BatchPutDocument API or the
CreateDataSource API.

Request Syntax

POST /applications/applicationId/indices HTTP/1.1

Content-type: application/json

{
"capacityConfiguration": {
"units": number
},
"clientToken": "string",
"description": "string",
"displayName": "string",
"tags": [
{
"key": "string",
"value": "string"
}
],
"type": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application using the index.

Length Constraints: Fixed length of 36.

CreateIndex API Version 2023-11-27 52

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

capacityConfiguration

The capacity units you want to provision for your index. You can add and remove capacity to fit
your usage needs.

Type: IndexCapacityConfiguration object

Required: No
clientToken

A token that you provide to identify the request to create an index. Multiple calls to the
CreateIndex API with the same client token will create only one index.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
description

A description for the Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
displayName

A name for the Amazon Q Business index.

Type: String

CreateIndex API Version 2023-11-27 53

Amazon Q Business API Reference

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: Yes
tags

A list of key-value pairs that identify or categorize the index. You can also use tags to help
control access to the index. Tag keys and values can consist of Unicode letters, digits, white
space, and any of the following symbols: _ . : / = + - @.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No
type

The index type that's suitable for your needs. For more information on what's included in each
type of index, see Amazon Q Business tiers.

Type: String

Valid Values: ENTERPRISE | STARTER

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"indexArn": "string",
"indexId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

CreateIndex API Version 2023-11-27 54

Amazon Q Business API Reference

The following data is returned in JSON format by the service.

indexArn

The Amazon Resource Name (ARN) of an Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
indexId

The identifier for the Amazon Q Business index.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

CreateIndex API Version 2023-11-27 55

Amazon Q Business API Reference

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python

CreateIndex API Version 2023-11-27 56

Amazon Q Business API Reference

• AWS SDK for Ruby V3

CreateIndex API Version 2023-11-27 57

Amazon Q Business API Reference

CreatePlugin
Service: QBusiness

Creates an Amazon Q Business plugin.

Request Syntax

POST /applications/applicationId/plugins HTTP/1.1

Content-type: application/json

{
"authConfiguration": { ... },
"clientToken": "string",
"customPluginConfiguration": {
"apiSchema": { ... },
"apiSchemaType": "string",
"description": "string"
},
"displayName": "string",
"serverUrl": "string",
"tags": [
{
"key": "string",
"value": "string"
}
],
"type": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application that will contain the plugin.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

CreatePlugin API Version 2023-11-27 58

Amazon Q Business API Reference

Request Body

The request accepts the following data in JSON format.

authConfiguration

Authentication configuration information for an Amazon Q Business plugin.

Type: PluginAuthConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: Yes
clientToken

A token that you provide to identify the request to create your Amazon Q Business plugin.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
customPluginConfiguration

Contains configuration for a custom plugin.

Type: CustomPluginConfiguration object

Required: No
displayName

A the name for your plugin.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: Yes
serverUrl

The source URL used for plugin configuration.

CreatePlugin API Version 2023-11-27 59

Amazon Q Business API Reference

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$

Required: No
tags

A list of key-value pairs that identify or categorize the data source connector. You can also use
tags to help control access to the data source connector. Tag keys and values can consist of
Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No
type

The type of plugin you want to create.

Type: String

Valid Values: SERVICE_NOW | SALESFORCE | JIRA | ZENDESK | CUSTOM

Required: Yes

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"buildStatus": "string",
"pluginArn": "string",
"pluginId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

CreatePlugin API Version 2023-11-27 60

Amazon Q Business API Reference

The following data is returned in JSON format by the service.

buildStatus

The current status of a plugin. A plugin is modified asynchronously.

Type: String

Valid Values: READY | CREATE_IN_PROGRESS | CREATE_FAILED |

UPDATE_IN_PROGRESS | UPDATE_FAILED | DELETE_IN_PROGRESS | DELETE_FAILED
pluginArn

The Amazon Resource Name (ARN) of a plugin.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
pluginId

The identifier of the plugin created.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

CreatePlugin API Version 2023-11-27 61

Amazon Q Business API Reference

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

CreatePlugin API Version 2023-11-27 62

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

CreatePlugin API Version 2023-11-27 63

Amazon Q Business API Reference

CreateRetriever
Service: QBusiness

Adds a retriever to your Amazon Q Business application.

Request Syntax

POST /applications/applicationId/retrievers HTTP/1.1

Content-type: application/json

{
"clientToken": "string",
"configuration": { ... },
"displayName": "string",
"roleArn": "string",
"tags": [
{
"key": "string",
"value": "string"
}
],
"type": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of your Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

CreateRetriever API Version 2023-11-27 64

Amazon Q Business API Reference

clientToken

A token that you provide to identify the request to create your Amazon Q Business application
retriever.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
configuration

Provides information on how the retriever used for your Amazon Q Business application is
configured.

Type: RetrieverConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: Yes
displayName

The name of your retriever.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: Yes
roleArn

The ARN of an IAM role used by Amazon Q Business to access the basic authentication
credentials stored in a Secrets Manager secret.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No

CreateRetriever API Version 2023-11-27 65

Amazon Q Business API Reference

tags

A list of key-value pairs that identify or categorize the retriever. You can also use tags to help
control access to the retriever. Tag keys and values can consist of Unicode letters, digits, white
space, and any of the following symbols: _ . : / = + - @.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No
type

The type of retriever you are using.

Type: String

Valid Values: NATIVE_INDEX | KENDRA_INDEX

Required: Yes

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"retrieverArn": "string",
"retrieverId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

retrieverArn

The Amazon Resource Name (ARN) of an IAM role associated with a retriever.

Type: String

CreateRetriever API Version 2023-11-27 66

Amazon Q Business API Reference

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
retrieverId

The identifier of the retriever you are using.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

CreateRetriever API Version 2023-11-27 67

Amazon Q Business API Reference

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

CreateRetriever API Version 2023-11-27 68

Amazon Q Business API Reference

CreateUser
Service: QBusiness

Creates a universally unique identifier (UUID) mapped to a list of local user ids within an
application.

Request Syntax

POST /applications/applicationId/users HTTP/1.1

Content-type: application/json

{
"clientToken": "string",
"userAliases": [
{
"dataSourceId": "string",
"indexId": "string",
"userId": "string"
}
],
"userId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application for which the user mapping will be created.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

CreateUser API Version 2023-11-27 69

Amazon Q Business API Reference

clientToken

A token that you provide to identify the request to create your Amazon Q Business user
mapping.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
userAliases

The list of user aliases in the mapping.

Type: Array of UserAlias objects

Array Members: Minimum number of 0 items. Maximum number of 100 items.

Required: No
userId

The user emails attached to a user mapping.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

CreateUser API Version 2023-11-27 70

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

CreateUser API Version 2023-11-27 71

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

CreateUser API Version 2023-11-27 72

Amazon Q Business API Reference

CreateWebExperience
Service: QBusiness

Creates an Amazon Q Business web experience.

Request Syntax

POST /applications/applicationId/experiences HTTP/1.1

Content-type: application/json

{
"clientToken": "string",
"roleArn": "string",
"samplePromptsControlMode": "string",
"subtitle": "string",
"tags": [
{
"key": "string",
"value": "string"
}
],
"title": "string",
"welcomeMessage": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business web experience.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

CreateWebExperience API Version 2023-11-27 73

Amazon Q Business API Reference

clientToken

A token you provide to identify a request to create an Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
roleArn

The Amazon Resource Name (ARN) of the service role attached to your web experience.

Note
You must provide this value if you're using IAM Identity Center to manage end user
access to your application. If you're using legacy identity management to manage user
access, you don't need to provide this value.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No
samplePromptsControlMode

Determines whether sample prompts are enabled in the web experience for an end user.

Type: String

Valid Values: ENABLED | DISABLED

Required: No
subtitle

A subtitle to personalize your Amazon Q Business web experience.

Type: String

CreateWebExperience API Version 2023-11-27 74

Amazon Q Business API Reference

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: ^\P{C}*$

Required: No
tags

A list of key-value pairs that identify or categorize your Amazon Q Business web experience. You
can also use tags to help control access to the web experience. Tag keys and values can consist
of Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No
title

The title for your Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: ^\P{C}*$

Required: No
welcomeMessage

The customized welcome message for end users of an Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 300.

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

CreateWebExperience API Version 2023-11-27 75

Amazon Q Business API Reference

{
"webExperienceArn": "string",
"webExperienceId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

webExperienceArn

The Amazon Resource Name (ARN) of an Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
webExperienceId

The identifier of the Amazon Q Business web experience.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

CreateWebExperience API Version 2023-11-27 76

Amazon Q Business API Reference

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

CreateWebExperience API Version 2023-11-27 77

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

CreateWebExperience API Version 2023-11-27 78

Amazon Q Business API Reference

DeleteApplication
Service: QBusiness

Deletes an Amazon Q Business application.

Request Syntax

DELETE /applications/applicationId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

DeleteApplication API Version 2023-11-27 79

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

DeleteApplication API Version 2023-11-27 80

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteApplication API Version 2023-11-27 81

Amazon Q Business API Reference

DeleteChatControlsConfiguration
Service: QBusiness

Deletes chat controls configured for an existing Amazon Q Business application.

Request Syntax

DELETE /applications/applicationId/chatcontrols HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application the chat controls have been configured for.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

DeleteChatControlsConfiguration API Version 2023-11-27 82

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

DeleteChatControlsConfiguration API Version 2023-11-27 83

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteChatControlsConfiguration API Version 2023-11-27 84

Amazon Q Business API Reference

DeleteConversation
Service: QBusiness

Deletes an Amazon Q Business web experience conversation.

Request Syntax

DELETE /applications/applicationId/conversations/conversationId?userId=userId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application associated with the conversation.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
conversationId

The identifier of the Amazon Q Business web experience conversation being deleted.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
userId

The identifier of the user who is deleting the conversation.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Request Body

The request does not have a request body.

DeleteConversation API Version 2023-11-27 85

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

LicenseNotFoundException

You don't have permissions to perform the action because your license is inactive. Ask your
admin to activate your license and try again after your licence is active.

HTTP Status Code: 400

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

DeleteConversation API Version 2023-11-27 86

Amazon Q Business API Reference

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteConversation API Version 2023-11-27 87

Amazon Q Business API Reference

DeleteDataSource
Service: QBusiness

Deletes an Amazon Q Business data source connector. While the data source is being deleted, the
Status field returned by a call to the DescribeDataSource API is set to DELETING.

Request Syntax

DELETE /applications/applicationId/indices/indexId/datasources/dataSourceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application used with the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source connector that you want to delete.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the index used with the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

DeleteDataSource API Version 2023-11-27 88

Amazon Q Business API Reference

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

DeleteDataSource API Version 2023-11-27 89

Amazon Q Business API Reference

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteDataSource API Version 2023-11-27 90

Amazon Q Business API Reference

DeleteGroup
Service: QBusiness

Deletes a group so that all users and sub groups that belong to the group can no longer access
documents only available to that group. For example, after deleting the group "Summer Interns",
all interns who belonged to that group no longer see intern-only documents in their chat results.

If you want to delete, update, or replace users or sub groups of a group, you need to use the
PutGroup operation. For example, if a user in the group "Engineering" leaves the engineering team
and another user takes their place, you provide an updated list of users or sub groups that belong
to the "Engineering" group when calling PutGroup.

Request Syntax

DELETE /applications/applicationId/indices/indexId/groups/groupName?
dataSourceId=dataSourceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application in which the group mapping belongs.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source linked to the group

A group can be tied to multiple data sources. You can delete a group from accessing documents
in a certain data source. For example, the groups "Research", "Engineering", and "Sales and
Marketing" are all tied to the company's documents stored in the data sources Confluence and
Salesforce. You want to delete "Research" and "Engineering" groups from Salesforce, so that
these groups cannot access customer-related documents stored in Salesforce. Only "Sales and
Marketing" should access documents in the Salesforce data source.

DeleteGroup API Version 2023-11-27 91

Amazon Q Business API Reference

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
groupName

The name of the group you want to delete.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: Yes
indexId

The identifier of the index you want to delete the group from.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

DeleteGroup API Version 2023-11-27 92

Amazon Q Business API Reference

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

DeleteGroup API Version 2023-11-27 93

Amazon Q Business API Reference

• AWS SDK for Go v2

• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteGroup API Version 2023-11-27 94

Amazon Q Business API Reference

DeleteIndex
Service: QBusiness

Deletes an Amazon Q Business index.

Request Syntax

DELETE /applications/applicationId/indices/indexId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application the Amazon Q Business index is linked to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the Amazon Q Business index.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

DeleteIndex API Version 2023-11-27 95

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

DeleteIndex API Version 2023-11-27 96

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteIndex API Version 2023-11-27 97

Amazon Q Business API Reference

DeletePlugin
Service: QBusiness

Deletes an Amazon Q Business plugin.

Request Syntax

DELETE /applications/applicationId/plugins/pluginId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier the application attached to the Amazon Q Business plugin.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
pluginId

The identifier of the plugin being deleted.

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

DeletePlugin API Version 2023-11-27 98

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

DeletePlugin API Version 2023-11-27 99

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeletePlugin API Version 2023-11-27 100

Amazon Q Business API Reference

DeleteRetriever
Service: QBusiness

Deletes the retriever used by an Amazon Q Business application.

Request Syntax

DELETE /applications/applicationId/retrievers/retrieverId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application using the retriever.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
retrieverId

The identifier of the retriever being deleted.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

DeleteRetriever API Version 2023-11-27 101

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

DeleteRetriever API Version 2023-11-27 102

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteRetriever API Version 2023-11-27 103

Amazon Q Business API Reference

DeleteUser
Service: QBusiness

Deletes a user by email id.

Request Syntax

DELETE /applications/applicationId/users/userId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application from which the user is being deleted.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
userId

The user email being deleted.

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

DeleteUser API Version 2023-11-27 104

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

DeleteUser API Version 2023-11-27 105

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteUser API Version 2023-11-27 106

Amazon Q Business API Reference

DeleteWebExperience
Service: QBusiness

Deletes an Amazon Q Business web experience.

Request Syntax

DELETE /applications/applicationId/experiences/webExperienceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application linked to the Amazon Q Business web
experience.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
webExperienceId

The identifier of the Amazon Q Business web experience being deleted.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

DeleteWebExperience API Version 2023-11-27 107

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

DeleteWebExperience API Version 2023-11-27 108

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteWebExperience API Version 2023-11-27 109

Amazon Q Business API Reference

GetApplication
Service: QBusiness

Gets information about an existing Amazon Q Business application.

Request Syntax

GET /applications/applicationId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"applicationArn": "string",
"applicationId": "string",
"attachmentsConfiguration": {
"attachmentsControlMode": "string"
},
"createdAt": number,
"description": "string",

GetApplication API Version 2023-11-27 110

Amazon Q Business API Reference

"displayName": "string",
"encryptionConfiguration": {
"kmsKeyId": "string"
},
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"identityCenterApplicationArn": "string",
"personalizationConfiguration": {
"personalizationControlMode": "string"
},
"qAppsConfiguration": {
"qAppsControlMode": "string"
},
"roleArn": "string",
"status": "string",
"updatedAt": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

applicationArn

The Amazon Resource Name (ARN) of the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
applicationId

The identifier of the Amazon Q Business application.

Type: String

Length Constraints: Fixed length of 36.

GetApplication API Version 2023-11-27 111

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
attachmentsConfiguration

Settings for whether end users can upload files directly during chat.

Type: AppliedAttachmentsConfiguration object

createdAt

The Unix timestamp when the Amazon Q Business application was last updated.

Type: Timestamp
description

A description for the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$
displayName

The name of the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$
encryptionConfiguration

The identifier of the AWS AWS KMS key that is used to encrypt your data. Amazon Q Business
doesn't support asymmetric keys.

Type: EncryptionConfiguration object

error

If the Status field is set to ERROR, the ErrorMessage field contains a description of the error
that caused the synchronization to fail.

Type: ErrorDetail object

GetApplication API Version 2023-11-27 112

Amazon Q Business API Reference

identityCenterApplicationArn

The Amazon Resource Name (ARN) of the AWS IAM Identity Center instance attached to your
Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 10. Maximum length of 1224.

Pattern: ^arn:(aws|aws-us-gov|aws-cn|aws-iso|aws-iso-b):sso::
\d{12}:application/(sso)?ins-[a-zA-Z0-9-.]{16}/apl-[a-zA-Z0-9]{16}$
personalizationConfiguration

Configuration information about chat response personalization. For more information, see
Personalizing chat responses.

Type: PersonalizationConfiguration object

qAppsConfiguration

Settings for whether end users can create and use Amazon Q Apps in the web experience.

Type: QAppsConfiguration object

roleArn

The Amazon Resource Name (ARN) of the IAM with permissions to access your CloudWatch logs
and metrics.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
status

The status of the Amazon Q Business application.

Type: String

Valid Values: CREATING | ACTIVE | DELETING | FAILED | UPDATING

GetApplication API Version 2023-11-27 113

Amazon Q Business API Reference

updatedAt

The Unix timestamp when the Amazon Q Business application was last updated.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

GetApplication API Version 2023-11-27 114

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetApplication API Version 2023-11-27 115

Amazon Q Business API Reference

GetChatControlsConfiguration
Service: QBusiness

Gets information about an chat controls configured for an existing Amazon Q Business application.

Request Syntax

GET /applications/applicationId/chatcontrols?maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application for which the chat controls are configured.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of configured chat controls to return.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of Amazon Q Business chat controls configured.

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

GetChatControlsConfiguration API Version 2023-11-27 116

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"blockedPhrases": {
"blockedPhrases": [ "string" ],
"systemMessageOverride": "string"
},
"creatorModeConfiguration": {
"creatorModeControl": "string"
},
"nextToken": "string",
"responseScope": "string",
"topicConfigurations": [
{
"description": "string",
"exampleChatMessages": [ "string" ],
"name": "string",
"rules": [
{
"excludedUsersAndGroups": {
"userGroups": [ "string" ],
"userIds": [ "string" ]
},
"includedUsersAndGroups": {
"userGroups": [ "string" ],
"userIds": [ "string" ]
},
"ruleConfiguration": { ... },
"ruleType": "string"
}
]
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

GetChatControlsConfiguration API Version 2023-11-27 117

Amazon Q Business API Reference

blockedPhrases

The phrases blocked from chat by your chat control configuration.

Type: BlockedPhrasesConfiguration object

creatorModeConfiguration

The configuration details for CREATOR_MODE.

Type: AppliedCreatorModeConfiguration object

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of Amazon Q Business chat controls configured.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

responseScope

The response scope configured for a Amazon Q Business application. This determines whether
your application uses its retrieval augmented generation (RAG) system to generate answers only
from your enterprise data, or also uses the large language models (LLM) knowledge to respons
to end user questions in chat.

Type: String

Valid Values: ENTERPRISE_CONTENT_ONLY | EXTENDED_KNOWLEDGE_ENABLED

topicConfigurations

The topic specific controls configured for a Amazon Q Business application.

Type: Array of TopicConfiguration objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Errors

For information about the errors that are common to all actions, see Common Errors.

GetChatControlsConfiguration API Version 2023-11-27 118

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

GetChatControlsConfiguration API Version 2023-11-27 119

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetChatControlsConfiguration API Version 2023-11-27 120

Amazon Q Business API Reference

GetDataSource
Service: QBusiness

Gets information about an existing Amazon Q Business data source connector.

Request Syntax

GET /applications/applicationId/indices/indexId/datasources/dataSourceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identfier of the index used with the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

GetDataSource API Version 2023-11-27 121

Amazon Q Business API Reference

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"applicationId": "string",
"configuration": JSON value,
"createdAt": number,
"dataSourceArn": "string",
"dataSourceId": "string",
"description": "string",
"displayName": "string",
"documentEnrichmentConfiguration": {
"inlineConfigurations": [
{
"condition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"documentContentOperator": "string",
"target": {
"attributeValueOperator": "string",
"key": "string",
"value": { ... }
}
}
],
"postExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"
},

GetDataSource API Version 2023-11-27 122

Amazon Q Business API Reference

"preExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"
}
},
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"indexId": "string",
"roleArn": "string",
"status": "string",
"syncSchedule": "string",
"type": "string",
"updatedAt": number,
"vpcConfiguration": {
"securityGroupIds": [ "string" ],
"subnetIds": [ "string" ]
}
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

applicationId

The identifier of the Amazon Q Business application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

GetDataSource API Version 2023-11-27 123

Amazon Q Business API Reference

configuration

The details of how the data source connector is configured.

Type: JSON value

createdAt

The Unix timestamp when the data source connector was created.

Type: Timestamp
dataSourceArn

The Amazon Resource Name (ARN) of the data source.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
dataSourceId

The identifier of the data source connector.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
description

The description for the data source connector.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$
displayName

The name for the data source connector.

Type: String

GetDataSource API Version 2023-11-27 124

Amazon Q Business API Reference

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$
documentEnrichmentConfiguration

Provides the configuration information for altering document metadata and content during the
document ingestion process.

For more information, see Custom document enrichment.

Type: DocumentEnrichmentConfiguration object

error

When the Status field value is FAILED, the ErrorMessage field contains a description of the
error that caused the data source connector to fail.

Type: ErrorDetail object

indexId

The identifier of the index linked to the data source connector.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
roleArn

The Amazon Resource Name (ARN) of the role with permission to access the data source and
required resources.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
status

The current status of the data source connector. When the Status field value is FAILED, the
ErrorMessage field contains a description of the error that caused the data source connector
to fail.

GetDataSource API Version 2023-11-27 125

Amazon Q Business API Reference

Type: String

Valid Values: PENDING_CREATION | CREATING | ACTIVE | DELETING | FAILED |

UPDATING
syncSchedule

The schedule for Amazon Q Business to update the index.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 998.

Pattern: ^\P{C}*$
type

The type of the data source connector. For example, S3.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

updatedAt

The Unix timestamp when the data source connector was last updated.

Type: Timestamp
vpcConfiguration

Configuration information for an Amazon VPC (Virtual Private Cloud) to connect to your data
source.

Type: DataSourceVpcConfiguration object

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

GetDataSource API Version 2023-11-27 126

Amazon Q Business API Reference

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3

GetDataSource API Version 2023-11-27 127

Amazon Q Business API Reference

• AWS SDK for Python

• AWS SDK for Ruby V3

GetDataSource API Version 2023-11-27 128

Amazon Q Business API Reference

GetGroup
Service: QBusiness

Describes a group by group name.

Request Syntax

GET /applications/applicationId/indices/indexId/groups/groupName?
dataSourceId=dataSourceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application id the group is attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source the group is attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
groupName

The name of the group.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: Yes
indexId

The identifier of the index the group is attached to.

GetGroup API Version 2023-11-27 129

Amazon Q Business API Reference

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"status": {
"errorDetail": {
"errorCode": "string",
"errorMessage": "string"
},
"lastUpdatedAt": number,
"status": "string"
},
"statusHistory": [
{
"errorDetail": {
"errorCode": "string",
"errorMessage": "string"
},
"lastUpdatedAt": number,
"status": "string"
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

GetGroup API Version 2023-11-27 130

Amazon Q Business API Reference

status

The current status of the group.

Type: GroupStatusDetail object

statusHistory

The status history of the group.

Type: Array of GroupStatusDetail objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

GetGroup API Version 2023-11-27 131

Amazon Q Business API Reference

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetGroup API Version 2023-11-27 132

Amazon Q Business API Reference

GetIndex
Service: QBusiness

Gets information about an existing Amazon Q Business index.

Request Syntax

GET /applications/applicationId/indices/indexId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application connected to the index.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the Amazon Q Business index you want information on.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

GetIndex API Version 2023-11-27 133

Amazon Q Business API Reference

{
"applicationId": "string",
"capacityConfiguration": {
"units": number
},
"createdAt": number,
"description": "string",
"displayName": "string",
"documentAttributeConfigurations": [
{
"name": "string",
"search": "string",
"type": "string"
}
],
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"indexArn": "string",
"indexId": "string",
"indexStatistics": {
"textDocumentStatistics": {
"indexedTextBytes": number,
"indexedTextDocumentCount": number
}
},
"status": "string",
"type": "string",
"updatedAt": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

applicationId

The identifier of the Amazon Q Business application associated with the index.

Type: String

GetIndex API Version 2023-11-27 134

Amazon Q Business API Reference

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
capacityConfiguration

The storage capacity units chosen for your Amazon Q Business index.

Type: IndexCapacityConfiguration object

createdAt

The Unix timestamp when the Amazon Q Business index was created.

Type: Timestamp
description

The description for the Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$
displayName

The name of the Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$
documentAttributeConfigurations

Configuration information for document attributes or metadata. Document metadata are fields
associated with your documents. For example, the company department name associated with
each document. For more information, see Understanding document attributes.

Type: Array of DocumentAttributeConfiguration objects

Array Members: Minimum number of 1 item. Maximum number of 500 items.

GetIndex API Version 2023-11-27 135

Amazon Q Business API Reference

error

When the Status field value is FAILED, the ErrorMessage field contains a message that
explains why.

Type: ErrorDetail object

indexArn

The Amazon Resource Name (ARN) of the Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
indexId

The identifier of the Amazon Q Business index.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
indexStatistics

Provides information about the number of documents indexed.

Type: IndexStatistics object

status

The current status of the index. When the value is ACTIVE, the index is ready for use. If the
Status field value is FAILED, the ErrorMessage field contains a message that explains why.

Type: String

Valid Values: CREATING | ACTIVE | DELETING | FAILED | UPDATING

type

The type of index attached to your Amazon Q Business application.

GetIndex API Version 2023-11-27 136

Amazon Q Business API Reference

Type: String

Valid Values: ENTERPRISE | STARTER

updatedAt

The Unix timestamp when the Amazon Q Business index was last updated.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

GetIndex API Version 2023-11-27 137

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetIndex API Version 2023-11-27 138

Amazon Q Business API Reference

GetPlugin
Service: QBusiness

Gets information about an existing Amazon Q Business plugin.

Request Syntax

GET /applications/applicationId/plugins/pluginId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application which contains the plugin.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
pluginId

The identifier of the plugin.

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

GetPlugin API Version 2023-11-27 139

Amazon Q Business API Reference

Content-type: application/json

{
"applicationId": "string",
"authConfiguration": { ... },
"buildStatus": "string",
"createdAt": number,
"customPluginConfiguration": {
"apiSchema": { ... },
"apiSchemaType": "string",
"description": "string"
},
"displayName": "string",
"pluginArn": "string",
"pluginId": "string",
"serverUrl": "string",
"state": "string",
"type": "string",
"updatedAt": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

applicationId

The identifier of the application which contains the plugin.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
authConfiguration

Authentication configuration information for an Amazon Q Business plugin.

Type: PluginAuthConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

GetPlugin API Version 2023-11-27 140

Amazon Q Business API Reference

buildStatus

The current status of a plugin. A plugin is modified asynchronously.

Type: String

Valid Values: READY | CREATE_IN_PROGRESS | CREATE_FAILED |

UPDATE_IN_PROGRESS | UPDATE_FAILED | DELETE_IN_PROGRESS | DELETE_FAILED
createdAt

The timestamp for when the plugin was created.

Type: Timestamp
customPluginConfiguration

Configuration information required to create a custom plugin.

Type: CustomPluginConfiguration object

displayName

The name of the plugin.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$
pluginArn

The Amazon Resource Name (ARN) of the role with permission to access resources needed to
create the plugin.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
pluginId

The identifier of the plugin.

GetPlugin API Version 2023-11-27 141

Amazon Q Business API Reference

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
serverUrl

The source URL used for plugin configuration.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$
state

The current state of the plugin.

Type: String

Valid Values: ENABLED | DISABLED

type

The type of the plugin.

Type: String

Valid Values: SERVICE_NOW | SALESFORCE | JIRA | ZENDESK | CUSTOM

updatedAt

The timestamp for when the plugin was last updated.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

GetPlugin API Version 2023-11-27 142

Amazon Q Business API Reference

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3

GetPlugin API Version 2023-11-27 143

Amazon Q Business API Reference

• AWS SDK for Python

• AWS SDK for Ruby V3

GetPlugin API Version 2023-11-27 144

Amazon Q Business API Reference

GetRetriever
Service: QBusiness

Gets information about an existing retriever used by an Amazon Q Business application.

Request Syntax

GET /applications/applicationId/retrievers/retrieverId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application using the retriever.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
retrieverId

The identifier of the retriever.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

GetRetriever API Version 2023-11-27 145

Amazon Q Business API Reference

{
"applicationId": "string",
"configuration": { ... },
"createdAt": number,
"displayName": "string",
"retrieverArn": "string",
"retrieverId": "string",
"roleArn": "string",
"status": "string",
"type": "string",
"updatedAt": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

applicationId

The identifier of the Amazon Q Business application using the retriever.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
configuration

Provides information on how the retriever used for your Amazon Q Business application is
configured.

Type: RetrieverConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.
createdAt

The Unix timestamp when the retriever was created.

Type: Timestamp

GetRetriever API Version 2023-11-27 146

Amazon Q Business API Reference

displayName

The name of the retriever.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$
retrieverArn

The Amazon Resource Name (ARN) of the IAM role associated with the retriever.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
retrieverId

The identifier of the retriever.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
roleArn

The Amazon Resource Name (ARN) of the role with the permission to access the retriever and
required resources.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
status

The status of the retriever.

GetRetriever API Version 2023-11-27 147

Amazon Q Business API Reference

Type: String

Valid Values: CREATING | ACTIVE | FAILED

type

The type of the retriever.

Type: String

Valid Values: NATIVE_INDEX | KENDRA_INDEX

updatedAt

The Unix timestamp when the retriever was last updated.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

GetRetriever API Version 2023-11-27 148

Amazon Q Business API Reference

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetRetriever API Version 2023-11-27 149

Amazon Q Business API Reference

GetUser
Service: QBusiness

Describes the universally unique identifier (UUID) associated with a local user in a data source.

Request Syntax

GET /applications/applicationId/users/userId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application connected to the user.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
userId

The user email address attached to the user.

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

GetUser API Version 2023-11-27 150

Amazon Q Business API Reference

"userAliases": [
{
"dataSourceId": "string",
"indexId": "string",
"userId": "string"
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

userAliases

A list of user aliases attached to a user.

Type: Array of UserAlias objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

GetUser API Version 2023-11-27 151

Amazon Q Business API Reference

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetUser API Version 2023-11-27 152

Amazon Q Business API Reference

GetWebExperience
Service: QBusiness

Gets information about an existing Amazon Q Business web experience.

Request Syntax

GET /applications/applicationId/experiences/webExperienceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application linked to the web experience.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
webExperienceId

The identifier of the Amazon Q Business web experience.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

GetWebExperience API Version 2023-11-27 153

Amazon Q Business API Reference

{
"applicationId": "string",
"authenticationConfiguration": { ... },
"createdAt": number,
"defaultEndpoint": "string",
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"roleArn": "string",
"samplePromptsControlMode": "string",
"status": "string",
"subtitle": "string",
"title": "string",
"updatedAt": number,
"webExperienceArn": "string",
"webExperienceId": "string",
"welcomeMessage": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

applicationId

The identifier of the Amazon Q Business application linked to the web experience.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
authenticationConfiguration

This parameter has been deprecated.

The authentication configuration information for your Amazon Q Business web experience.

Type: WebExperienceAuthConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

GetWebExperience API Version 2023-11-27 154

Amazon Q Business API Reference

createdAt

The Unix timestamp when the Amazon Q Business web experience was last created.

Type: Timestamp
defaultEndpoint

The endpoint of your Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$
error

When the Status field value is FAILED, the ErrorMessage field contains a description of the
error that caused the data source connector to fail.

Type: ErrorDetail object

roleArn

The Amazon Resource Name (ARN) of the service role attached to your web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
samplePromptsControlMode

Determines whether sample prompts are enabled in the web experience for an end user.

Type: String

Valid Values: ENABLED | DISABLED

status

The current status of the Amazon Q Business web experience. When the Status field value
is FAILED, the ErrorMessage field contains a description of the error that caused the data
source connector to fail.

GetWebExperience API Version 2023-11-27 155

Amazon Q Business API Reference

Type: String

Valid Values: CREATING | ACTIVE | DELETING | FAILED | PENDING_AUTH_CONFIG

subtitle

The subtitle for your Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: ^\P{C}*$
title

The title for your Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: ^\P{C}*$
updatedAt

The Unix timestamp when the Amazon Q Business web experience was last updated.

Type: Timestamp
webExperienceArn

The Amazon Resource Name (ARN) of the role with the permission to access the Amazon Q
Business web experience and required resources.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$
webExperienceId

The identifier of the Amazon Q Business web experience.

GetWebExperience API Version 2023-11-27 156

Amazon Q Business API Reference

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$
welcomeMessage

The customized welcome message for end users of an Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 300.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

GetWebExperience API Version 2023-11-27 157

Amazon Q Business API Reference

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetWebExperience API Version 2023-11-27 158

Amazon Q Business API Reference

ListApplications
Service: QBusiness

Lists Amazon Q Business applications.

Request Syntax

GET /applications?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults

The maximum number of Amazon Q Business applications to return.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of Amazon Q Business applications.

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"applications": [
{
"applicationId": "string",
"createdAt": number,
"displayName": "string",

ListApplications API Version 2023-11-27 159

Amazon Q Business API Reference

"status": "string",
"updatedAt": number
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

applications

An array of summary information on the configuration of one or more Amazon Q Business

applications.

Type: Array of Application objects

nextToken

If the response is truncated, Amazon Q Business returns this token. You can use this token in a
subsequent request to retrieve the next set of applications.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

ListApplications API Version 2023-11-27 160

Amazon Q Business API Reference

HTTP Status Code: 500

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListApplications API Version 2023-11-27 161

Amazon Q Business API Reference

ListConversations
Service: QBusiness

Lists one or more Amazon Q Business conversations.

Request Syntax

GET /applications/applicationId/conversations?
maxResults=maxResults&nextToken=nextToken&userId=userId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of Amazon Q Business conversations to return.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of Amazon Q Business conversations.

Length Constraints: Minimum length of 1. Maximum length of 800.

userId

The identifier of the user involved in the Amazon Q Business web experience conversation.

Length Constraints: Minimum length of 1. Maximum length of 1024.

ListConversations API Version 2023-11-27 162

Amazon Q Business API Reference

Pattern: ^\P{C}*$

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"conversations": [
{
"conversationId": "string",
"startTime": number,
"title": "string"
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

conversations

An array of summary information on the configuration of one or more Amazon Q Business web
experiences.

Type: Array of Conversation objects

nextToken

If the response is truncated, Amazon Q Business returns this token, which you can use in a later
request to list the next set of messages.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

ListConversations API Version 2023-11-27 163

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

LicenseNotFoundException

You don't have permissions to perform the action because your license is inactive. Ask your
admin to activate your license and try again after your licence is active.

HTTP Status Code: 400

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

ListConversations API Version 2023-11-27 164

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListConversations API Version 2023-11-27 165

Amazon Q Business API Reference

ListDataSources
Service: QBusiness

Lists the Amazon Q Business data source connectors that you have created.

Request Syntax

GET /applications/applicationId/indices/indexId/datasources?
maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application linked to the data source connectors.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the index used with one or more data source connectors.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of data source connectors to return.

Valid Range: Minimum value of 1. Maximum value of 10.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of Amazon Q Business data source connectors.

ListDataSources API Version 2023-11-27 166

Amazon Q Business API Reference

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"dataSources": [
{
"createdAt": number,
"dataSourceId": "string",
"displayName": "string",
"status": "string",
"type": "string",
"updatedAt": number
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

dataSources

An array of summary information for one or more data source connector.

Type: Array of DataSource objects

nextToken

If the response is truncated, Amazon Q Business returns this token. You can use this token in a
subsequent request to retrieve the next set of data source connectors.

Type: String

ListDataSources API Version 2023-11-27 167

Amazon Q Business API Reference

Length Constraints: Minimum length of 1. Maximum length of 800.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

ListDataSources API Version 2023-11-27 168

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListDataSources API Version 2023-11-27 169

Amazon Q Business API Reference

ListDataSourceSyncJobs
Service: QBusiness

Get information about an Amazon Q Business data source connector synchronization.

Request Syntax

GET /applications/applicationId/indices/indexId/datasources/dataSourceId/syncjobs?
endTime=endTime&maxResults=maxResults&nextToken=nextToken&startTime=startTime&syncStatus=status
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application connected to the data source.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
endTime

The end time of the data source connector sync.

indexId

The identifier of the index used with the Amazon Q Business data source connector.

Length Constraints: Fixed length of 36.

ListDataSourceSyncJobs API Version 2023-11-27 170

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of synchronization jobs to return in the response.

Valid Range: Minimum value of 1. Maximum value of 10.

nextToken

If the maxResults response was incpmplete because there is more data to retriever, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of responses.

Length Constraints: Minimum length of 1. Maximum length of 800.

startTime

The start time of the data source connector sync.

statusFilter

Only returns synchronization jobs with the Status field equal to the specified status.

Valid Values: FAILED | SUCCEEDED | SYNCING | INCOMPLETE | STOPPING | ABORTED

| SYNCING_INDEXING

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"history": [
{
"dataSourceErrorCode": "string",
"endTime": number,

ListDataSourceSyncJobs API Version 2023-11-27 171

Amazon Q Business API Reference

"error": {
"errorCode": "string",
"errorMessage": "string"
},
"executionId": "string",
"metrics": {
"documentsAdded": "string",
"documentsDeleted": "string",
"documentsFailed": "string",
"documentsModified": "string",
"documentsScanned": "string"
},
"startTime": number,
"status": "string"
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

history

A history of synchronization jobs for the data source connector.

Type: Array of DataSourceSyncJob objects

nextToken

If the response is truncated, Amazon Q Business returns this token. You can use this token in
any subsequent request to retrieve the next set of jobs.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

Errors

For information about the errors that are common to all actions, see Common Errors.

ListDataSourceSyncJobs API Version 2023-11-27 172

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

ListDataSourceSyncJobs API Version 2023-11-27 173

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListDataSourceSyncJobs API Version 2023-11-27 174

Amazon Q Business API Reference

ListDocuments
Service: QBusiness

A list of documents attached to an index.

Request Syntax

GET /applications/applicationId/index/indexId/documents?
dataSourceIds=dataSourceIds&maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application id the documents are attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceIds

The identifier of the data sources the documents are attached to.

Array Members: Fixed number of 1 item.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
indexId

The identifier of the index the documents are attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

ListDocuments API Version 2023-11-27 175

Amazon Q Business API Reference

maxResults

The maximum number of documents to return.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of documents.

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"documentDetailList": [
{
"createdAt": number,
"documentId": "string",
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"status": "string",
"updatedAt": number
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

ListDocuments API Version 2023-11-27 176

Amazon Q Business API Reference

The following data is returned in JSON format by the service.

documentDetailList

A list of document details.

Type: Array of DocumentDetails objects

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of documents.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ListDocuments API Version 2023-11-27 177

Amazon Q Business API Reference

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListDocuments API Version 2023-11-27 178

Amazon Q Business API Reference

ListGroups
Service: QBusiness

Provides a list of groups that are mapped to users.

Request Syntax

GET /applications/applicationId/indices/indexId/groups?
dataSourceId=dataSourceId&maxResults=maxResults&nextToken=nextToken&updatedEarlierThan=updatedE
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application for getting a list of groups mapped to users.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source for getting a list of groups mapped to users.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$
indexId

The identifier of the index for getting a list of groups mapped to users.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

ListGroups API Version 2023-11-27 179

Amazon Q Business API Reference

maxResults

The maximum number of returned groups that are mapped to users.

Valid Range: Minimum value of 1. Maximum value of 10.

nextToken

If the previous response was incomplete (because there is more data to retrieve), Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of groups that are mapped to users.

Length Constraints: Minimum length of 1. Maximum length of 800.

updatedEarlierThan

The timestamp identifier used for the latest PUT or DELETE action for mapping users to their
groups.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"items": [
{
"groupName": "string"
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

ListGroups API Version 2023-11-27 180

Amazon Q Business API Reference

The following data is returned in JSON format by the service.

items

Summary information for list of groups that are mapped to users.

Type: Array of GroupSummary objects

nextToken

If the response is truncated, Amazon Q Business returns this token that you can use in the
subsequent request to retrieve the next set of groups that are mapped to users.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

ListGroups API Version 2023-11-27 181

Amazon Q Business API Reference

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListGroups API Version 2023-11-27 182

Amazon Q Business API Reference

ListIndices
Service: QBusiness

Lists the Amazon Q Business indices you have created.

Request Syntax

GET /applications/applicationId/indices?maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application connected to the index.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of indices to return.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of Amazon Q Business indices.

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

ListIndices API Version 2023-11-27 183

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"indices": [
{
"createdAt": number,
"displayName": "string",
"indexId": "string",
"status": "string",
"updatedAt": number
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

indices

An array of information on the items in one or more indexes.

Type: Array of Index objects

nextToken

If the response is truncated, Amazon Q Business returns this token that you can use in the
subsequent request to retrieve the next set of indexes.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

Errors

For information about the errors that are common to all actions, see Common Errors.

ListIndices API Version 2023-11-27 184

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

ListIndices API Version 2023-11-27 185

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListIndices API Version 2023-11-27 186

Amazon Q Business API Reference

ListMessages
Service: QBusiness

Gets a list of messages associated with an Amazon Q Business web experience.

Request Syntax

GET /applications/applicationId/conversations/conversationId?
maxResults=maxResults&nextToken=nextToken&userId=userId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier for the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
conversationId

The identifier of the Amazon Q Business web experience conversation.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of messages to return.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

If the number of retrievers returned exceeds maxResults, Amazon Q Business returns a next
token as a pagination token to retrieve the next set of messages.

Length Constraints: Minimum length of 1. Maximum length of 800.

ListMessages API Version 2023-11-27 187

Amazon Q Business API Reference

userId

The identifier of the user involved in the Amazon Q Business web experience conversation.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"messages": [
{
"actionExecution": {
"payload": {
"string" : {
"value": JSON value
}
},
"payloadFieldNameSeparator": "string",
"pluginId": "string"
},
"actionReview": {
"payload": {
"string" : {
"allowedFormat": "string",
"allowedValues": [
{
"displayValue": JSON value,
"value": JSON value
}
],
"displayDescription": "string",
"displayName": "string",
"displayOrder": number,
"required": boolean,

ListMessages API Version 2023-11-27 188

Amazon Q Business API Reference

"type": "string",
"value": JSON value
}
},
"payloadFieldNameSeparator": "string",
"pluginId": "string",
"pluginType": "string"
},
"attachments": [
{
"error": {
"errorCode": "string",
"errorMessage": "string"
},
"name": "string",
"status": "string"
}
],
"body": "string",
"messageId": "string",
"sourceAttribution": [
{
"citationNumber": number,
"snippet": "string",
"textMessageSegments": [
{
"beginOffset": number,
"endOffset": number,
"snippetExcerpt": {
"text": "string"
}
}
],
"title": "string",
"updatedAt": number,
"url": "string"
}
],
"time": number,
"type": "string"
}
],
"nextToken": "string"

ListMessages API Version 2023-11-27 189

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

messages

An array of information on one or more messages.

Type: Array of Message objects

nextToken

If the response is truncated, Amazon Q Business returns this token, which you can use in a later
request to list the next set of messages.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

LicenseNotFoundException

You don't have permissions to perform the action because your license is inactive. Ask your
admin to activate your license and try again after your licence is active.

ListMessages API Version 2023-11-27 190

Amazon Q Business API Reference

HTTP Status Code: 400

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListMessages API Version 2023-11-27 191

Amazon Q Business API Reference

ListPlugins
Service: QBusiness

Lists configured Amazon Q Business plugins.

Request Syntax

GET /applications/applicationId/plugins?maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application the plugin is attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of documents to return.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of plugins.

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

ListPlugins API Version 2023-11-27 192

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"plugins": [
{
"buildStatus": "string",
"createdAt": number,
"displayName": "string",
"pluginId": "string",
"serverUrl": "string",
"state": "string",
"type": "string",
"updatedAt": number
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of plugins.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

plugins

Information about a configured plugin.

Type: Array of Plugin objects

ListPlugins API Version 2023-11-27 193

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

ListPlugins API Version 2023-11-27 194

Amazon Q Business API Reference

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListPlugins API Version 2023-11-27 195

Amazon Q Business API Reference

ListRetrievers
Service: QBusiness

Lists the retriever used by an Amazon Q Business application.

Request Syntax

GET /applications/applicationId/retrievers?maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application using the retriever.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of retrievers returned.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken

If the number of retrievers returned exceeds maxResults, Amazon Q Business returns a next
token as a pagination token to retrieve the next set of retrievers.

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

ListRetrievers API Version 2023-11-27 196

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"retrievers": [
{
"applicationId": "string",
"displayName": "string",
"retrieverId": "string",
"status": "string",
"type": "string"
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

nextToken

If the response is truncated, Amazon Q Business returns this token, which you can use in a later
request to list the next set of retrievers.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

retrievers

An array of summary information for one or more retrievers.

Type: Array of Retriever objects

Errors

For information about the errors that are common to all actions, see Common Errors.

ListRetrievers API Version 2023-11-27 197

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

ListRetrievers API Version 2023-11-27 198

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListRetrievers API Version 2023-11-27 199

Amazon Q Business API Reference

ListTagsForResource
Service: QBusiness

Gets a list of tags associated with a specified resource. Amazon Q Business applications and data
sources can have tags associated with them.

Request Syntax

GET /v1/tags/resourceARN HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceARN

The Amazon Resource Name (ARN) of the Amazon Q Business application or data source to get
a list of tags for.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"tags": [
{
"key": "string",
"value": "string"
}
]
}

ListTagsForResource API Version 2023-11-27 200

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

tags

A list of tags associated with the Amazon Q Business application or data source.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ListTagsForResource API Version 2023-11-27 201

Amazon Q Business API Reference

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListTagsForResource API Version 2023-11-27 202

Amazon Q Business API Reference

ListWebExperiences
Service: QBusiness

Lists one or more Amazon Q Business Web Experiences.

Request Syntax

GET /applications/applicationId/experiences?maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application linked to the listed web experiences.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
maxResults

The maximum number of Amazon Q Business Web Experiences to return.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

If the maxResults response was incomplete because there is more data to retrieve, Amazon
Q Business returns a pagination token in the response. You can use this pagination token to
retrieve the next set of Amazon Q Business conversations.

Length Constraints: Minimum length of 1. Maximum length of 800.

Request Body

The request does not have a request body.

ListWebExperiences API Version 2023-11-27 203

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"webExperiences": [
{
"createdAt": number,
"defaultEndpoint": "string",
"status": "string",
"updatedAt": number,
"webExperienceId": "string"
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

nextToken

If the response is truncated, Amazon Q Business returns this token, which you can use in a later
request to list the next set of messages.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 800.

webExperiences

An array of summary information for one or more Amazon Q Business experiences.

Type: Array of WebExperience objects

Errors

For information about the errors that are common to all actions, see Common Errors.

ListWebExperiences API Version 2023-11-27 204

Amazon Q Business API Reference

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

ListWebExperiences API Version 2023-11-27 205

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListWebExperiences API Version 2023-11-27 206

Amazon Q Business API Reference

PutFeedback
Service: QBusiness

Enables your end user to provide feedback on their Amazon Q Business generated chat responses.

Request Syntax

POST /applications/applicationId/conversations/conversationId/messages/messageId/
feedback?userId=userId HTTP/1.1
Content-type: application/json

{
"messageCopiedAt": number,
"messageUsefulness": {
"comment": "string",
"reason": "string",
"submittedAt": number,
"usefulness": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application associated with the feedback.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
conversationId

The identifier of the conversation the feedback is attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

PutFeedback API Version 2023-11-27 207

Amazon Q Business API Reference

Required: Yes
messageId

The identifier of the chat message that the feedback was given for.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
userId

The identifier of the user giving the feedback.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Request Body

The request accepts the following data in JSON format.

messageCopiedAt

The timestamp for when the feedback was recorded.

Type: Timestamp

Required: No
messageUsefulness

The feedback usefulness value given by the user to the chat message.

Type: MessageUsefulnessFeedback object

Required: No

Response Syntax

HTTP/1.1 200

PutFeedback API Version 2023-11-27 208

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

PutFeedback API Version 2023-11-27 209

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

PutFeedback API Version 2023-11-27 210

Amazon Q Business API Reference

PutGroup
Service: QBusiness

Create, or updates, a mapping of users—who have access to a document—to groups.

You can also map sub groups to groups. For example, the group "Company Intellectual Property
Teams" includes sub groups "Research" and "Engineering". These sub groups include their own list
of users or people who work in these teams. Only users who work in research and engineering, and
therefore belong in the intellectual property group, can see top-secret company documents in their
Amazon Q Business chat results.

Request Syntax

PUT /applications/applicationId/indices/indexId/groups HTTP/1.1

Content-type: application/json

{
"dataSourceId": "string",
"groupMembers": {
"memberGroups": [
{
"groupName": "string",
"type": "string"
}
],
"memberUsers": [
{
"type": "string",
"userId": "string"
}
]
},
"groupName": "string",
"type": "string"
}

URI Request Parameters

The request uses the following URI parameters.

PutGroup API Version 2023-11-27 211

Amazon Q Business API Reference

applicationId

The identifier of the application in which the user and group mapping belongs.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the index in which you want to map users to their groups.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

dataSourceId

The identifier of the data source for which you want to map users to their groups. This is useful
if a group is tied to multiple data sources, but you only want the group to access documents
of a certain data source. For example, the groups "Research", "Engineering", and "Sales and
Marketing" are all tied to the company's documents stored in the data sources Confluence
and Salesforce. However, "Sales and Marketing" team only needs access to customer-related
documents stored in Salesforce.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
groupMembers

A list of users or sub groups that belong to a group. This is for generating Amazon Q Business
chat results only from document a user has access to.

PutGroup API Version 2023-11-27 212

Amazon Q Business API Reference

Type: GroupMembers object

Required: Yes
groupName

The list that contains your users or sub groups that belong the same group. For example, the
group "Company" includes the user "CEO" and the sub groups "Research", "Engineering", and
"Sales and Marketing".

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: Yes
type

The type of the group.

Type: String

Valid Values: INDEX | DATASOURCE

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

PutGroup API Version 2023-11-27 213

Amazon Q Business API Reference

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

PutGroup API Version 2023-11-27 214

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

PutGroup API Version 2023-11-27 215

Amazon Q Business API Reference

StartDataSourceSyncJob
Service: QBusiness

Starts a data source connector synchronization job. If a synchronization job is already in progress,
Amazon Q Business returns a ConflictException.

Request Syntax

POST /applications/applicationId/indices/indexId/datasources/dataSourceId/startsync
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of Amazon Q Business application the data source is connected to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the index used with the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

StartDataSourceSyncJob API Version 2023-11-27 216

Amazon Q Business API Reference

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"executionId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

executionId

The identifier for a particular synchronization job.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

StartDataSourceSyncJob API Version 2023-11-27 217

Amazon Q Business API Reference

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

StartDataSourceSyncJob API Version 2023-11-27 218

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

StartDataSourceSyncJob API Version 2023-11-27 219

Amazon Q Business API Reference

StopDataSourceSyncJob
Service: QBusiness

Stops an Amazon Q Business data source connector synchronization job already in progress.

Request Syntax

POST /applications/applicationId/indices/indexId/datasources/dataSourceId/stopsync
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application that the data source is connected to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the index used with the Amazon Q Business data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

StopDataSourceSyncJob API Version 2023-11-27 220

Amazon Q Business API Reference

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

StopDataSourceSyncJob API Version 2023-11-27 221

Amazon Q Business API Reference

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

StopDataSourceSyncJob API Version 2023-11-27 222

Amazon Q Business API Reference

TagResource
Service: QBusiness

Adds the specified tag to the specified Amazon Q Business application or data source resource. If
the tag already exists, the existing value is replaced with the new value.

Request Syntax

POST /v1/tags/resourceARN HTTP/1.1

Content-type: application/json

{
"tags": [
{
"key": "string",
"value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

resourceARN

The Amazon Resource Name (ARN) of the Amazon Q Business application or data source to tag.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes

Request Body

The request accepts the following data in JSON format.

tags

A list of tag keys to add to the Amazon Q Business application or data source. If a tag already
exists, the existing value is replaced with the new value.

Type: Array of Tag objects

TagResource API Version 2023-11-27 223

Amazon Q Business API Reference

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

TagResource API Version 2023-11-27 224

Amazon Q Business API Reference

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

TagResource API Version 2023-11-27 225

Amazon Q Business API Reference

UntagResource
Service: QBusiness

Removes a tag from an Amazon Q Business application or a data source.

Request Syntax

DELETE /v1/tags/resourceARN?tagKeys=tagKeys HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceARN

The Amazon Resource Name (ARN) of the Amazon Q Business application, or data source to
remove the tag from.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes
tagKeys

A list of tag keys to remove from the Amazon Q Business application or data source. If a tag key
does not exist on the resource, it is ignored.

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

UntagResource API Version 2023-11-27 226

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

UntagResource API Version 2023-11-27 227

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UntagResource API Version 2023-11-27 228

Amazon Q Business API Reference

UpdateApplication
Service: QBusiness

Updates an existing Amazon Q Business application.

Request Syntax

PUT /applications/applicationId HTTP/1.1

Content-type: application/json

{
"attachmentsConfiguration": {
"attachmentsControlMode": "string"
},
"description": "string",
"displayName": "string",
"identityCenterInstanceArn": "string",
"personalizationConfiguration": {
"personalizationControlMode": "string"
},
"qAppsConfiguration": {
"qAppsControlMode": "string"
},
"roleArn": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

UpdateApplication API Version 2023-11-27 229

Amazon Q Business API Reference

Request Body

The request accepts the following data in JSON format.

attachmentsConfiguration

An option to allow end users to upload files directly during chat.

Type: AttachmentsConfiguration object

Required: No
description

A description for the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
displayName

A name for the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
identityCenterInstanceArn

The Amazon Resource Name (ARN) of the IAM Identity Center instance you are either creating
for—or connecting to—your Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 10. Maximum length of 1224.

UpdateApplication API Version 2023-11-27 230

Amazon Q Business API Reference

Pattern: ^arn:(aws|aws-us-gov|aws-cn|aws-iso|aws-iso-b):sso:::instance/
(sso)?ins-[a-zA-Z0-9-.]{16}$

Required: No
personalizationConfiguration

Configuration information about chat response personalization. For more information, see
Personalizing chat responses.

Type: PersonalizationConfiguration object

Required: No
qAppsConfiguration

An option to allow end users to create and use Amazon Q Apps in the web experience.

Type: QAppsConfiguration object

Required: No
roleArn

An AWS Identity and Access Management (IAM) role that gives Amazon Q Business permission
to access Amazon CloudWatch logs and metrics.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

UpdateApplication API Version 2023-11-27 231

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

UpdateApplication API Version 2023-11-27 232

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateApplication API Version 2023-11-27 233

Amazon Q Business API Reference

UpdateChatControlsConfiguration
Service: QBusiness

Updates an set of chat controls configured for an existing Amazon Q Business application.

Request Syntax

PATCH /applications/applicationId/chatcontrols HTTP/1.1

Content-type: application/json

{
"blockedPhrasesConfigurationUpdate": {
"blockedPhrasesToCreateOrUpdate": [ "string" ],
"blockedPhrasesToDelete": [ "string" ],
"systemMessageOverride": "string"
},
"clientToken": "string",
"creatorModeConfiguration": {
"creatorModeControl": "string"
},
"responseScope": "string",
"topicConfigurationsToCreateOrUpdate": [
{
"description": "string",
"exampleChatMessages": [ "string" ],
"name": "string",
"rules": [
{
"excludedUsersAndGroups": {
"userGroups": [ "string" ],
"userIds": [ "string" ]
},
"includedUsersAndGroups": {
"userGroups": [ "string" ],
"userIds": [ "string" ]
},
"ruleConfiguration": { ... },
"ruleType": "string"
}
]
}
],
"topicConfigurationsToDelete": [

UpdateChatControlsConfiguration API Version 2023-11-27 234

Amazon Q Business API Reference

{
"description": "string",
"exampleChatMessages": [ "string" ],
"name": "string",
"rules": [
{
"excludedUsersAndGroups": {
"userGroups": [ "string" ],
"userIds": [ "string" ]
},
"includedUsersAndGroups": {
"userGroups": [ "string" ],
"userIds": [ "string" ]
},
"ruleConfiguration": { ... },
"ruleType": "string"
}
]
}
]
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application for which the chat controls are configured.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

blockedPhrasesConfigurationUpdate

The phrases blocked from chat by your chat control configuration.

UpdateChatControlsConfiguration API Version 2023-11-27 235

Amazon Q Business API Reference

Type: BlockedPhrasesConfigurationUpdate object

Required: No
clientToken

A token that you provide to identify the request to update a Amazon Q Business application
chat configuration.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: No
creatorModeConfiguration

The configuration details for CREATOR_MODE.

Type: CreatorModeConfiguration object

Required: No
responseScope

The response scope configured for your application. This determines whether your application
uses its retrieval augmented generation (RAG) system to generate answers only from your
enterprise data, or also uses the large language models (LLM) knowledge to respons to end user
questions in chat.

Type: String

Valid Values: ENTERPRISE_CONTENT_ONLY | EXTENDED_KNOWLEDGE_ENABLED

Required: No
topicConfigurationsToCreateOrUpdate

The configured topic specific chat controls you want to update.

Type: Array of TopicConfiguration objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: No

UpdateChatControlsConfiguration API Version 2023-11-27 236

Amazon Q Business API Reference

topicConfigurationsToDelete

The configured topic specific chat controls you want to delete.

Type: Array of TopicConfiguration objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

UpdateChatControlsConfiguration API Version 2023-11-27 237

Amazon Q Business API Reference

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateChatControlsConfiguration API Version 2023-11-27 238

Amazon Q Business API Reference

UpdateChatControlsConfiguration API Version 2023-11-27 239

Amazon Q Business API Reference

UpdateDataSource
Service: QBusiness

Updates an existing Amazon Q Business data source connector.

Request Syntax

PUT /applications/applicationId/indices/indexId/datasources/dataSourceId HTTP/1.1

Content-type: application/json

{
"configuration": JSON value,
"description": "string",
"displayName": "string",
"documentEnrichmentConfiguration": {
"inlineConfigurations": [
{
"condition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"documentContentOperator": "string",
"target": {
"attributeValueOperator": "string",
"key": "string",
"value": { ... }
}
}
],
"postExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",
"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"
},
"preExtractionHookConfiguration": {
"invocationCondition": {
"key": "string",

UpdateDataSource API Version 2023-11-27 240

Amazon Q Business API Reference

"operator": "string",
"value": { ... }
},
"lambdaArn": "string",
"roleArn": "string",
"s3BucketName": "string"
}
},
"roleArn": "string",
"syncSchedule": "string",
"vpcConfiguration": {
"securityGroupIds": [ "string" ],
"subnetIds": [ "string" ]
}
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application the data source is attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
dataSourceId

The identifier of the data source connector.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the index attached to the data source connector.

Length Constraints: Fixed length of 36.

UpdateDataSource API Version 2023-11-27 241

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

configuration

Provides the configuration information for an Amazon Q Business data source.

Type: JSON value

Required: No
description

The description of the data source connector.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
displayName

A name of the data source connector.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
documentEnrichmentConfiguration

Provides the configuration information for altering document metadata and content during the
document ingestion process.

UpdateDataSource API Version 2023-11-27 242

Amazon Q Business API Reference

For more information, see Custom document enrichment.

Type: DocumentEnrichmentConfiguration object

Required: No
roleArn

The Amazon Resource Name (ARN) of an IAM role with permission to access the data source and
required resources.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No
syncSchedule

The chosen update frequency for your data source.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 998.

Pattern: ^\P{C}*$

Required: No
vpcConfiguration

Provides configuration information needed to connect to an Amazon VPC (Virtual Private

Cloud).

Type: DataSourceVpcConfiguration object

Required: No

Response Syntax

HTTP/1.1 200

UpdateDataSource API Version 2023-11-27 243

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

UpdateDataSource API Version 2023-11-27 244

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateDataSource API Version 2023-11-27 245

Amazon Q Business API Reference

UpdateIndex
Service: QBusiness

Updates an Amazon Q Business index.

Request Syntax

PUT /applications/applicationId/indices/indexId HTTP/1.1

Content-type: application/json

{
"capacityConfiguration": {
"units": number
},
"description": "string",
"displayName": "string",
"documentAttributeConfigurations": [
{
"name": "string",
"search": "string",
"type": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application connected to the index.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
indexId

The identifier of the Amazon Q Business index.

UpdateIndex API Version 2023-11-27 246

Amazon Q Business API Reference

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

capacityConfiguration

The storage capacity units you want to provision for your Amazon Q Business index. You can
add and remove capacity to fit your usage needs.

Type: IndexCapacityConfiguration object

Required: No
description

The description of the Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
displayName

The name of the Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No

UpdateIndex API Version 2023-11-27 247

Amazon Q Business API Reference

documentAttributeConfigurations

Configuration information for document metadata or fields. Document metadata are fields
or attributes associated with your documents. For example, the company department name
associated with each document. For more information, see Understanding document attributes.

Type: Array of DocumentAttributeConfiguration objects

Array Members: Minimum number of 1 item. Maximum number of 500 items.

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

UpdateIndex API Version 2023-11-27 248

Amazon Q Business API Reference

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python

UpdateIndex API Version 2023-11-27 249

Amazon Q Business API Reference

• AWS SDK for Ruby V3

UpdateIndex API Version 2023-11-27 250

Amazon Q Business API Reference

UpdatePlugin
Service: QBusiness

Updates an Amazon Q Business plugin.

Request Syntax

PUT /applications/applicationId/plugins/pluginId HTTP/1.1

Content-type: application/json

{
"authConfiguration": { ... },
"customPluginConfiguration": {
"apiSchema": { ... },
"apiSchemaType": "string",
"description": "string"
},
"displayName": "string",
"serverUrl": "string",
"state": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application the plugin is attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
pluginId

The identifier of the plugin.

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

UpdatePlugin API Version 2023-11-27 251

Amazon Q Business API Reference

Required: Yes

Request Body

The request accepts the following data in JSON format.

authConfiguration

The authentication configuration the plugin is using.

Type: PluginAuthConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No
customPluginConfiguration

The configuration for a custom plugin.

Type: CustomPluginConfiguration object

Required: No
displayName

The name of the plugin.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
serverUrl

The source URL used for plugin configuration.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$

UpdatePlugin API Version 2023-11-27 252

Amazon Q Business API Reference

Required: No
state

The status of the plugin.

Type: String

Valid Values: ENABLED | DISABLED

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

UpdatePlugin API Version 2023-11-27 253

Amazon Q Business API Reference

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python

UpdatePlugin API Version 2023-11-27 254

Amazon Q Business API Reference

• AWS SDK for Ruby V3

UpdatePlugin API Version 2023-11-27 255

Amazon Q Business API Reference

UpdateRetriever
Service: QBusiness

Updates the retriever used for your Amazon Q Business application.

Request Syntax

PUT /applications/applicationId/retrievers/retrieverId HTTP/1.1

Content-type: application/json

{
"configuration": { ... },
"displayName": "string",
"roleArn": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of your Amazon Q Business application.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
retrieverId

The identifier of your retriever.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

UpdateRetriever API Version 2023-11-27 256

Amazon Q Business API Reference

configuration

Provides information on how the retriever used for your Amazon Q Business application is
configured.

Type: RetrieverConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No
displayName

The name of your retriever.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
roleArn

The Amazon Resource Name (ARN) of an IAM role with permission to access the retriever and
required resources.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

UpdateRetriever API Version 2023-11-27 257

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

UpdateRetriever API Version 2023-11-27 258

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateRetriever API Version 2023-11-27 259

Amazon Q Business API Reference

UpdateUser
Service: QBusiness

Updates a information associated with a user id.

Request Syntax

PUT /applications/applicationId/users/userId HTTP/1.1

Content-type: application/json

{
"userAliasesToDelete": [
{
"dataSourceId": "string",
"indexId": "string",
"userId": "string"
}
],
"userAliasesToUpdate": [
{
"dataSourceId": "string",
"indexId": "string",
"userId": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the application the user is attached to.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
userId

The email id attached to the user.

UpdateUser API Version 2023-11-27 260

Amazon Q Business API Reference

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Request Body

The request accepts the following data in JSON format.

userAliasesToDelete

The user aliases attached to the user id that are to be deleted.

Type: Array of UserAlias objects

Required: No
userAliasesToUpdate

The user aliases attached to the user id that are to be updated.

Type: Array of UserAlias objects

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"userAliasesAdded": [
{
"dataSourceId": "string",
"indexId": "string",
"userId": "string"
}
],
"userAliasesDeleted": [
{
"dataSourceId": "string",
"indexId": "string",
"userId": "string"

UpdateUser API Version 2023-11-27 261

Amazon Q Business API Reference

}
],
"userAliasesUpdated": [
{
"dataSourceId": "string",
"indexId": "string",
"userId": "string"
}
]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

userAliasesAdded

The user aliases that have been to be added to a user id.

Type: Array of UserAlias objects

userAliasesDeleted

The user aliases that have been deleted from a user id.

Type: Array of UserAlias objects

userAliasesUpdated

The user aliases attached to a user id that have been updated.

Type: Array of UserAlias objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

UpdateUser API Version 2023-11-27 262

Amazon Q Business API Reference

HTTP Status Code: 403

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ServiceQuotaExceededException

You have exceeded the set limits for your Amazon Q Business service.

HTTP Status Code: 402

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

UpdateUser API Version 2023-11-27 263

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateUser API Version 2023-11-27 264

Amazon Q Business API Reference

UpdateWebExperience
Service: QBusiness

Updates an Amazon Q Business web experience.

Request Syntax

PUT /applications/applicationId/experiences/webExperienceId HTTP/1.1

Content-type: application/json

{
"authenticationConfiguration": { ... },
"roleArn": "string",
"samplePromptsControlMode": "string",
"subtitle": "string",
"title": "string",
"welcomeMessage": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId

The identifier of the Amazon Q Business application attached to the web experience.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
webExperienceId

The identifier of the Amazon Q Business web experience.

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$

Required: Yes

UpdateWebExperience API Version 2023-11-27 265

Amazon Q Business API Reference

Request Body

The request accepts the following data in JSON format.

authenticationConfiguration

This parameter has been deprecated.

The authentication configuration of the Amazon Q Business web experience.

Type: WebExperienceAuthConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No
roleArn

The Amazon Resource Name (ARN) of the role with permission to access the Amazon Q Business
web experience and required resources.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No
samplePromptsControlMode

Determines whether sample prompts are enabled in the web experience for an end user.

Type: String

Valid Values: ENABLED | DISABLED

Required: No
subtitle

The subtitle of the Amazon Q Business web experience.

Type: String

UpdateWebExperience API Version 2023-11-27 266

Amazon Q Business API Reference

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: ^\P{C}*$

Required: No
title

The title of the Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: ^\P{C}*$

Required: No
welcomeMessage

A customized welcome message for an end user in an Amazon Q Business web experience.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 300.

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have access to perform this action. Make sure you have the required permission
policies and user accounts and try again.

UpdateWebExperience API Version 2023-11-27 267

Amazon Q Business API Reference

HTTP Status Code: 403

ConflictException

You are trying to perform an action that conflicts with the current status of your resource. Fix
any inconsistences with your resources and try again.

HTTP Status Code: 409

InternalServerException

An issue occurred with the internal server used for your Amazon Q Business service. Wait some
minutes and try again, or contact Support for help.

HTTP Status Code: 500

ResourceNotFoundException

The resource you want to use doesn’t exist. Make sure you have provided the correct resource
and try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to throttling. Reduce the number of requests and try again.

HTTP Status Code: 429

ValidationException

The input doesn't meet the constraints set by the Amazon Q Business service. Provide the
correct input and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

UpdateWebExperience API Version 2023-11-27 268

Amazon Q Business API Reference

• AWS SDK for Go v2

• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

QApps
The following actions are supported by QApps:

• AssociateLibraryItemReview
• AssociateQAppWithUser
• CreateLibraryItem
• CreateQApp
• DeleteLibraryItem
• DeleteQApp
• DisassociateLibraryItemReview
• DisassociateQAppFromUser
• GetLibraryItem
• GetQApp
• GetQAppSession
• ImportDocument
• ListLibraryItems
• ListQApps
• ListTagsForResource
• PredictQApp
• StartQAppSession
• StopQAppSession
• TagResource
• UntagResource

QApps API Version 2023-11-27 269

Amazon Q Business API Reference

• UpdateLibraryItem
• UpdateQApp
• UpdateQAppSession

QApps API Version 2023-11-27 270

Amazon Q Business API Reference

AssociateLibraryItemReview
Service: QApps

Associates a rating or review for a library item with the user submitting the request. This
increments the rating count for the specified library item.

Request Syntax

POST /catalog.associateItemRating HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"libraryItemId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier for the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

libraryItemId

The unique identifier of the library item to associate the review with.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

AssociateLibraryItemReview API Version 2023-11-27 271

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

AssociateLibraryItemReview API Version 2023-11-27 272

Amazon Q Business API Reference

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AssociateLibraryItemReview API Version 2023-11-27 273

Amazon Q Business API Reference

AssociateQAppWithUser
Service: QApps

This operation creates a link between the user's identity calling the operation and a specific Q App.
This is useful to mark the Q App as a favorite for the user if the user doesn't own the Amazon Q
App so they can still run it and see it in their inventory of Q Apps.

Request Syntax

POST /apps.install HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

appId

The ID of the Amazon Q App to associate with the user.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

AssociateQAppWithUser API Version 2023-11-27 274

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

AssociateQAppWithUser API Version 2023-11-27 275

Amazon Q Business API Reference

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AssociateQAppWithUser API Version 2023-11-27 276

Amazon Q Business API Reference

CreateLibraryItem
Service: QApps

Creates a new library item for an Amazon Q App, allowing it to be discovered and used by other
allowed users.

Request Syntax

POST /catalog.createItem HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appId": "string",
"appVersion": number,
"categories": [ "string" ]
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

appId

The unique identifier of the Amazon Q App to publish to the library.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

CreateLibraryItem API Version 2023-11-27 277

Amazon Q Business API Reference

appVersion

The version of the Amazon Q App to publish to the library.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

Required: Yes
categories

The categories to associate with the library item for easier discovery.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 3 items.

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"createdAt": "string",
"createdBy": "string",
"libraryItemId": "string",
"ratingCount": number,
"status": "string",
"updatedAt": "string",
"updatedBy": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

CreateLibraryItem API Version 2023-11-27 278

Amazon Q Business API Reference

createdAt

The date and time the library item was created.

Type: Timestamp
createdBy

The user who created the library item.

Type: String
libraryItemId

The unique identifier of the new library item.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
ratingCount

The number of ratings the library item has received from users.

Type: Integer
status

The status of the new library item, such as "Published".

Type: String
updatedAt

The date and time the library item was last updated.

Type: Timestamp
updatedBy

The user who last updated the library item.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

CreateLibraryItem API Version 2023-11-27 279

Amazon Q Business API Reference

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

CreateLibraryItem API Version 2023-11-27 280

Amazon Q Business API Reference

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

CreateLibraryItem API Version 2023-11-27 281

Amazon Q Business API Reference

CreateQApp
Service: QApps

Creates a new Amazon Q App based on the provided definition. The Q App definition specifies the
cards and flow of the Q App. This operation also calculates the dependencies between the cards by
inspecting the references in the prompts.

Request Syntax

POST /apps.create HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appDefinition": {
"cards": [
{ ... }
],
"initialPrompt": "string"
},
"description": "string",
"tags": {
"string" : "string"
},
"title": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

CreateQApp API Version 2023-11-27 282

Amazon Q Business API Reference

appDefinition

The definition of the new Q App, specifying the cards and flow.

Type: AppDefinitionInput object

Required: Yes
description

The description of the new Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Required: No
tags

Optional tags to associate with the new Q App.

Type: String to string map

Required: No
title

The title of the new Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"appArn": "string",
"appId": "string",

CreateQApp API Version 2023-11-27 283

Amazon Q Business API Reference

"appVersion": number,
"createdAt": "string",
"createdBy": "string",
"description": "string",
"initialPrompt": "string",
"requiredCapabilities": [ "string" ],
"status": "string",
"title": "string",
"updatedAt": "string",
"updatedBy": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

appArn

The Amazon Resource Name (ARN) of the new Q App.

Type: String
appId

The unique identifier of the new Q App.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
appVersion

The version of the new Q App.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

createdAt

The date and time the Q App was created.

Type: Timestamp

CreateQApp API Version 2023-11-27 284

Amazon Q Business API Reference

createdBy

The user who created the Q App.

Type: String
description

The description of the new Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

initialPrompt

The initial prompt displayed when the Q App is started.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 10000.

requiredCapabilities

The capabilities required to run the Q App, such as file upload or third-party integrations.

Type: Array of strings

Valid Values: FileUpload | CreatorMode | RetrievalMode | PluginMode

status

The status of the new Q App, such as "Created".

Type: String

Valid Values: PUBLISHED | DRAFT | DELETED

title

The title of the new Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

CreateQApp API Version 2023-11-27 285

Amazon Q Business API Reference

updatedAt

The date and time the Q App was last updated.

Type: Timestamp
updatedBy

The user who last updated the Q App.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

ConflictException

The requested operation could not be completed due to a conflict with the current state of the
resource.

HTTP Status Code: 409

ContentTooLargeException

The requested operation could not be completed because the content exceeds the maximum
allowed size.

HTTP Status Code: 413

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

CreateQApp API Version 2023-11-27 286

Amazon Q Business API Reference

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

CreateQApp API Version 2023-11-27 287

Amazon Q Business API Reference

DeleteLibraryItem
Service: QApps

Deletes a library item for an Amazon Q App, removing it from the library so it can no longer be
discovered or used by other users.

Request Syntax

POST /catalog.deleteItem HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"libraryItemId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

libraryItemId

The unique identifier of the library item to delete.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

DeleteLibraryItem API Version 2023-11-27 288

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

DeleteLibraryItem API Version 2023-11-27 289

Amazon Q Business API Reference

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteLibraryItem API Version 2023-11-27 290

Amazon Q Business API Reference

DeleteQApp
Service: QApps

Deletes an Amazon Q App owned by the user. If the Q App was previously published to the library,
it is also removed from the library.

Request Syntax

POST /apps.delete HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

appId

The unique identifier of the Q App to delete.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

DeleteQApp API Version 2023-11-27 291

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

DeleteQApp API Version 2023-11-27 292

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DeleteQApp API Version 2023-11-27 293

Amazon Q Business API Reference

DisassociateLibraryItemReview
Service: QApps

Removes a rating or review previously submitted by the user for a library item.

Request Syntax

POST /catalog.disassociateItemRating HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"libraryItemId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

libraryItemId

The unique identifier of the library item to remove the review from.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

DisassociateLibraryItemReview API Version 2023-11-27 294

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

DisassociateLibraryItemReview API Version 2023-11-27 295

Amazon Q Business API Reference

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DisassociateLibraryItemReview API Version 2023-11-27 296

Amazon Q Business API Reference

DisassociateQAppFromUser
Service: QApps

Disassociates a Q App from a user removing the user's access to run the Q App.

Request Syntax

POST /apps.uninstall HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

appId

The unique identifier of the Q App to disassociate from the user.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

DisassociateQAppFromUser API Version 2023-11-27 297

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

DisassociateQAppFromUser API Version 2023-11-27 298

Amazon Q Business API Reference

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

DisassociateQAppFromUser API Version 2023-11-27 299

Amazon Q Business API Reference

GetLibraryItem
Service: QApps

Retrieves details about a library item for an Amazon Q App, including its metadata, categories,
ratings, and usage statistics.

Request Syntax

GET /catalog.getItem?appId=appId&libraryItemId=libraryItemId HTTP/1.1

instance-id: instanceId

URI Request Parameters

The request uses the following URI parameters.

appId

The unique identifier of the Amazon Q App associated with the library item.

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes
libraryItemId

The unique identifier of the library item to retrieve.

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

GetLibraryItem API Version 2023-11-27 300

Amazon Q Business API Reference

Content-type: application/json

{
"appId": "string",
"appVersion": number,
"categories": [
{
"id": "string",
"title": "string"
}
],
"createdAt": "string",
"createdBy": "string",
"isRatedByUser": boolean,
"libraryItemId": "string",
"ratingCount": number,
"status": "string",
"updatedAt": "string",
"updatedBy": "string",
"userCount": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

appId

The unique identifier of the Q App associated with the library item.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
appVersion

The version of the Q App associated with the library item.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

GetLibraryItem API Version 2023-11-27 301

Amazon Q Business API Reference

categories

The categories associated with the library item for discovery.

Type: Array of Category objects

Array Members: Minimum number of 0 items. Maximum number of 3 items.

createdAt

The date and time the library item was created.

Type: Timestamp
createdBy

The user who created the library item.

Type: String
isRatedByUser

Whether the current user has rated the library item.

Type: Boolean
libraryItemId

The unique identifier of the library item.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
ratingCount

The number of ratings the library item has received from users.

Type: Integer
status

The status of the library item, such as "Published".

Type: String
updatedAt

The date and time the library item was last updated.

GetLibraryItem API Version 2023-11-27 302

Amazon Q Business API Reference

Type: Timestamp
updatedBy

The user who last updated the library item.

Type: String
userCount

The number of users who have associated the Q App with their account.

Type: Integer

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

GetLibraryItem API Version 2023-11-27 303

Amazon Q Business API Reference

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetLibraryItem API Version 2023-11-27 304

Amazon Q Business API Reference

GetQApp
Service: QApps

Retrieves the full details of an Q App, including its definition specifying the cards and flow.

Request Syntax

GET /apps.get?appId=appId HTTP/1.1

instance-id: instanceId

URI Request Parameters

The request uses the following URI parameters.

appId

The unique identifier of the Q App to retrieve.

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"appArn": "string",
"appDefinition": {
"appDefinitionVersion": "string",
"canEdit": boolean,

GetQApp API Version 2023-11-27 305

Amazon Q Business API Reference

"cards": [
{ ... }
]
},
"appId": "string",
"appVersion": number,
"createdAt": "string",
"createdBy": "string",
"description": "string",
"initialPrompt": "string",
"requiredCapabilities": [ "string" ],
"status": "string",
"title": "string",
"updatedAt": "string",
"updatedBy": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

appArn

The Amazon Resource Name (ARN) of the Q App.

Type: String
appDefinition

The full definition of the Q App, specifying the cards and flow.

Type: AppDefinition object

appId

The unique identifier of the Q App.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
appVersion

The version of the Q App.

GetQApp API Version 2023-11-27 306

Amazon Q Business API Reference

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

createdAt

The date and time the Q App was created.

Type: Timestamp
createdBy

The user who created the Q App.

Type: String
description

The description of the Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

initialPrompt

The initial prompt displayed when the Q App is started.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 10000.

requiredCapabilities

The capabilities required to run the Q App, such as file upload or third-party integrations.

Type: Array of strings

Valid Values: FileUpload | CreatorMode | RetrievalMode | PluginMode

status

The status of the Q App.

Type: String

Valid Values: PUBLISHED | DRAFT | DELETED

GetQApp API Version 2023-11-27 307

Amazon Q Business API Reference

title

The title of the Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

updatedAt

The date and time the Q App was last updated.

Type: Timestamp
updatedBy

The user who last updated the Q App.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

GetQApp API Version 2023-11-27 308

Amazon Q Business API Reference

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetQApp API Version 2023-11-27 309

Amazon Q Business API Reference

GetQAppSession
Service: QApps

Retrieves the current state and results for an active session of an Amazon Q App.

Request Syntax

GET /runtime.getQAppSession?sessionId=sessionId HTTP/1.1

instance-id: instanceId

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes
sessionId

The unique identifier of the Q App session to retrieve.

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"cardStatus": {
"string" : {

GetQAppSession API Version 2023-11-27 310

Amazon Q Business API Reference

"currentState": "string",
"currentValue": "string"
}
},
"sessionArn": "string",
"sessionId": "string",
"status": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

cardStatus

The current status for each card in the Q App session.

Type: String to CardStatus object map

Key Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]

{12}
sessionArn

The Amazon Resource Name (ARN) of the Q App session.

Type: String
sessionId

The unique identifier of the Q App session.

Type: String
status

The current status of the Q App session.

Type: String

Valid Values: IN_PROGRESS | WAITING | COMPLETED

GetQAppSession API Version 2023-11-27 311

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

GetQAppSession API Version 2023-11-27 312

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

GetQAppSession API Version 2023-11-27 313

Amazon Q Business API Reference

ImportDocument
Service: QApps

Uploads a file that can then be used either as a default in a FileUploadCard from Q App
definition or as a file that is used inside a single Q App run. The purpose of the document is
determined by a scope parameter that indicates whether it is at the app definition level or at the
app session level.

Request Syntax

POST /apps.importDocument HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appId": "string",
"cardId": "string",
"fileContentsBase64": "string",
"fileName": "string",
"scope": "string",
"sessionId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

appId

The unique identifier of the Q App the file is associated with.

ImportDocument API Version 2023-11-27 314

Amazon Q Business API Reference

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
cardId

The unique identifier of the card the file is associated with, if applicable.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
fileContentsBase64

The base64-encoded contents of the file to upload.

Type: String

Required: Yes
fileName

The name of the file being uploaded.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
scope

Whether the file is associated with an Q App definition or a specific Q App session.

Type: String

Valid Values: APPLICATION | SESSION

Required: Yes
sessionId

The unique identifier of the Q App session the file is associated with, if applicable.

ImportDocument API Version 2023-11-27 315

Amazon Q Business API Reference

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"fileId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

fileId

The unique identifier assigned to the uploaded file.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

ContentTooLargeException

The requested operation could not be completed because the content exceeds the maximum
allowed size.

ImportDocument API Version 2023-11-27 316

Amazon Q Business API Reference

HTTP Status Code: 413

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

ImportDocument API Version 2023-11-27 317

Amazon Q Business API Reference

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ImportDocument API Version 2023-11-27 318

Amazon Q Business API Reference

ListLibraryItems
Service: QApps

Lists the library items for Amazon Q Apps that are published and available for users in your AWS
account.

Request Syntax

GET /catalog.list?categoryId=categoryId&limit=limit&nextToken=nextToken HTTP/1.1

instance-id: instanceId

URI Request Parameters

The request uses the following URI parameters.

categoryId

Optional category to filter the library items by.

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes
limit

The maximum number of library items to return in the response.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

The token to request the next page of results.

Length Constraints: Minimum length of 0. Maximum length of 300.

Request Body

The request does not have a request body.

ListLibraryItems API Version 2023-11-27 319

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"libraryItems": [
{
"appId": "string",
"appVersion": number,
"categories": [
{
"id": "string",
"title": "string"
}
],
"createdAt": "string",
"createdBy": "string",
"isRatedByUser": boolean,
"libraryItemId": "string",
"ratingCount": number,
"status": "string",
"updatedAt": "string",
"updatedBy": "string",
"userCount": number
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

libraryItems

The list of library items meeting the request criteria.

Type: Array of LibraryItemMember objects

ListLibraryItems API Version 2023-11-27 320

Amazon Q Business API Reference

nextToken

The token to use to request the next page of results.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

ListLibraryItems API Version 2023-11-27 321

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListLibraryItems API Version 2023-11-27 322

Amazon Q Business API Reference

ListQApps
Service: QApps

Lists the Amazon Q Apps owned by or associated with the user either because they created it or
because they used it from the library in the past. The user identity is extracted from the credentials
used to invoke this operation..

Request Syntax

GET /apps.list?limit=limit&nextToken=nextToken HTTP/1.1

instance-id: instanceId

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes
limit

The maximum number of Q Apps to return in the response.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken

The token to request the next page of results.

Length Constraints: Minimum length of 0. Maximum length of 300.

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

ListQApps API Version 2023-11-27 323

Amazon Q Business API Reference

{
"apps": [
{
"appArn": "string",
"appId": "string",
"canEdit": boolean,
"createdAt": "string",
"description": "string",
"status": "string",
"title": "string"
}
],
"nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

apps

The list of Amazon Q Apps meeting the request criteria.

Type: Array of UserAppItem objects

nextToken

The token to use to request the next page of results.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

ListQApps API Version 2023-11-27 324

Amazon Q Business API Reference

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListQApps API Version 2023-11-27 325

Amazon Q Business API Reference

ListTagsForResource
Service: QApps

Lists the tags associated with an Amazon Q Apps resource.

Request Syntax

GET /tags/resourceARN HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceARN

The Amazon Resource Name (ARN) of the resource whose tags should be listed.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"tags": {
"string" : "string"
}
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

ListTagsForResource API Version 2023-11-27 326

Amazon Q Business API Reference

tags

The list of tags that are assigned to the resource.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

ListTagsForResource API Version 2023-11-27 327

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

ListTagsForResource API Version 2023-11-27 328

Amazon Q Business API Reference

PredictQApp
Service: QApps

Generates an Amazon Q App definition based on either a conversation or a problem statement

provided as input.The resulting app definition can be used to call CreateQApp. This API doesn't
create Amazon Q Apps directly.

Request Syntax

POST /apps.predictQApp HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"options": { ... }
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

options

The input to generate the Q App definition from, either a conversation or problem statement.

Type: PredictQAppInputOptions object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No

PredictQApp API Version 2023-11-27 329

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"app": {
"appDefinition": {
"cards": [
{ ... }
],
"initialPrompt": "string"
},
"description": "string",
"title": "string"
},
"problemStatement": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

app

The generated Q App definition.

Type: PredictAppDefinition object

problemStatement

The problem statement extracted from the input conversation, if provided.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

PredictQApp API Version 2023-11-27 330

Amazon Q Business API Reference

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

PredictQApp API Version 2023-11-27 331

Amazon Q Business API Reference

PredictQApp API Version 2023-11-27 332

Amazon Q Business API Reference

StartQAppSession
Service: QApps

Starts a new session for an Amazon Q App, allowing inputs to be provided and the app to be run.

Note
Each Q App session will be condensed into a single conversation in the web experience.

Request Syntax

POST /runtime.startQAppSession HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appId": "string",
"appVersion": number,
"initialValues": [
{
"cardId": "string",
"value": "string"
}
],
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

StartQAppSession API Version 2023-11-27 333

Amazon Q Business API Reference

Request Body

The request accepts the following data in JSON format.

appId

The unique identifier of the Q App to start a session for.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
appVersion

The version of the Q App to use for the session.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

Required: Yes
initialValues

Optional initial input values to provide for the Q App session.

Type: Array of CardValue objects

Array Members: Minimum number of 0 items. Maximum number of 20 items.

Required: No
tags

Optional tags to associate with the new Q App session.

Type: String to string map

Required: No

Response Syntax

HTTP/1.1 200

StartQAppSession API Version 2023-11-27 334

Amazon Q Business API Reference

Content-type: application/json

{
"sessionArn": "string",
"sessionId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

sessionArn

The Amazon Resource Name (ARN) of the new Q App session.

Type: String
sessionId

The unique identifier of the new Q App session.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

StartQAppSession API Version 2023-11-27 335

Amazon Q Business API Reference

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python

StartQAppSession API Version 2023-11-27 336

Amazon Q Business API Reference

• AWS SDK for Ruby V3

StartQAppSession API Version 2023-11-27 337

Amazon Q Business API Reference

StopQAppSession
Service: QApps

Stops an active session for an Amazon Q App.This deletes all data related to the session and makes
it invalid for future uses. The results of the session will be persisted as part of the conversation.

Request Syntax

POST /runtime.deleteMiniAppRun HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"sessionId": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

sessionId

The unique identifier of the Q App session to stop.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes

StopQAppSession API Version 2023-11-27 338

Amazon Q Business API Reference

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

StopQAppSession API Version 2023-11-27 339

Amazon Q Business API Reference

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

StopQAppSession API Version 2023-11-27 340

Amazon Q Business API Reference

TagResource
Service: QApps

Associates tags with an Amazon Q Apps resource.

Request Syntax

POST /tags/resourceARN HTTP/1.1

Content-type: application/json

{
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

resourceARN

The Amazon Resource Name (ARN) of the resource to tag.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes

Request Body

The request accepts the following data in JSON format.

tags

The tags to associate with the resource.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 256.

TagResource API Version 2023-11-27 341

Amazon Q Business API Reference

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

ConflictException

The requested operation could not be completed due to a conflict with the current state of the
resource.

HTTP Status Code: 409

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

TagResource API Version 2023-11-27 342

Amazon Q Business API Reference

HTTP Status Code: 429

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

TagResource API Version 2023-11-27 343

Amazon Q Business API Reference

UntagResource
Service: QApps

Disassociates tags from an Amazon Q Apps resource.

Request Syntax

DELETE /tags/resourceARN?tagKeys=tagKeys HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceARN

The Amazon Resource Name (ARN) of the resource to disassociate the tag from.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes
tagKeys

The keys of the tags to disassociate from the resource.

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

UntagResource API Version 2023-11-27 344

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2

UntagResource API Version 2023-11-27 345

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UntagResource API Version 2023-11-27 346

Amazon Q Business API Reference

UpdateLibraryItem
Service: QApps

Updates the metadata and status of a library item for an Amazon Q App.

Request Syntax

POST /catalog.updateItem HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"categories": [ "string" ],
"libraryItemId": "string",
"status": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

categories

The new categories to associate with the library item.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 3 items.

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: No

UpdateLibraryItem API Version 2023-11-27 347

Amazon Q Business API Reference

libraryItemId

The unique identifier of the library item to update.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
status

The new status to set for the library item, such as "Published" or "Hidden".

Type: String

Valid Values: PUBLISHED | DISABLED

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"appId": "string",
"appVersion": number,
"categories": [
{
"id": "string",
"title": "string"
}
],
"createdAt": "string",
"createdBy": "string",
"isRatedByUser": boolean,
"libraryItemId": "string",
"ratingCount": number,
"status": "string",
"updatedAt": "string",
"updatedBy": "string",
"userCount": number

UpdateLibraryItem API Version 2023-11-27 348

Amazon Q Business API Reference

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

appId

The unique identifier of the Q App associated with the library item.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
appVersion

The version of the Q App associated with the library item.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

categories

The categories associated with the updated library item.

Type: Array of Category objects

Array Members: Minimum number of 0 items. Maximum number of 3 items.

createdAt

The date and time the library item was originally created.

Type: Timestamp
createdBy

The user who originally created the library item.

Type: String
isRatedByUser

Whether the current user has rated the library item.

UpdateLibraryItem API Version 2023-11-27 349

Amazon Q Business API Reference

Type: Boolean
libraryItemId

The unique identifier of the updated library item.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
ratingCount

The number of ratings the library item has received.

Type: Integer
status

The new status of the updated library item.

Type: String
updatedAt

The date and time the library item was last updated.

Type: Timestamp
updatedBy

The user who last updated the library item.

Type: String
userCount

The number of users who have the associated Q App.

Type: Integer

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

UpdateLibraryItem API Version 2023-11-27 350

Amazon Q Business API Reference

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2

UpdateLibraryItem API Version 2023-11-27 351

Amazon Q Business API Reference

• AWS SDK for JavaScript V3

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateLibraryItem API Version 2023-11-27 352

Amazon Q Business API Reference

UpdateQApp
Service: QApps

Updates an existing Amazon Q App, allowing modifications to its title, description, and definition.

Request Syntax

POST /apps.update HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"appDefinition": {
"cards": [
{ ... }
],
"initialPrompt": "string"
},
"appId": "string",
"description": "string",
"title": "string"
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

appDefinition

The new definition specifying the cards and flow for the Q App.

Type: AppDefinitionInput object

UpdateQApp API Version 2023-11-27 353

Amazon Q Business API Reference

Required: No
appId

The unique identifier of the Q App to update.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
description

The new description for the Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Required: No
title

The new title for the Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"appArn": "string",
"appId": "string",
"appVersion": number,
"createdAt": "string",
"createdBy": "string",
"description": "string",

UpdateQApp API Version 2023-11-27 354

Amazon Q Business API Reference

"initialPrompt": "string",
"requiredCapabilities": [ "string" ],
"status": "string",
"title": "string",
"updatedAt": "string",
"updatedBy": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

appArn

The Amazon Resource Name (ARN) of the updated Q App.

Type: String
appId

The unique identifier of the updated Q App.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}
appVersion

The new version of the updated Q App.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

createdAt

The date and time the Q App was originally created.

Type: Timestamp
createdBy

The user who originally created the Q App.

UpdateQApp API Version 2023-11-27 355

Amazon Q Business API Reference

Type: String
description

The new description of the updated Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

initialPrompt

The initial prompt for the updated Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 10000.

requiredCapabilities

The capabilities required for the updated Q App.

Type: Array of strings

Valid Values: FileUpload | CreatorMode | RetrievalMode | PluginMode

status

The status of the updated Q App.

Type: String

Valid Values: PUBLISHED | DRAFT | DELETED

title

The new title of the updated Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

updatedAt

The date and time the Q App was last updated.

Type: Timestamp

UpdateQApp API Version 2023-11-27 356

Amazon Q Business API Reference

updatedBy

The user who last updated the Q App.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

ContentTooLargeException

The requested operation could not be completed because the content exceeds the maximum
allowed size.

HTTP Status Code: 413

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

UpdateQApp API Version 2023-11-27 357

Amazon Q Business API Reference

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateQApp API Version 2023-11-27 358

Amazon Q Business API Reference

UpdateQAppSession
Service: QApps

Updates the session for a given Q App sessionId. This is only valid when at least one card of the
session is in the WAITING state. Data for each WAITING card can be provided as input. If inputs are
not provided, the call will be accepted but session will not move forward. Inputs for cards that are
not in the WAITING status will be ignored.

Request Syntax

POST /runtime.updateQAppSession HTTP/1.1

instance-id: instanceId
Content-type: application/json

{
"sessionId": "string",
"values": [
{
"cardId": "string",
"value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

instanceId

The unique identifier of the Amazon Q Business application environment instance.

Required: Yes

Request Body

The request accepts the following data in JSON format.

sessionId

The unique identifier of the Q App session to provide input for.

UpdateQAppSession API Version 2023-11-27 359

Amazon Q Business API Reference

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
values

The input values to provide for the current state of the Q App session.

Type: Array of CardValue objects

Array Members: Minimum number of 0 items. Maximum number of 20 items.

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
"sessionArn": "string",
"sessionId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

sessionArn

The Amazon Resource Name (ARN) of the updated Q App session.

Type: String
sessionId

The unique identifier of the updated Q App session.

Type: String

UpdateQAppSession API Version 2023-11-27 360

Amazon Q Business API Reference

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The client is not authorized to perform the requested operation.

HTTP Status Code: 403

InternalServerException

An internal service error occurred while processing the request.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The requested operation could not be completed because it would exceed the service's quota or
limit.

HTTP Status Code: 402

ThrottlingException

The requested operation could not be completed because too many requests were sent at once.
Wait a bit and try again later.

HTTP Status Code: 429

UnauthorizedException

The client is not authenticated or authorized to perform the requested operation.

HTTP Status Code: 401

ValidationException

The input failed to satisfy the constraints specified by the service.

HTTP Status Code: 400

UpdateQAppSession API Version 2023-11-27 361

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go v2
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

UpdateQAppSession API Version 2023-11-27 362

Amazon Q Business API Reference

Data Types
The following data types are supported by QBusiness:

• AccessConfiguration
• AccessControl
• ActionExecution
• ActionExecutionEvent
• ActionExecutionPayloadField
• ActionReview
• ActionReviewEvent
• ActionReviewPayloadField
• ActionReviewPayloadFieldAllowedValue
• APISchema
• Application
• AppliedAttachmentsConfiguration
• AppliedCreatorModeConfiguration
• AttachmentInput
• AttachmentInputEvent
• AttachmentOutput
• AttachmentsConfiguration
• AttributeFilter
• AuthChallengeRequest
• AuthChallengeRequestEvent
• AuthChallengeResponse
• AuthChallengeResponseEvent
• BasicAuthConfiguration
• BlockedPhrasesConfiguration
• BlockedPhrasesConfigurationUpdate
• ChatInputStream
• ChatModeConfiguration

API Version 2023-11-27 363

Amazon Q Business API Reference

• ChatOutputStream
• ConfigurationEvent
• ContentBlockerRule
• ContentRetrievalRule
• Conversation
• CreatorModeConfiguration
• CustomPluginConfiguration
• DataSource
• DataSourceSyncJob
• DataSourceSyncJobMetrics
• DataSourceVpcConfiguration
• DateAttributeBoostingConfiguration
• DeleteDocument
• Document
• DocumentAttribute
• DocumentAttributeBoostingConfiguration
• DocumentAttributeCondition
• DocumentAttributeConfiguration
• DocumentAttributeTarget
• DocumentAttributeValue
• DocumentContent
• DocumentDetails
• DocumentEnrichmentConfiguration
• EligibleDataSource
• EncryptionConfiguration
• EndOfInputEvent
• ErrorDetail
• FailedAttachmentEvent
• FailedDocument
• GroupMembers

API Version 2023-11-27 364

Amazon Q Business API Reference

• GroupStatusDetail
• GroupSummary
• HookConfiguration
• Index
• IndexCapacityConfiguration
• IndexStatistics
• InlineDocumentEnrichmentConfiguration
• KendraIndexConfiguration
• MemberGroup
• MemberUser
• Message
• MessageUsefulnessFeedback
• MetadataEvent
• NativeIndexConfiguration
• NoAuthConfiguration
• NumberAttributeBoostingConfiguration
• OAuth2ClientCredentialConfiguration
• PersonalizationConfiguration
• Plugin
• PluginAuthConfiguration
• PluginConfiguration
• Principal
• PrincipalGroup
• PrincipalUser
• QAppsConfiguration
• Retriever
• RetrieverConfiguration
• Rule
• RuleConfiguration
• S3

API Version 2023-11-27 365

Amazon Q Business API Reference

• SamlConfiguration
• SnippetExcerpt
• SourceAttribution
• StringAttributeBoostingConfiguration
• StringListAttributeBoostingConfiguration
• Tag
• TextDocumentStatistics
• TextInputEvent
• TextOutputEvent
• TextSegment
• TopicConfiguration
• UserAlias
• UsersAndGroups
• ValidationExceptionField
• WebExperience
• WebExperienceAuthConfiguration

The following data types are supported by QApps:

• AppDefinition
• AppDefinitionInput
• AttributeFilter
• Card
• CardInput
• CardStatus
• CardValue
• Category
• ConversationMessage
• DocumentAttribute
• DocumentAttributeValue
• FileUploadCard

API Version 2023-11-27 366

Amazon Q Business API Reference

• FileUploadCardInput
• LibraryItemMember
• PredictAppDefinition
• PredictQAppInputOptions
• QPluginCard
• QPluginCardInput
• QQueryCard
• QQueryCardInput
• TextInputCard
• TextInputCardInput
• UserAppItem

QBusiness
The following data types are supported by QBusiness:

• AccessConfiguration
• AccessControl
• ActionExecution
• ActionExecutionEvent
• ActionExecutionPayloadField
• ActionReview
• ActionReviewEvent
• ActionReviewPayloadField
• ActionReviewPayloadFieldAllowedValue
• APISchema
• Application
• AppliedAttachmentsConfiguration
• AppliedCreatorModeConfiguration
• AttachmentInput
• AttachmentInputEvent

QBusiness API Version 2023-11-27 367

Amazon Q Business API Reference

• AttachmentOutput
• AttachmentsConfiguration
• AttributeFilter
• AuthChallengeRequest
• AuthChallengeRequestEvent
• AuthChallengeResponse
• AuthChallengeResponseEvent
• BasicAuthConfiguration
• BlockedPhrasesConfiguration
• BlockedPhrasesConfigurationUpdate
• ChatInputStream
• ChatModeConfiguration
• ChatOutputStream
• ConfigurationEvent
• ContentBlockerRule
• ContentRetrievalRule
• Conversation
• CreatorModeConfiguration
• CustomPluginConfiguration
• DataSource
• DataSourceSyncJob
• DataSourceSyncJobMetrics
• DataSourceVpcConfiguration
• DateAttributeBoostingConfiguration
• DeleteDocument
• Document
• DocumentAttribute
• DocumentAttributeBoostingConfiguration
• DocumentAttributeCondition
• DocumentAttributeConfiguration

QBusiness API Version 2023-11-27 368

Amazon Q Business API Reference

• DocumentAttributeTarget
• DocumentAttributeValue
• DocumentContent
• DocumentDetails
• DocumentEnrichmentConfiguration
• EligibleDataSource
• EncryptionConfiguration
• EndOfInputEvent
• ErrorDetail
• FailedAttachmentEvent
• FailedDocument
• GroupMembers
• GroupStatusDetail
• GroupSummary
• HookConfiguration
• Index
• IndexCapacityConfiguration
• IndexStatistics
• InlineDocumentEnrichmentConfiguration
• KendraIndexConfiguration
• MemberGroup
• MemberUser
• Message
• MessageUsefulnessFeedback
• MetadataEvent
• NativeIndexConfiguration
• NoAuthConfiguration
• NumberAttributeBoostingConfiguration
• OAuth2ClientCredentialConfiguration
• PersonalizationConfiguration

QBusiness API Version 2023-11-27 369

Amazon Q Business API Reference

• Plugin
• PluginAuthConfiguration
• PluginConfiguration
• Principal
• PrincipalGroup
• PrincipalUser
• QAppsConfiguration
• Retriever
• RetrieverConfiguration
• Rule
• RuleConfiguration
• S3
• SamlConfiguration
• SnippetExcerpt
• SourceAttribution
• StringAttributeBoostingConfiguration
• StringListAttributeBoostingConfiguration
• Tag
• TextDocumentStatistics
• TextInputEvent
• TextOutputEvent
• TextSegment
• TopicConfiguration
• UserAlias
• UsersAndGroups
• ValidationExceptionField
• WebExperience
• WebExperienceAuthConfiguration

QBusiness API Version 2023-11-27 370

Amazon Q Business API Reference

AccessConfiguration
Service: QBusiness

Used to configure access permissions for a document.

Contents

accessControls

A list of AccessControlList objects.

Type: Array of AccessControl objects

Required: Yes
memberRelation

Describes the member relation within the AccessControlList object.

Type: String

Valid Values: AND | OR

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AccessConfiguration API Version 2023-11-27 371

Amazon Q Business API Reference

AccessControl
Service: QBusiness

A list of principals. Each principal can be either a USER or a GROUP and can be designated
document access permissions of either ALLOW or DENY.

Contents

principals

Contains a list of principals, where a principal can be either a USER or a GROUP. Each principal
can be have the following type of document access: ALLOW or DENY.

Type: Array of Principal objects

Required: Yes
memberRelation

Describes the member relation within a principal list.

Type: String

Valid Values: AND | OR

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AccessControl API Version 2023-11-27 372

Amazon Q Business API Reference

ActionExecution
Service: QBusiness

Performs an Amazon Q Business plugin action during a non-streaming chat conversation.

Contents

payload

A mapping of field names to the field values in input that an end user provides to Amazon Q
Business requests to perform their plugin action.

Type: String to ActionExecutionPayloadField object map

Key Length Constraints: Minimum length of 1.

Required: Yes
payloadFieldNameSeparator

A string used to retain information about the hierarchical contexts within an action execution
event payload.

Type: String

Length Constraints: Fixed length of 1.

Required: Yes
pluginId

The identifier of the plugin the action is attached to.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

ActionExecution API Version 2023-11-27 373

Amazon Q Business API Reference

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ActionExecution API Version 2023-11-27 374

Amazon Q Business API Reference

ActionExecutionEvent
Service: QBusiness

A request from an end user signalling an intent to perform an Amazon Q Business plugin action
during a streaming chat.

Contents

payload

A mapping of field names to the field values in input that an end user provides to Amazon Q
Business requests to perform their plugin action.

Type: String to ActionExecutionPayloadField object map

Key Length Constraints: Minimum length of 1.

Required: Yes

payloadFieldNameSeparator

A string used to retain information about the hierarchical contexts within a action execution
event payload.

Type: String

Length Constraints: Fixed length of 1.

Required: Yes

pluginId

The identifier of the plugin for which the action is being requested.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

ActionExecutionEvent API Version 2023-11-27 375

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ActionExecutionEvent API Version 2023-11-27 376

Amazon Q Business API Reference

ActionExecutionPayloadField
Service: QBusiness

A user input field in an plugin action execution payload.

Contents

value

The content of a user input field in an plugin action execution payload.

Type: JSON value

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ActionExecutionPayloadField API Version 2023-11-27 377

Amazon Q Business API Reference

ActionReview
Service: QBusiness

An output event that Amazon Q Business returns to an user who wants to perform a plugin action
during a non-streaming chat conversation. It contains information about the selected action with a
list of possible user input fields, some pre-populated by Amazon Q Business.

Contents

payload

Field values that an end user needs to provide to Amazon Q Business for Amazon Q Business to
perform the requested plugin action.

Type: String to ActionReviewPayloadField object map

Key Length Constraints: Minimum length of 1.

Required: No
payloadFieldNameSeparator

A string used to retain information about the hierarchical contexts within an action review
payload.

Type: String

Length Constraints: Fixed length of 1.

Required: No
pluginId

The identifier of the plugin associated with the action review.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: No

ActionReview API Version 2023-11-27 378

Amazon Q Business API Reference

pluginType

The type of plugin.

Type: String

Valid Values: SERVICE_NOW | SALESFORCE | JIRA | ZENDESK | CUSTOM

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ActionReview API Version 2023-11-27 379

Amazon Q Business API Reference

ActionReviewEvent
Service: QBusiness

An output event that Amazon Q Business returns to an user who wants to perform a plugin action
during a streaming chat conversation. It contains information about the selected action with a list
of possible user input fields, some pre-populated by Amazon Q Business.

Contents

conversationId

The identifier of the conversation with which the action review event is associated.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
payload

Field values that an end user needs to provide to Amazon Q Business for Amazon Q Business to
perform the requested plugin action.

Type: String to ActionReviewPayloadField object map

Key Length Constraints: Minimum length of 1.

Required: No
payloadFieldNameSeparator

A string used to retain information about the hierarchical contexts within an action review event
payload.

Type: String

Length Constraints: Fixed length of 1.

Required: No

ActionReviewEvent API Version 2023-11-27 380

Amazon Q Business API Reference

pluginId

The identifier of the plugin associated with the action review event.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: No
pluginType

The type of plugin.

Type: String

Valid Values: SERVICE_NOW | SALESFORCE | JIRA | ZENDESK | CUSTOM

Required: No
systemMessageId

The identifier of an Amazon Q Business AI generated associated with the action review event.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
userMessageId

The identifier of the conversation with which the plugin action is associated.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No

ActionReviewEvent API Version 2023-11-27 381

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ActionReviewEvent API Version 2023-11-27 382

Amazon Q Business API Reference

ActionReviewPayloadField
Service: QBusiness

A user input field in an plugin action review payload.

Contents

allowedFormat

The expected data format for the action review input field value. For example, in PTO request,
from and to would be of datetime allowed format.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
allowedValues

Information about the field values that an end user can use to provide to Amazon Q Business
for Amazon Q Business to perform the requested plugin action.

Type: Array of ActionReviewPayloadFieldAllowedValue objects

Required: No
displayDescription

The field level description of each action review input field. This could be an explanation of the
field. In the Amazon Q Business web experience, these descriptions could be used to display as
tool tips to help users understand the field.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
displayName

The name of the field.

Type: String

ActionReviewPayloadField API Version 2023-11-27 383

Amazon Q Business API Reference

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
displayOrder

The display order of fields in a payload.

Type: Integer

Required: No
required

Information about whether the field is required.

Type: Boolean

Required: No
type

The type of field.

Type: String

Valid Values: STRING | NUMBER | ARRAY | BOOLEAN

Required: No
value

The field value.

Type: JSON value

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2

ActionReviewPayloadField API Version 2023-11-27 384

Amazon Q Business API Reference

• AWS SDK for Ruby V3

ActionReviewPayloadField API Version 2023-11-27 385

Amazon Q Business API Reference

ActionReviewPayloadFieldAllowedValue
Service: QBusiness

Information about the field values that an end user can use to provide to Amazon Q Business for
Amazon Q Business to perform the requested plugin action.

Contents

displayValue

The name of the field.

Type: JSON value

Required: No
value

The field value.

Type: JSON value

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ActionReviewPayloadFieldAllowedValue API Version 2023-11-27 386

Amazon Q Business API Reference

APISchema
Service: QBusiness

Contains details about the OpenAPI schema for a custom plugin. For more information, see custom
plugin OpenAPI schemas. You can either include the schema directly in the payload field or you can
upload it to an S3 bucket and specify the S3 bucket location in the s3 field.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

payload

The JSON or YAML-formatted payload defining the OpenAPI schema for a custom plugin.

Type: String

Required: No
s3

Contains details about the S3 object containing the OpenAPI schema for a custom plugin. The
schema could be in either JSON or YAML format.

Type: S3 object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

APISchema API Version 2023-11-27 387

Amazon Q Business API Reference

APISchema API Version 2023-11-27 388

Amazon Q Business API Reference

Application
Service: QBusiness

Summary information for an Amazon Q Business application.

Contents

applicationId

The identifier for the Amazon Q Business application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
createdAt

The Unix timestamp when the Amazon Q Business application was created.

Type: Timestamp

Required: No
displayName

The name of the Amazon Q Business application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
status

The status of the Amazon Q Business application. The application is ready to use when the
status is ACTIVE.

Type: String

Application API Version 2023-11-27 389

Amazon Q Business API Reference

Valid Values: CREATING | ACTIVE | DELETING | FAILED | UPDATING

Required: No
updatedAt

The Unix timestamp when the Amazon Q Business application was last updated.

Type: Timestamp

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Application API Version 2023-11-27 390

Amazon Q Business API Reference

AppliedAttachmentsConfiguration
Service: QBusiness

Configuration information about the file upload during chat feature for your application.

Contents

attachmentsControlMode

Information about whether file upload during chat functionality is activated for your
application.

Type: String

Valid Values: ENABLED | DISABLED

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AppliedAttachmentsConfiguration API Version 2023-11-27 391

Amazon Q Business API Reference

AppliedCreatorModeConfiguration
Service: QBusiness

The creator mode specific admin controls configured for an Amazon Q Business application.
Determines whether an end user can generate LLM-only responses when they use the web
experience.

For more information, see Admin controls and guardrails and Conversation settings.

Contents

creatorModeControl

Information about whether creator mode is enabled or disabled for an Amazon Q Business
application.

Type: String

Valid Values: ENABLED | DISABLED

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AppliedCreatorModeConfiguration API Version 2023-11-27 392

Amazon Q Business API Reference

AttachmentInput
Service: QBusiness

A file directly uploaded into a web experience chat.

Contents

data

The data contained within the uploaded file.

Type: Base64-encoded binary data object

Required: Yes
name

The name of the file.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AttachmentInput API Version 2023-11-27 393

Amazon Q Business API Reference

AttachmentInputEvent
Service: QBusiness

A file input event activated by a end user request to upload files into their web experience chat.

Contents

attachment

A file directly uploaded into a web experience chat.

Type: AttachmentInput object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AttachmentInputEvent API Version 2023-11-27 394

Amazon Q Business API Reference

AttachmentOutput
Service: QBusiness

The details of a file uploaded during chat.

Contents

error

An error associated with a file uploaded during chat.

Type: ErrorDetail object

Required: No
name

The name of a file uploaded during chat.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
status

The status of a file uploaded during chat.

Type: String

Valid Values: FAILED | SUCCEEDED

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

AttachmentOutput API Version 2023-11-27 395

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for Ruby V3

AttachmentOutput API Version 2023-11-27 396

Amazon Q Business API Reference

AttachmentsConfiguration
Service: QBusiness

Configuration information for the file upload during chat feature.

Contents

attachmentsControlMode

Status information about whether file upload functionality is activated or deactivated for your
end user.

Type: String

Valid Values: ENABLED | DISABLED

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AttachmentsConfiguration API Version 2023-11-27 397

Amazon Q Business API Reference

AttributeFilter
Service: QBusiness

Enables filtering of responses based on document attributes or metadata fields.

Contents

andAllFilters

Performs a logical AND operation on all supplied filters.

Type: Array of AttributeFilter objects

Required: No
containsAll

Returns true when a document contains all the specified document attributes or metadata
fields. Supported for the following document attribute value types: stringListValue.

Type: DocumentAttribute object

Required: No
containsAny

Returns true when a document contains any of the specified document attributes or metadata
fields. Supported for the following document attribute value types: stringListValue.

Type: DocumentAttribute object

Required: No
equalsTo

Performs an equals operation on two document attributes or metadata fields. Supported for
the following document attribute value types: dateValue, longValue, stringListValue
and stringValue.

Type: DocumentAttribute object

Required: No

AttributeFilter API Version 2023-11-27 398

Amazon Q Business API Reference

greaterThan

Performs a greater than operation on two document attributes or metadata fields. Supported
for the following document attribute value types: dateValue and longValue.

Type: DocumentAttribute object

Required: No
greaterThanOrEquals

Performs a greater or equals than operation on two document attributes or metadata fields.
Supported for the following document attribute value types: dateValue and longValue.

Type: DocumentAttribute object

Required: No
lessThan

Performs a less than operation on two document attributes or metadata fields. Supported for
the following document attribute value types: dateValue and longValue.

Type: DocumentAttribute object

Required: No
lessThanOrEquals

Performs a less than or equals operation on two document attributes or metadata

fields.Supported for the following document attribute value type: dateValue and longValue.

Type: DocumentAttribute object

Required: No
notFilter

Performs a logical NOT operation on all supplied filters.

Type: AttributeFilter object

Required: No
orAllFilters

Performs a logical OR operation on all supplied filters.

AttributeFilter API Version 2023-11-27 399

Amazon Q Business API Reference

Type: Array of AttributeFilter objects

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AttributeFilter API Version 2023-11-27 400

Amazon Q Business API Reference

AuthChallengeRequest
Service: QBusiness

A request made by Amazon Q Business to a third paty authentication server to authenticate a

custom plugin user.

Contents

authorizationUrl

The URL sent by Amazon Q Business to the third party authentication server to authenticate a
custom plugin user through an OAuth protocol.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AuthChallengeRequest API Version 2023-11-27 401

Amazon Q Business API Reference

AuthChallengeRequestEvent
Service: QBusiness

An authentication verification event activated by an end user request to use a custom plugin.

Contents

authorizationUrl

The URL sent by Amazon Q Business to a third party authentication server in response to an
authentication verification event activated by an end user request to use a custom plugin.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AuthChallengeRequestEvent API Version 2023-11-27 402

Amazon Q Business API Reference

AuthChallengeResponse
Service: QBusiness

Contains details of the authentication information received from a third party authentication
server in response to an authentication challenge.

Contents

responseMap

The mapping of key-value pairs in an authentication challenge response.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 100.

Value Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AuthChallengeResponse API Version 2023-11-27 403

Amazon Q Business API Reference

AuthChallengeResponseEvent
Service: QBusiness

An authentication verification event response by a third party authentication server to Amazon Q

Business.

Contents

responseMap

The mapping of key-value pairs in an authentication challenge response.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 100.

Value Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AuthChallengeResponseEvent API Version 2023-11-27 404

Amazon Q Business API Reference

BasicAuthConfiguration
Service: QBusiness

Information about the basic authentication credentials used to configure a plugin.

Contents

roleArn

The ARN of an IAM role used by Amazon Q Business to access the basic authentication
credentials stored in a Secrets Manager secret.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: Yes
secretArn

The ARN of the Secrets Manager secret that stores the basic authentication credentials used for
plugin configuration..

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2

BasicAuthConfiguration API Version 2023-11-27 405

Amazon Q Business API Reference

• AWS SDK for Ruby V3

BasicAuthConfiguration API Version 2023-11-27 406

Amazon Q Business API Reference

BlockedPhrasesConfiguration
Service: QBusiness

Provides information about the phrases blocked from chat by your chat control configuration.

Contents

blockedPhrases

A list of phrases blocked from a Amazon Q Business web experience chat.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 5 items.

Length Constraints: Minimum length of 0. Maximum length of 36.

Pattern: ^\P{C}*$

Required: No
systemMessageOverride

The configured custom message displayed to an end user informing them that they've used a
blocked phrase during chat.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 350.

Pattern: ^\P{C}*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

BlockedPhrasesConfiguration API Version 2023-11-27 407

Amazon Q Business API Reference

BlockedPhrasesConfiguration API Version 2023-11-27 408

Amazon Q Business API Reference

BlockedPhrasesConfigurationUpdate
Service: QBusiness

Updates a blocked phrases configuration in your Amazon Q Business application.

Contents

blockedPhrasesToCreateOrUpdate

Creates or updates a blocked phrases configuration in your Amazon Q Business application.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 5 items.

Length Constraints: Minimum length of 0. Maximum length of 36.

Pattern: ^\P{C}*$

Required: No
blockedPhrasesToDelete

Deletes a blocked phrases configuration in your Amazon Q Business application.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 5 items.

Length Constraints: Minimum length of 0. Maximum length of 36.

Pattern: ^\P{C}*$

Required: No
systemMessageOverride

The configured custom message displayed to your end user when they use blocked phrase
during chat.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 350.

Pattern: ^\P{C}*$

BlockedPhrasesConfigurationUpdate API Version 2023-11-27 409

Amazon Q Business API Reference

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

BlockedPhrasesConfigurationUpdate API Version 2023-11-27 410

Amazon Q Business API Reference

ChatInputStream
Service: QBusiness

The streaming input for the Chat API.

Contents

actionExecutionEvent

A request from an end user to perform an Amazon Q Business plugin action.

Type: ActionExecutionEvent object

Required: No
attachmentEvent

A request by an end user to upload a file during chat.

Type: AttachmentInputEvent object

Required: No
authChallengeResponseEvent

An authentication verification event response by a third party authentication server to Amazon

Q Business.

Type: AuthChallengeResponseEvent object

Required: No
configurationEvent

A configuration event activated by an end user request to select a specific chat mode.

Type: ConfigurationEvent object

Required: No
endOfInputEvent

The end of the streaming input for the Chat API.

Type: EndOfInputEvent object

ChatInputStream API Version 2023-11-27 411

Amazon Q Business API Reference

Required: No
textEvent

Information about the payload of the ChatInputStream event containing the end user
message input.

Type: TextInputEvent object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ChatInputStream API Version 2023-11-27 412

Amazon Q Business API Reference

ChatModeConfiguration
Service: QBusiness

Configuration information for Amazon Q Business conversation modes.

For more information, see Admin controls and guardrails and Conversation settings.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

pluginConfiguration

Configuration information required to invoke chat in PLUGIN_MODE.

Type: PluginConfiguration object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ChatModeConfiguration API Version 2023-11-27 413

Amazon Q Business API Reference

ChatOutputStream
Service: QBusiness

The streaming output for the Chat API.

Contents

actionReviewEvent

A request from Amazon Q Business to the end user for information Amazon Q Business needs
to successfully complete a requested plugin action.

Type: ActionReviewEvent object

Required: No
authChallengeRequestEvent

An authentication verification event activated by an end user request to use a custom plugin.

Type: AuthChallengeRequestEvent object

Required: No
failedAttachmentEvent

A failed file upload event during a web experience chat.

Type: FailedAttachmentEvent object

Required: No
metadataEvent

A metadata event for a AI-generated text output message in a Amazon Q Business conversation.

Type: MetadataEvent object

Required: No
textEvent

Information about the payload of the ChatOutputStream event containing the AI-generated
message output.

Type: TextOutputEvent object

ChatOutputStream API Version 2023-11-27 414

Amazon Q Business API Reference

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ChatOutputStream API Version 2023-11-27 415

Amazon Q Business API Reference

ConfigurationEvent
Service: QBusiness

A configuration event activated by an end user request to select a specific chat mode.

Contents

attributeFilter

Enables filtering of responses based on document attributes or metadata fields.

Type: AttributeFilter object

Required: No
chatMode

The chat modes available to an Amazon Q Business end user.

• RETRIEVAL_MODE - The default chat mode for an Amazon Q Business application. When this
mode is enabled, Amazon Q Business generates responses only from data sources connected
to an Amazon Q Business application.
• CREATOR_MODE - By selecting this mode, users can choose to generate responses only from
the LLM knowledge, without consulting connected data sources, for a chat request.
• PLUGIN_MODE - By selecting this mode, users can choose to use plugins in chat.

For more information, see Admin controls and guardrails, Plugins, and Conversation settings.

Type: String

Valid Values: RETRIEVAL_MODE | CREATOR_MODE | PLUGIN_MODE

Required: No
chatModeConfiguration

Configuration information for Amazon Q Business conversation modes.

For more information, see Admin controls and guardrails and Conversation settings.

Type: ChatModeConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

ConfigurationEvent API Version 2023-11-27 416

Amazon Q Business API Reference

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ConfigurationEvent API Version 2023-11-27 417

Amazon Q Business API Reference

ContentBlockerRule
Service: QBusiness

A rule for configuring how Amazon Q Business responds when it encounters a a blocked topic. You
can configure a custom message to inform your end users that they have asked about a restricted
topic and suggest any next steps they should take.

Contents

systemMessageOverride

The configured custom message displayed to an end user informing them that they've used a
blocked phrase during chat.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 350.

Pattern: ^\P{C}*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ContentBlockerRule API Version 2023-11-27 418

Amazon Q Business API Reference

ContentRetrievalRule
Service: QBusiness

Rules for retrieving content from data sources connected to a Amazon Q Business application for a
specific topic control configuration.

Contents

eligibleDataSources

Specifies data sources in a Amazon Q Business application to use for content generation.

Type: Array of EligibleDataSource objects

Array Members: Minimum number of 0 items. Maximum number of 5 items.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ContentRetrievalRule API Version 2023-11-27 419

Amazon Q Business API Reference

Conversation
Service: QBusiness

A conversation in an Amazon Q Business application.

Contents

conversationId

The identifier of the Amazon Q Business conversation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
startTime

The start time of the conversation.

Type: Timestamp

Required: No
title

The title of the conversation.

Type: String

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Conversation API Version 2023-11-27 420

Amazon Q Business API Reference

Conversation API Version 2023-11-27 421

Amazon Q Business API Reference

CreatorModeConfiguration
Service: QBusiness

Configuration information required to invoke chat in CREATOR_MODE.

For more information, see Admin controls and guardrails and Conversation settings.

Contents

creatorModeControl

Status information about whether CREATOR_MODE has been enabled or disabled. The default
status is DISABLED.

Type: String

Valid Values: ENABLED | DISABLED

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

CreatorModeConfiguration API Version 2023-11-27 422

Amazon Q Business API Reference

CustomPluginConfiguration
Service: QBusiness

Configuration information required to create a custom plugin.

Contents

apiSchema

Contains either details about the S3 object containing the OpenAPI schema for the action group
or the JSON or YAML-formatted payload defining the schema.

Type: APISchema object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: Yes
apiSchemaType

The type of OpenAPI schema to use.

Type: String

Valid Values: OPEN_API_V3

Required: Yes
description

A description for your custom plugin configuration.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

CustomPluginConfiguration API Version 2023-11-27 423

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for Ruby V3

CustomPluginConfiguration API Version 2023-11-27 424

Amazon Q Business API Reference

DataSource
Service: QBusiness

A data source in an Amazon Q Business application.

Contents

createdAt

The Unix timestamp when the Amazon Q Business data source was created.

Type: Timestamp

Required: No
dataSourceId

The identifier of the Amazon Q Business data source.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
displayName

The name of the Amazon Q Business data source.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
status

The status of the Amazon Q Business data source.

Type: String

DataSource API Version 2023-11-27 425

Amazon Q Business API Reference

Valid Values: PENDING_CREATION | CREATING | ACTIVE | DELETING | FAILED |

UPDATING

Required: No
type

The type of the Amazon Q Business data source.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
updatedAt

The Unix timestamp when the Amazon Q Business data source was last updated.

Type: Timestamp

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DataSource API Version 2023-11-27 426

Amazon Q Business API Reference

DataSourceSyncJob
Service: QBusiness

Provides information about an Amazon Q Business data source connector synchronization job.

Contents

dataSourceErrorCode

If the reason that the synchronization failed is due to an error with the underlying data source,
this field contains a code that identifies the error.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
endTime

The Unix timestamp when the synchronization job completed.

Type: Timestamp

Required: No
error

If the Status field is set to FAILED, the ErrorCode field indicates the reason the
synchronization failed.

Type: ErrorDetail object

Required: No
executionId

The identifier of a data source synchronization job.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

DataSourceSyncJob API Version 2023-11-27 427

Amazon Q Business API Reference

Required: No
metrics

Maps a batch delete document request to a specific data source sync job. This is optional and
should only be supplied when documents are deleted by a data source connector.

Type: DataSourceSyncJobMetrics object

Required: No
startTime

The Unix time stamp when the data source synchronization job started.

Type: Timestamp

Required: No
status

The status of the synchronization job. When the Status field is set to SUCCEEDED, the
synchronization job is done. If the status code is FAILED, the ErrorCode and ErrorMessage
fields give you the reason for the failure.

Type: String

Valid Values: FAILED | SUCCEEDED | SYNCING | INCOMPLETE | STOPPING | ABORTED

| SYNCING_INDEXING

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DataSourceSyncJob API Version 2023-11-27 428

Amazon Q Business API Reference

DataSourceSyncJobMetrics
Service: QBusiness

Maps a batch delete document request to a specific Amazon Q Business data source connector sync
job.

Contents

documentsAdded

The current count of documents added from the data source during the data source sync.

Type: String

Pattern: ^(([1-9][0-9]*)|0)$

Required: No
documentsDeleted

The current count of documents deleted from the data source during the data source sync.

Type: String

Pattern: ^(([1-9][0-9]*)|0)$

Required: No
documentsFailed

The current count of documents that failed to sync from the data source during the data source
sync.

Type: String

Pattern: ^(([1-9][0-9]*)|0)$

Required: No
documentsModified

The current count of documents modified in the data source during the data source sync.

Type: String

DataSourceSyncJobMetrics API Version 2023-11-27 429

Amazon Q Business API Reference

Pattern: ^(([1-9][0-9]*)|0)$

Required: No
documentsScanned

The current count of documents crawled by the ongoing sync job in the data source.

Type: String

Pattern: ^(([1-9][0-9]*)|0)$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DataSourceSyncJobMetrics API Version 2023-11-27 430

Amazon Q Business API Reference

DataSourceVpcConfiguration
Service: QBusiness

Provides configuration information needed to connect to an Amazon VPC (Virtual Private Cloud).

Contents

securityGroupIds

A list of identifiers of security groups within your Amazon VPC. The security groups should
enable Amazon Q Business to connect to the data source.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[-0-9a-zA-Z]+$

Required: Yes
subnetIds

A list of identifiers for subnets within your Amazon VPC. The subnets should be able to connect
to each other in the VPC, and they should have outgoing access to the Internet through a NAT
device.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[-0-9a-zA-Z]+$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

DataSourceVpcConfiguration API Version 2023-11-27 431

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for Ruby V3

DataSourceVpcConfiguration API Version 2023-11-27 432

Amazon Q Business API Reference

DateAttributeBoostingConfiguration
Service: QBusiness

Provides information on boosting DATE type document attributes.

For more information on how boosting document attributes work in Amazon Q Business, see
Boosting using document attributes.

Contents

boostingLevel

Specifies how much a document attribute is boosted.

Type: String

Valid Values: NONE | LOW | MEDIUM | HIGH | VERY_HIGH

Required: Yes
boostingDurationInSeconds

Specifies the duration, in seconds, of a boost applies to a DATE type document attribute.

Type: Long

Valid Range: Minimum value of 0. Maximum value of 999999999.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DateAttributeBoostingConfiguration API Version 2023-11-27 433

Amazon Q Business API Reference

DeleteDocument
Service: QBusiness

A document deleted from an Amazon Q Business data source connector.

Contents

documentId

The identifier of the deleted document.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1825.

Pattern: ^\P{C}*$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DeleteDocument API Version 2023-11-27 434

Amazon Q Business API Reference

Document
Service: QBusiness

A document in an Amazon Q Business application.

Contents

id

The identifier of the document.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1825.

Pattern: ^\P{C}*$

Required: Yes
accessConfiguration

Configuration information for access permission to a document.

Type: AccessConfiguration object

Required: No
attributes

Custom attributes to apply to the document for refining Amazon Q Business web experience
responses.

Type: Array of DocumentAttribute objects

Array Members: Minimum number of 1 item. Maximum number of 500 items.

Required: No
content

The contents of the document.

Type: DocumentContent object

Note: This object is a Union. Only one member of this object can be specified or returned.

Document API Version 2023-11-27 435

Amazon Q Business API Reference

Required: No
contentType

The file type of the document in the Blob field.

If you want to index snippets or subsets of HTML documents instead of the entirety of the
HTML documents, you add the HTML start and closing tags (<HTML>content</HTML>) around
the content.

Type: String

Valid Values: PDF | HTML | MS_WORD | PLAIN_TEXT | PPT | RTF | XML | XSLT |
MS_EXCEL | CSV | JSON | MD

Required: No
documentEnrichmentConfiguration

The configuration information for altering document metadata and content during the
document ingestion process.

Type: DocumentEnrichmentConfiguration object

Required: No
title

The title of the document.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2

Document API Version 2023-11-27 436

Amazon Q Business API Reference

• AWS SDK for Ruby V3

Document API Version 2023-11-27 437

Amazon Q Business API Reference

DocumentAttribute
Service: QBusiness

A document attribute or metadata field.

Contents

name

The identifier for the attribute.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$

Required: Yes
value

The value of the attribute.

Type: DocumentAttributeValue object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttribute API Version 2023-11-27 438

Amazon Q Business API Reference

DocumentAttributeBoostingConfiguration
Service: QBusiness

Provides information on boosting supported Amazon Q Business document attribute types. When
an end user chat query matches document attributes that have been boosted, Amazon Q Business
prioritizes generating responses from content that matches the boosted document attributes.

Note
For STRING and STRING_LIST type document attributes to be used for
boosting on the console and the API, they must be enabled for search using the
DocumentAttributeConfiguration object of the UpdateIndex API. If you haven't enabled
searching on these attributes, you can't boost attributes of these data types on either the
console or the API.

For more information on how boosting document attributes work in Amazon Q Business, see
Boosting using document attributes.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

dateConfiguration

Provides information on boosting DATE type document attributes.

Type: DateAttributeBoostingConfiguration object

Required: No
numberConfiguration

Provides information on boosting NUMBER type document attributes.

Type: NumberAttributeBoostingConfiguration object

DocumentAttributeBoostingConfiguration API Version 2023-11-27 439

Amazon Q Business API Reference

Required: No
stringConfiguration

Provides information on boosting STRING type document attributes.

Type: StringAttributeBoostingConfiguration object

Required: No
stringListConfiguration

Provides information on boosting STRING_LIST type document attributes.

Type: StringListAttributeBoostingConfiguration object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttributeBoostingConfiguration API Version 2023-11-27 440

Amazon Q Business API Reference

DocumentAttributeCondition
Service: QBusiness

The condition used for the target document attribute or metadata field when ingesting documents
into Amazon Q Business. You use this with DocumentAttributeTarget to apply the condition.

For example, you can create the 'Department' target field and have it prefill department names
associated with the documents based on information in the 'Source_URI' field. Set the condition
that if the 'Source_URI' field contains 'financial' in its URI value, then prefill the target field
'Department' with the target value 'Finance' for the document.

Amazon Q Business can't create a target field if it has not already been created as an index
field. After you create your index field, you can create a document metadata field using
DocumentAttributeTarget. Amazon Q Business then will map your newly created metadata
field to your index field.

Contents

key

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains
source URIs associated with the documents.

Amazon Q Business currently doesn't support _document_body as an attribute key used for
the condition.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$

Required: Yes
operator

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains
source URIs associated with the documents.

DocumentAttributeCondition API Version 2023-11-27 441

Amazon Q Business API Reference

Amazon Q Business currently does not support _document_body as an attribute key used for
the condition.

Type: String

Valid Values: GREATER_THAN | GREATER_THAN_OR_EQUALS | LESS_THAN |

LESS_THAN_OR_EQUALS | EQUALS | NOT_EQUALS | CONTAINS | NOT_CONTAINS |
EXISTS | NOT_EXISTS | BEGINS_WITH

Required: Yes
value

The value of a document attribute. You can only provide one value for a document attribute.

Type: DocumentAttributeValue object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttributeCondition API Version 2023-11-27 442

Amazon Q Business API Reference

DocumentAttributeConfiguration
Service: QBusiness

Configuration information for document attributes. Document attributes are metadata or fields
associated with your documents. For example, the company department name associated with
each document.

For more information, see Understanding document attributes.

Contents

name

The name of the document attribute.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 30.

Pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$

Required: No
search

Information about whether the document attribute can be used by an end user to search for
information on their web experience.

Type: String

Valid Values: ENABLED | DISABLED

Required: No
type

The type of document attribute.

Type: String

Valid Values: STRING | STRING_LIST | NUMBER | DATE

Required: No

DocumentAttributeConfiguration API Version 2023-11-27 443

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttributeConfiguration API Version 2023-11-27 444

Amazon Q Business API Reference

DocumentAttributeTarget
Service: QBusiness

The target document attribute or metadata field you want to alter when ingesting documents into
Amazon Q Business.

For example, you can delete all customer identification numbers associated with the documents,
stored in the document metadata field called 'Customer_ID' by setting the target key as
'Customer_ID' and the deletion flag to TRUE. This removes all customer ID values in the field
'Customer_ID'. This would scrub personally identifiable information from each document's
metadata.

Amazon Q Business can't create a target field if it has not already been created as an index
field. After you create your index field, you can create a document metadata field using
DocumentAttributeTarget. Amazon Q Business will then map your newly created document
attribute to your index field.

You can also use this with DocumentAttributeCondition.

Contents

key

The identifier of the target document attribute or metadata field. For example, 'Department'
could be an identifier for the target attribute or metadata field that includes the department
names associated with the documents.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$

Required: Yes
attributeValueOperator

TRUE to delete the existing target value for your specified target attribute key. You cannot
create a target value and set this to TRUE.

Type: String

DocumentAttributeTarget API Version 2023-11-27 445

Amazon Q Business API Reference

Valid Values: DELETE

Required: No
value

The value of a document attribute. You can only provide one value for a document attribute.

Type: DocumentAttributeValue object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttributeTarget API Version 2023-11-27 446

Amazon Q Business API Reference

DocumentAttributeValue
Service: QBusiness

The value of a document attribute. You can only provide one value for a document attribute.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

dateValue

A date expressed as an ISO 8601 string.

It's important for the time zone to be included in the ISO 8601 date-time format. For example,
2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at
12:30PM (plus 10 seconds) in Central European Time.

Type: Timestamp

Required: No
longValue

A long integer value.

Type: Long

Required: No
stringListValue

A list of strings.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

DocumentAttributeValue API Version 2023-11-27 447

Amazon Q Business API Reference

stringValue

A string.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttributeValue API Version 2023-11-27 448

Amazon Q Business API Reference

DocumentContent
Service: QBusiness

The contents of a document.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

blob

The contents of the document. Documents passed to the blob parameter must be base64
encoded. Your code might not need to encode the document file bytes if you're using an AWS
SDK to call Amazon Q Business APIs. If you are calling the Amazon Q Business endpoint directly
using REST, you must base64 encode the contents before sending.

Type: Base64-encoded binary data object

Required: No
s3

The path to the document in an Amazon S3 bucket.

Type: S3 object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentContent API Version 2023-11-27 449

Amazon Q Business API Reference

DocumentContent API Version 2023-11-27 450

Amazon Q Business API Reference

DocumentDetails
Service: QBusiness

The details of a document within an Amazon Q Business index.

Contents

createdAt

The timestamp for when the document was created.

Type: Timestamp

Required: No
documentId

The identifier of the document.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1825.

Pattern: ^\P{C}*$

Required: No
error

An error message associated with the document.

Type: ErrorDetail object

Required: No
status

The current status of the document.

Type: String

Valid Values: RECEIVED | PROCESSING | INDEXED | UPDATED | FAILED | DELETING

| DELETED | DOCUMENT_FAILED_TO_INDEX

Required: No

DocumentDetails API Version 2023-11-27 451

Amazon Q Business API Reference

updatedAt

The timestamp for when the document was last updated.

Type: Timestamp

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentDetails API Version 2023-11-27 452

Amazon Q Business API Reference

DocumentEnrichmentConfiguration
Service: QBusiness

Provides the configuration information for altering document metadata and content during the
document ingestion process.

For more information, see Custom document enrichment.

Contents

inlineConfigurations

Configuration information to alter document attributes or metadata fields and content when
ingesting documents into Amazon Q Business.

Type: Array of InlineDocumentEnrichmentConfiguration objects

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Required: No
postExtractionHookConfiguration

Provides the configuration information for invoking a Lambda function in AWS Lambda to alter
document metadata and content when ingesting documents into Amazon Q Business.

You can configure your Lambda function using the PreExtractionHookConfiguration

parameter if you want to apply advanced alterations on the original or raw documents.

If you want to apply advanced alterations on the Amazon Q Business structured documents, you
must configure your Lambda function using PostExtractionHookConfiguration.

You can only invoke one Lambda function. However, this function can invoke other functions it
requires.

For more information, see Custom document enrichment.

Type: HookConfiguration object

Required: No
preExtractionHookConfiguration

Provides the configuration information for invoking a Lambda function in AWS Lambda to alter
document metadata and content when ingesting documents into Amazon Q Business.

DocumentEnrichmentConfiguration API Version 2023-11-27 453

Amazon Q Business API Reference

You can configure your Lambda function using the PreExtractionHookConfiguration

parameter if you want to apply advanced alterations on the original or raw documents.

If you want to apply advanced alterations on the Amazon Q Business structured documents, you
must configure your Lambda function using PostExtractionHookConfiguration.

You can only invoke one Lambda function. However, this function can invoke other functions it
requires.

For more information, see Custom document enrichment.

Type: HookConfiguration object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentEnrichmentConfiguration API Version 2023-11-27 454

Amazon Q Business API Reference

EligibleDataSource
Service: QBusiness

The identifier of the data source Amazon Q Business will generate responses from.

Contents

dataSourceId

The identifier of the data source.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
indexId

The identifier of the index the data source is attached to.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

EligibleDataSource API Version 2023-11-27 455

Amazon Q Business API Reference

EncryptionConfiguration
Service: QBusiness

Provides the identifier of the AWS KMS key used to encrypt data indexed by Amazon Q Business.
Amazon Q Business doesn't support asymmetric keys.

Contents

kmsKeyId

The identifier of the AWS KMS key. Amazon Q Business doesn't support asymmetric keys.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

EncryptionConfiguration API Version 2023-11-27 456

Amazon Q Business API Reference

EndOfInputEvent
Service: QBusiness

The end of the streaming input for the Chat API.

Contents

The members of this exception structure are context-dependent.

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

EndOfInputEvent API Version 2023-11-27 457

Amazon Q Business API Reference

ErrorDetail
Service: QBusiness

Provides information about a data source sync error.

Contents

errorCode

The code associated with the data source sync error.

Type: String

Valid Values: InternalError | InvalidRequest | ResourceInactive |

ResourceNotFound

Required: No
errorMessage

The message explaining the data source sync error.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^\P{C}*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ErrorDetail API Version 2023-11-27 458

Amazon Q Business API Reference

FailedAttachmentEvent
Service: QBusiness

A failed file upload during web experience chat.

Contents

attachment

The details of a file uploaded during chat.

Type: AttachmentOutput object

Required: No
conversationId

The identifier of the conversation associated with the failed file upload.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
systemMessageId

The identifier of the AI-generated message associated with the file upload.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
userMessageId

The identifier of the end user chat message associated with the file upload.

Type: String

FailedAttachmentEvent API Version 2023-11-27 459

Amazon Q Business API Reference

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

FailedAttachmentEvent API Version 2023-11-27 460

Amazon Q Business API Reference

FailedDocument
Service: QBusiness

A list of documents that could not be removed from an Amazon Q Business index. Each entry
contains an error message that indicates why the document couldn't be removed from the index.

Contents

dataSourceId

The identifier of the Amazon Q Business data source connector that contains the failed
document.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
error

An explanation for why the document couldn't be removed from the index.

Type: ErrorDetail object

Required: No
id

The identifier of the document that couldn't be removed from the Amazon Q Business index.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1825.

Pattern: ^\P{C}*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

FailedDocument API Version 2023-11-27 461

Amazon Q Business API Reference

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

FailedDocument API Version 2023-11-27 462

Amazon Q Business API Reference

GroupMembers
Service: QBusiness

A list of users or sub groups that belong to a group. This is for generating Amazon Q Business chat
results only from document a user has access to.

Contents

memberGroups

A list of sub groups that belong to a group. For example, the sub groups "Research",
"Engineering", and "Sales and Marketing" all belong to the group "Company".

Type: Array of MemberGroup objects

Array Members: Minimum number of 1 item. Maximum number of 1000 items.

Required: No
memberUsers

A list of users that belong to a group. For example, a list of interns all belong to the "Interns"
group.

Type: Array of MemberUser objects

Array Members: Minimum number of 1 item. Maximum number of 1000 items.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

GroupMembers API Version 2023-11-27 463

Amazon Q Business API Reference

GroupStatusDetail
Service: QBusiness

Provides the details of a group's status.

Contents

errorDetail

The details of an error associated a group status.

Type: ErrorDetail object

Required: No
lastUpdatedAt

The Unix timestamp when the Amazon Q Business application was last updated.

Type: Timestamp

Required: No
status

The status of a group.

Type: String

Valid Values: FAILED | SUCCEEDED | PROCESSING | DELETING | DELETED

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

GroupStatusDetail API Version 2023-11-27 464

Amazon Q Business API Reference

GroupSummary
Service: QBusiness

Summary information for groups.

Contents

groupName

The name of the group the summary information is for.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

GroupSummary API Version 2023-11-27 465

Amazon Q Business API Reference

HookConfiguration
Service: QBusiness

Provides the configuration information for invoking a Lambda function in AWS Lambda to alter
document metadata and content when ingesting documents into Amazon Q Business.

You can configure your Lambda function using the PreExtractionHookConfiguration

parameter if you want to apply advanced alterations on the original or raw documents.

If you want to apply advanced alterations on the Amazon Q Business structured documents, you
must configure your Lambda function using PostExtractionHookConfiguration.

You can only invoke one Lambda function. However, this function can invoke other functions it
requires.

For more information, see Custom document enrichment.

Contents

invocationCondition

The condition used for when a Lambda function should be invoked.

For example, you can specify a condition that if there are empty date-time values, then Amazon
Q Business should invoke a function that inserts the current date-time.

Type: DocumentAttributeCondition object

Required: No
lambdaArn

The Amazon Resource Name (ARN) of a role with permission to run a Lambda function during
ingestion. For more information, see IAM roles for Custom Document Enrichment (CDE).

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^arn:aws[a-zA-Z-]*:lambda:[a-z-]*-[0-9]:[0-9]{12}:function:[a-zA-
Z0-9-_]+(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?
(:[a-zA-Z0-9-_]+)?$

HookConfiguration API Version 2023-11-27 466

Amazon Q Business API Reference

Required: No
roleArn

The Amazon Resource Name (ARN) of a role with permission to run

PreExtractionHookConfiguration and PostExtractionHookConfiguration for
altering document metadata and content during the document ingestion process.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: No
s3BucketName

Stores the original, raw documents or the structured, parsed documents before and after
altering them. For more information, see Data contracts for Lambda functions.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 63.

Pattern: ^[a-z0-9][\.\-a-z0-9]{1,61}[a-z0-9]$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

HookConfiguration API Version 2023-11-27 467

Amazon Q Business API Reference

Index
Service: QBusiness

Summary information for your Amazon Q Business index.

Contents

createdAt

The Unix timestamp when the index was created.

Type: Timestamp

Required: No
displayName

The name of the index.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
indexId

The identifier for the index.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
status

The current status of the index. When the status is ACTIVE, the index is ready.

Type: String

Index API Version 2023-11-27 468

Amazon Q Business API Reference

Valid Values: CREATING | ACTIVE | DELETING | FAILED | UPDATING

Required: No
updatedAt

The Unix timestamp when the index was last updated.

Type: Timestamp

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Index API Version 2023-11-27 469

Amazon Q Business API Reference

IndexCapacityConfiguration
Service: QBusiness

Provides information about index capacity configuration.

Contents

units

The number of storage units configured for an Amazon Q Business index.

Type: Integer

Valid Range: Minimum value of 1.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

IndexCapacityConfiguration API Version 2023-11-27 470

Amazon Q Business API Reference

IndexStatistics
Service: QBusiness

Provides information about the number of documents in an index.

Contents

textDocumentStatistics

The number of documents indexed.

Type: TextDocumentStatistics object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

IndexStatistics API Version 2023-11-27 471

Amazon Q Business API Reference

InlineDocumentEnrichmentConfiguration
Service: QBusiness

Provides the configuration information for applying basic logic to alter document metadata and
content when ingesting documents into Amazon Q Business.

To apply advanced logic, to go beyond what you can do with basic logic, see
HookConfiguration.

For more information, see Custom document enrichment.

Contents

condition

The condition used for the target document attribute or metadata field when ingesting
documents into Amazon Q Business. You use this with DocumentAttributeTarget to apply
the condition.

For example, you can create the 'Department' target field and have it prefill department names
associated with the documents based on information in the 'Source_URI' field. Set the condition
that if the 'Source_URI' field contains 'financial' in its URI value, then prefill the target field
'Department' with the target value 'Finance' for the document.

Amazon Q Business can't create a target field if it has not already been created as an index
field. After you create your index field, you can create a document metadata field using
DocumentAttributeTarget. Amazon Q Business then will map your newly created metadata
field to your index field.

Type: DocumentAttributeCondition object

Required: No
documentContentOperator

TRUE to delete content if the condition used for the target attribute is met.

Type: String

Valid Values: DELETE

Required: No

InlineDocumentEnrichmentConfiguration API Version 2023-11-27 472

Amazon Q Business API Reference

target

The target document attribute or metadata field you want to alter when ingesting documents
into Amazon Q Business.

For example, you can delete all customer identification numbers associated with the
documents, stored in the document metadata field called 'Customer_ID' by setting the target
key as 'Customer_ID' and the deletion flag to TRUE. This removes all customer ID values in the
field 'Customer_ID'. This would scrub personally identifiable information from each document's
metadata.

Amazon Q Business can't create a target field if it has not already been created as an index
field. After you create your index field, you can create a document metadata field using
DocumentAttributeTarget. Amazon Q Business will then map your newly created document
attribute to your index field.

You can also use this with DocumentAttributeCondition.

Type: DocumentAttributeTarget object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

InlineDocumentEnrichmentConfiguration API Version 2023-11-27 473

Amazon Q Business API Reference

KendraIndexConfiguration
Service: QBusiness

Stores an Amazon Kendra index as a retriever.

Contents

indexId

The identifier of the Amazon Kendra index.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

KendraIndexConfiguration API Version 2023-11-27 474

Amazon Q Business API Reference

MemberGroup
Service: QBusiness

The sub groups that belong to a group.

Contents

groupName

The name of the sub group.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: Yes
type

The type of the sub group.

Type: String

Valid Values: INDEX | DATASOURCE

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

MemberGroup API Version 2023-11-27 475

Amazon Q Business API Reference

MemberUser
Service: QBusiness

The users that belong to a group.

Contents

userId

The identifier of the user you want to map to a group.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: Yes
type

The type of the user.

Type: String

Valid Values: INDEX | DATASOURCE

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

MemberUser API Version 2023-11-27 476

Amazon Q Business API Reference

Message
Service: QBusiness

A message in an Amazon Q Business web experience.

Contents

actionExecution

Performs an Amazon Q Business plugin action during a non-streaming chat conversation.

Type: ActionExecution object

Required: No
actionReview

An output event that Amazon Q Business returns to an user who wants to perform a plugin
action during a non-streaming chat conversation. It contains information about the selected
action with a list of possible user input fields, some pre-populated by Amazon Q Business.

Type: ActionReview object

Required: No
attachments

A file directly uploaded into an Amazon Q Business web experience chat.

Type: Array of AttachmentOutput objects

Required: No
body

The content of the Amazon Q Business web experience message.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$}$

Required: No

Message API Version 2023-11-27 477

Amazon Q Business API Reference

messageId

The identifier of the Amazon Q Business web experience message.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
sourceAttribution

The source documents used to generate Amazon Q Business web experience message.

Type: Array of SourceAttribution objects

Required: No
time

The timestamp of the first Amazon Q Business web experience message.

Type: Timestamp

Required: No
type

The type of Amazon Q Business message, whether HUMAN or AI generated.

Type: String

Valid Values: USER | SYSTEM

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Message API Version 2023-11-27 478

Amazon Q Business API Reference

Message API Version 2023-11-27 479

Amazon Q Business API Reference

MessageUsefulnessFeedback
Service: QBusiness

End user feedback on an AI-generated web experience chat message usefulness.

Contents

submittedAt

The timestamp for when the feedback was submitted.

Type: Timestamp

Required: Yes
usefulness

The usefulness value assigned by an end user to a message.

Type: String

Valid Values: USEFUL | NOT_USEFUL

Required: Yes
comment

A comment given by an end user on the usefulness of an AI-generated chat message.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: No
reason

The reason for a usefulness rating.

Type: String

Valid Values: NOT_FACTUALLY_CORRECT | HARMFUL_OR_UNSAFE |

INCORRECT_OR_MISSING_SOURCES | NOT_HELPFUL | FACTUALLY_CORRECT |

MessageUsefulnessFeedback API Version 2023-11-27 480

Amazon Q Business API Reference

COMPLETE | RELEVANT_SOURCES | HELPFUL | NOT_BASED_ON_DOCUMENTS |

NOT_COMPLETE | NOT_CONCISE | OTHER

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

MessageUsefulnessFeedback API Version 2023-11-27 481

Amazon Q Business API Reference

MetadataEvent
Service: QBusiness

A metadata event for a AI-generated text output message in a Amazon Q Business conversation,
containing associated metadata generated.

Contents

conversationId

The identifier of the conversation with which the generated metadata is associated.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
finalTextMessage

The final text output message generated by the system.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
sourceAttributions

The source documents used to generate the conversation response.

Type: Array of SourceAttribution objects

Required: No
systemMessageId

The identifier of an Amazon Q Business AI generated message within the conversation.

Type: String

Length Constraints: Fixed length of 36.

MetadataEvent API Version 2023-11-27 482

Amazon Q Business API Reference

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
userMessageId

The identifier of an Amazon Q Business end user text input message within the conversation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

MetadataEvent API Version 2023-11-27 483

Amazon Q Business API Reference

NativeIndexConfiguration
Service: QBusiness

Configuration information for an Amazon Q Business index.

Contents

indexId

The identifier for the Amazon Q Business index.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: Yes
boostingOverride

Overrides the default boosts applied by Amazon Q Business to supported document attribute
data types.

Type: String to DocumentAttributeBoostingConfiguration object map

Map Entries: Maximum number of items.

Key Length Constraints: Minimum length of 1. Maximum length of 200.

Key Pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

NativeIndexConfiguration API Version 2023-11-27 484

Amazon Q Business API Reference

NativeIndexConfiguration API Version 2023-11-27 485

Amazon Q Business API Reference

NoAuthConfiguration
Service: QBusiness

Information about invoking a custom plugin without any authentication or authorization

requirement.

Contents

The members of this exception structure are context-dependent.

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

NoAuthConfiguration API Version 2023-11-27 486

Amazon Q Business API Reference

NumberAttributeBoostingConfiguration
Service: QBusiness

Provides information on boosting NUMBER type document attributes.

For more information on how boosting document attributes work in Amazon Q Business, see
Boosting using document attributes.

Contents

boostingLevel

Specifies the duration, in seconds, of a boost applies to a NUMBER type document attribute.

Type: String

Valid Values: NONE | LOW | MEDIUM | HIGH | VERY_HIGH

Required: Yes
boostingType

Specifies how much a document attribute is boosted.

Type: String

Valid Values: PRIORITIZE_LARGER_VALUES | PRIORITIZE_SMALLER_VALUES

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

NumberAttributeBoostingConfiguration API Version 2023-11-27 487

Amazon Q Business API Reference

OAuth2ClientCredentialConfiguration
Service: QBusiness

Information about the OAuth 2.0 authentication credential/token used to configure a plugin.

Contents

roleArn

The ARN of an IAM role used by Amazon Q Business to access the OAuth 2.0 authentication
credentials stored in a Secrets Manager secret.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: Yes
secretArn

The ARN of the Secrets Manager secret that stores the OAuth 2.0 credentials/token used for
plugin configuration.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2

OAuth2ClientCredentialConfiguration API Version 2023-11-27 488

Amazon Q Business API Reference

• AWS SDK for Ruby V3

OAuth2ClientCredentialConfiguration API Version 2023-11-27 489

Amazon Q Business API Reference

PersonalizationConfiguration
Service: QBusiness

Configuration information about chat response personalization. For more information, see
Personalizing chat responses.

Contents

personalizationControlMode

An option to allow Amazon Q Business to customize chat responses using user specific
metadata—specifically, location and job information—in your IAM Identity Center instance.

Type: String

Valid Values: ENABLED | DISABLED

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

PersonalizationConfiguration API Version 2023-11-27 490

Amazon Q Business API Reference

Plugin
Service: QBusiness

Information about an Amazon Q Business plugin and its configuration.

Contents

buildStatus

The status of the plugin.

Type: String

Valid Values: READY | CREATE_IN_PROGRESS | CREATE_FAILED |

UPDATE_IN_PROGRESS | UPDATE_FAILED | DELETE_IN_PROGRESS | DELETE_FAILED

Required: No
createdAt

The timestamp for when the plugin was created.

Type: Timestamp

Required: No
displayName

The name of the plugin.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
pluginId

The identifier of the plugin.

Type: String

Plugin API Version 2023-11-27 491

Amazon Q Business API Reference

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: No
serverUrl

The plugin server URL used for configuration.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$

Required: No
state

The current status of the plugin.

Type: String

Valid Values: ENABLED | DISABLED

Required: No
type

The type of the plugin.

Type: String

Valid Values: SERVICE_NOW | SALESFORCE | JIRA | ZENDESK | CUSTOM

Required: No
updatedAt

The timestamp for when the plugin was last updated.

Type: Timestamp

Required: No

Plugin API Version 2023-11-27 492

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Plugin API Version 2023-11-27 493

Amazon Q Business API Reference

PluginAuthConfiguration
Service: QBusiness

Authentication configuration information for an Amazon Q Business plugin.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

basicAuthConfiguration

Information about the basic authentication credentials used to configure a plugin.

Type: BasicAuthConfiguration object

Required: No
noAuthConfiguration

Information about invoking a custom plugin without any authentication.

Type: NoAuthConfiguration object

Required: No
oAuth2ClientCredentialConfiguration

Information about the OAuth 2.0 authentication credential/token used to configure a plugin.

Type: OAuth2ClientCredentialConfiguration object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

PluginAuthConfiguration API Version 2023-11-27 494

Amazon Q Business API Reference

• AWS SDK for Java V2

• AWS SDK for Ruby V3

PluginAuthConfiguration API Version 2023-11-27 495

Amazon Q Business API Reference

PluginConfiguration
Service: QBusiness

Configuration information required to invoke chat in PLUGIN_MODE.

For more information, see Admin controls and guardrails, Plugins, and Conversation settings.

Contents

pluginId

The identifier of the plugin you want to use.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

PluginConfiguration API Version 2023-11-27 496

Amazon Q Business API Reference

Principal
Service: QBusiness

Provides user and group information used for filtering documents to use for generating Amazon Q
Business conversation responses.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

group

The group associated with the principal.

Type: PrincipalGroup object

Required: No
user

The user associated with the principal.

Type: PrincipalUser object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Principal API Version 2023-11-27 497

Amazon Q Business API Reference

PrincipalGroup
Service: QBusiness

Provides information about a group associated with the principal.

Contents

access

Provides information about whether to allow or deny access to the principal.

Type: String

Valid Values: ALLOW | DENY

Required: Yes
membershipType

The type of group.

Type: String

Valid Values: INDEX | DATASOURCE

Required: No
name

The name of the group.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

PrincipalGroup API Version 2023-11-27 498

Amazon Q Business API Reference

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

PrincipalGroup API Version 2023-11-27 499

Amazon Q Business API Reference

PrincipalUser
Service: QBusiness

Provides information about a user associated with a principal.

Contents

access

Provides information about whether to allow or deny access to the principal.

Type: String

Valid Values: ALLOW | DENY

Required: Yes
id

The identifier of the user.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: ^\P{C}*$

Required: No
membershipType

The type of group.

Type: String

Valid Values: INDEX | DATASOURCE

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

PrincipalUser API Version 2023-11-27 500

Amazon Q Business API Reference

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

PrincipalUser API Version 2023-11-27 501

Amazon Q Business API Reference

QAppsConfiguration
Service: QBusiness

Configuration information about Amazon Q Apps. (preview feature)

Contents

qAppsControlMode

Status information about whether end users can create and use Amazon Q Apps in the web
experience.

Type: String

Valid Values: ENABLED | DISABLED

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

QAppsConfiguration API Version 2023-11-27 502

Amazon Q Business API Reference

Retriever
Service: QBusiness

Summary information for the retriever used for your Amazon Q Business application.

Contents

applicationId

The identifier of the Amazon Q Business application using the retriever.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
displayName

The name of your retriever.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Required: No
retrieverId

The identifier of the retriever used by your Amazon Q Business application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
status

The status of your retriever.

Retriever API Version 2023-11-27 503

Amazon Q Business API Reference

Type: String

Valid Values: CREATING | ACTIVE | FAILED

Required: No
type

The type of your retriever.

Type: String

Valid Values: NATIVE_INDEX | KENDRA_INDEX

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Retriever API Version 2023-11-27 504

Amazon Q Business API Reference

RetrieverConfiguration
Service: QBusiness

Provides information on how the retriever used for your Amazon Q Business application is
configured.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

kendraIndexConfiguration

Provides information on how the Amazon Kendra index used as a retriever for your Amazon Q
Business application is configured.

Type: KendraIndexConfiguration object

Required: No
nativeIndexConfiguration

Provides information on how a Amazon Q Business index used as a retriever for your Amazon Q
Business application is configured.

Type: NativeIndexConfiguration object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

RetrieverConfiguration API Version 2023-11-27 505

Amazon Q Business API Reference

RetrieverConfiguration API Version 2023-11-27 506

Amazon Q Business API Reference

Rule
Service: QBusiness

Guardrail rules for an Amazon Q Business application. Amazon Q Business supports only one rule
at a time.

Contents

ruleType

The type of rule.

Type: String

Valid Values: CONTENT_BLOCKER_RULE | CONTENT_RETRIEVAL_RULE

Required: Yes
excludedUsersAndGroups

Users and groups to be excluded from a rule.

Type: UsersAndGroups object

Required: No
includedUsersAndGroups

Users and groups to be included in a rule.

Type: UsersAndGroups object

Required: No
ruleConfiguration

The configuration information for a rule.

Type: RuleConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No

Rule API Version 2023-11-27 507

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Rule API Version 2023-11-27 508

Amazon Q Business API Reference

RuleConfiguration
Service: QBusiness

Provides configuration information about a rule.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

contentBlockerRule

A rule for configuring how Amazon Q Business responds when it encounters a a blocked topic.

Type: ContentBlockerRule object

Required: No
contentRetrievalRule

Rules for retrieving content from data sources connected to a Amazon Q Business application
for a specific topic control configuration.

Type: ContentRetrievalRule object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

RuleConfiguration API Version 2023-11-27 509

Amazon Q Business API Reference

S3
Service: QBusiness

Information required for Amazon Q Business to find a specific file in an Amazon S3 bucket.

Contents

bucket

The name of the S3 bucket that contains the file.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 63.

Pattern: ^[a-z0-9][\.\-a-z0-9]{1,61}[a-z0-9]$

Required: Yes
key

The name of the file.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

S3 API Version 2023-11-27 510

Amazon Q Business API Reference

SamlConfiguration
Service: QBusiness

Provides the SAML 2.0 compliant identity provider (IdP) configuration information Amazon Q
Business needs to deploy a Amazon Q Business web experience.

Contents

metadataXML

The metadata XML that your IdP generated.

Type: String

Length Constraints: Minimum length of 1000. Maximum length of 10000000.

Pattern: ^.*$

Required: Yes
roleArn

The Amazon Resource Name (ARN) of an IAM role assumed by users when they authenticate
into their Amazon Q Business web experience, containing the relevant Amazon Q Business
permissions for conversing with Amazon Q Business.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1284.

Pattern: ^arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-
z0-9-\.]{0,63}:[^/].{0,1023}$

Required: Yes
userIdAttribute

The user attribute name in your IdP that maps to the user email.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: Yes

SamlConfiguration API Version 2023-11-27 511

Amazon Q Business API Reference

userGroupAttribute

The group attribute name in your IdP that maps to user groups.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

SamlConfiguration API Version 2023-11-27 512

Amazon Q Business API Reference

SnippetExcerpt
Service: QBusiness

Contains the relevant text excerpt from a source that was used to generate a citation text segment
in an Amazon Q Business chat response.

Contents

text

The relevant text excerpt from a source that was used to generate a citation text segment in an
Amazon Q chat response.

Type: String

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

SnippetExcerpt API Version 2023-11-27 513

Amazon Q Business API Reference

SourceAttribution
Service: QBusiness

The documents used to generate an Amazon Q Business web experience response.

Contents

citationNumber

The number attached to a citation in an Amazon Q Business generated response.

Type: Integer

Required: No
snippet

The content extract from the document on which the generated response is based.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
textMessageSegments

A text extract from a source document that is used for source attribution.

Type: Array of TextSegment objects

Required: No
title

The title of the document which is the source for the Amazon Q Business generated response.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
updatedAt

The Unix timestamp when the Amazon Q Business application was last updated.

SourceAttribution API Version 2023-11-27 514

Amazon Q Business API Reference

Type: Timestamp

Required: No
url

The URL of the document which is the source for the Amazon Q Business generated response.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

SourceAttribution API Version 2023-11-27 515

Amazon Q Business API Reference

StringAttributeBoostingConfiguration
Service: QBusiness

Provides information on boosting STRING type document attributes.

Note
For STRING and STRING_LIST type document attributes to be used for
boosting on the console and the API, they must be enabled for search using the
DocumentAttributeConfiguration object of the UpdateIndex API. If you haven't enabled
searching on these attributes, you can't boost attributes of these data types on either the
console or the API.

For more information on how boosting document attributes work in Amazon Q Business, see
Boosting using document attributes.

Contents

boostingLevel

Specifies how much a document attribute is boosted.

Type: String

Valid Values: NONE | LOW | MEDIUM | HIGH | VERY_HIGH

Required: Yes
attributeValueBoosting

Specifies specific values of a STRING type document attribute being boosted.

Type: String to string map

Map Entries: Maximum number of 10 items.

Key Length Constraints: Minimum length of 1. Maximum length of 2048.

Valid Values: LOW | MEDIUM | HIGH | VERY_HIGH

Required: No

StringAttributeBoostingConfiguration API Version 2023-11-27 516

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

StringAttributeBoostingConfiguration API Version 2023-11-27 517

Amazon Q Business API Reference

StringListAttributeBoostingConfiguration
Service: QBusiness

Provides information on boosting STRING_LIST type document attributes.

Note
For STRING and STRING_LIST type document attributes to be used for
boosting on the console and the API, they must be enabled for search using the
DocumentAttributeConfiguration object of the UpdateIndex API. If you haven't enabled
searching on these attributes, you can't boost attributes of these data types on either the
console or the API.

For more information on how boosting document attributes work in Amazon Q Business, see
Boosting using document attributes.

Contents

boostingLevel

Specifies how much a document attribute is boosted.

Type: String

Valid Values: NONE | LOW | MEDIUM | HIGH | VERY_HIGH

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

StringListAttributeBoostingConfiguration API Version 2023-11-27 518

Amazon Q Business API Reference

Tag
Service: QBusiness

A list of key/value pairs that identify an index, FAQ, or data source. Tag keys and values can consist
of Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.

Contents

key

The key for the tag. Keys are not case sensitive and must be unique for the Amazon Q Business
application or data source.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: Yes
value

The value associated with the tag. The value may be an empty string but it can't be null.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 256.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Tag API Version 2023-11-27 519

Amazon Q Business API Reference

TextDocumentStatistics
Service: QBusiness

Provides information about text documents in an index.

Contents

indexedTextBytes

The total size, in bytes, of the indexed documents.

Type: Long

Valid Range: Minimum value of 0.

Required: No
indexedTextDocumentCount

The number of text documents indexed.

Type: Integer

Valid Range: Minimum value of 0.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

TextDocumentStatistics API Version 2023-11-27 520

Amazon Q Business API Reference

TextInputEvent
Service: QBusiness

An input event for a end user message in an Amazon Q Business web experience.

Contents

userMessage

A user message in a text message input event.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 7000.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

TextInputEvent API Version 2023-11-27 521

Amazon Q Business API Reference

TextOutputEvent
Service: QBusiness

An output event for an AI-generated response in an Amazon Q Business web experience.

Contents

conversationId

The identifier of the conversation with which the text output event is associated.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
systemMessage

An AI-generated message in a TextOutputEvent.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
systemMessageId

The identifier of an AI-generated message in a TextOutputEvent.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
userMessageId

The identifier of an end user message in a TextOutputEvent.

TextOutputEvent API Version 2023-11-27 522

Amazon Q Business API Reference

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

TextOutputEvent API Version 2023-11-27 523

Amazon Q Business API Reference

TextSegment
Service: QBusiness

Provides information about a text extract in a chat response that can be attributed to a source
document.

Contents

beginOffset

The zero-based location in the response string where the source attribution starts.

Type: Integer

Required: No
endOffset

The zero-based location in the response string where the source attribution ends.

Type: Integer

Required: No
snippetExcerpt

The relevant text excerpt from a source that was used to generate a citation text segment in an
Amazon Q Business chat response.

Type: SnippetExcerpt object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

TextSegment API Version 2023-11-27 524

Amazon Q Business API Reference

TopicConfiguration
Service: QBusiness

The topic specific controls configured for an Amazon Q Business application.

Contents

name

A name for your topic control configuration.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,35}$

Required: Yes
rules

Rules defined for a topic configuration.

Type: Array of Rule objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: Yes
description

A description for your topic control configuration. Use this to outline how the large language
model (LLM) should use this topic control configuration.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 350.

Pattern: ^\P{C}*$

Required: No
exampleChatMessages

A list of example phrases that you expect the end user to use in relation to the topic.

TopicConfiguration API Version 2023-11-27 525

Amazon Q Business API Reference

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 5 items.

Length Constraints: Minimum length of 0. Maximum length of 350.

Pattern: ^\P{C}*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

TopicConfiguration API Version 2023-11-27 526

Amazon Q Business API Reference

UserAlias
Service: QBusiness

Aliases attached to a user id within an Amazon Q Business application.

Contents

userId

The identifier of the user id associated with the user aliases.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes
dataSourceId

The identifier of the data source that the user aliases are associated with.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No
indexId

The identifier of the index that the user aliases are associated with.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{35}$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

UserAlias API Version 2023-11-27 527

Amazon Q Business API Reference

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

UserAlias API Version 2023-11-27 528

Amazon Q Business API Reference

UsersAndGroups
Service: QBusiness

Provides information about users and groups associated with a topic control rule.

Contents

userGroups

The user groups associated with a topic control rule.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
userIds

The user ids associated with a topic control rule.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

UsersAndGroups API Version 2023-11-27 529

Amazon Q Business API Reference

ValidationExceptionField
Service: QBusiness

The input failed to meet the constraints specified by Amazon Q Business in a specified field.

Contents

message

A message about the validation exception.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes
name

The field name where the invalid entry was detected.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ValidationExceptionField API Version 2023-11-27 530

Amazon Q Business API Reference

WebExperience
Service: QBusiness

Provides information for an Amazon Q Business web experience.

Contents

createdAt

The Unix timestamp when the Amazon Q Business application was last updated.

Type: Timestamp

Required: No
defaultEndpoint

The endpoint URLs for your Amazon Q Business web experience. The URLs are unique and fully
hosted by AWS.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(https?|ftp|file)://([^\s]*)$

Required: No
status

The status of your Amazon Q Business web experience.

Type: String

Valid Values: CREATING | ACTIVE | DELETING | FAILED | PENDING_AUTH_CONFIG

Required: No
updatedAt

The Unix timestamp when your Amazon Q Business web experience was updated.

Type: Timestamp

Required: No

WebExperience API Version 2023-11-27 531

Amazon Q Business API Reference

webExperienceId

The identifier of your Amazon Q Business web experience.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

WebExperience API Version 2023-11-27 532

Amazon Q Business API Reference

WebExperienceAuthConfiguration
Service: QBusiness

Provides the authorization configuration information needed to deploy a Amazon Q Business web
experience to end users.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

samlConfiguration

Provides the SAML 2.0 compliant identity provider (IdP) configuration information Amazon Q
Business needs to deploy a Amazon Q Business web experience.

Type: SamlConfiguration object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

QApps
The following data types are supported by QApps:

• AppDefinition
• AppDefinitionInput

WebExperienceAuthConfiguration API Version 2023-11-27 533

Amazon Q Business API Reference

• AttributeFilter
• Card
• CardInput
• CardStatus
• CardValue
• Category
• ConversationMessage
• DocumentAttribute
• DocumentAttributeValue
• FileUploadCard
• FileUploadCardInput
• LibraryItemMember
• PredictAppDefinition
• PredictQAppInputOptions
• QPluginCard
• QPluginCardInput
• QQueryCard
• QQueryCardInput
• TextInputCard
• TextInputCardInput
• UserAppItem

QApps API Version 2023-11-27 534

Amazon Q Business API Reference

AppDefinition
Service: QApps

The definition of the Q App, specifying the cards and flow.

Contents

appDefinitionVersion

The version of the app definition schema or specification.

Type: String

Required: Yes
cards

The cards that make up the Q App, such as text input, file upload, or query cards.

Type: Array of Card objects

Array Members: Minimum number of 0 items. Maximum number of 20 items.

Required: Yes
canEdit

A flag indicating whether the Q App's definition can be edited by the user.

Type: Boolean

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AppDefinition API Version 2023-11-27 535

Amazon Q Business API Reference

AppDefinitionInput
Service: QApps

The input for defining an Q App.

Contents

cards

The cards that make up the Q App definition.

Type: Array of CardInput objects

Array Members: Minimum number of 0 items. Maximum number of 20 items.

Required: Yes
initialPrompt

The initial prompt displayed when the Q App is started.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 10000.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AppDefinitionInput API Version 2023-11-27 536

Amazon Q Business API Reference

AttributeFilter
Service: QApps

The filter criteria used on responses based on document attributes or metadata fields.

Contents

andAllFilters

Performs a logical AND operation on all supplied filters.

Type: Array of AttributeFilter objects

Required: No
containsAll

Returns true when a document contains all the specified document attributes or metadata
fields. Supported for the following document attribute value types: stringListValue.

Type: DocumentAttribute object

Required: No
containsAny

Returns true when a document contains any of the specified document attributes or metadata
fields. Supported for the following document attribute value types: stringListValue.

Type: DocumentAttribute object

Required: No
equalsTo

Performs an equals operation on two document attributes or metadata fields. Supported for
the following document attribute value types: dateValue, longValue, stringListValue
and stringValue.

Type: DocumentAttribute object

Required: No

AttributeFilter API Version 2023-11-27 537

Amazon Q Business API Reference

greaterThan

Performs a greater than operation on two document attributes or metadata fields. Supported
for the following document attribute value types: dateValue and longValue.

Type: DocumentAttribute object

Required: No
greaterThanOrEquals

Performs a greater than or equals operation on two document attributes or metadata fields.
Supported for the following document attribute value types: dateValue and longValue.

Type: DocumentAttribute object

Required: No
lessThan

Performs a less than operation on two document attributes or metadata fields. Supported for
the following document attribute value types: dateValue and longValue.

Type: DocumentAttribute object

Required: No
lessThanOrEquals

Performs a less than or equals operation on two document attributes or metadata

fields.Supported for the following document attribute value type: dateValue and longValue.

Type: DocumentAttribute object

Required: No
notFilter

Performs a logical NOT operation on all supplied filters.

Type: AttributeFilter object

Required: No
orAllFilters

Performs a logical OR operation on all supplied filters.

AttributeFilter API Version 2023-11-27 538

Amazon Q Business API Reference

Type: Array of AttributeFilter objects

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

AttributeFilter API Version 2023-11-27 539

Amazon Q Business API Reference

Card
Service: QApps

A card representing a component or step in an Amazon Q App's flow.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

fileUpload

A container for the properties of the file upload card.

Type: FileUploadCard object

Required: No
qPlugin

A container for the properties of the plugin card.

Type: QPluginCard object

Required: No
qQuery

A container for the properties of the query card.

Type: QQueryCard object

Required: No
textInput

A container for the properties of the text input card.

Type: TextInputCard object

Required: No

Card API Version 2023-11-27 540

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Card API Version 2023-11-27 541

Amazon Q Business API Reference

CardInput
Service: QApps

The properties defining an input card in an Amazon Q App.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

fileUpload

A container for the properties of the file upload input card.

Type: FileUploadCardInput object

Required: No
qPlugin

A container for the properties of the plugin input card.

Type: QPluginCardInput object

Required: No
qQuery

A container for the properties of the query input card.

Type: QQueryCardInput object

Required: No
textInput

A container for the properties of the text input card.

Type: TextInputCardInput object

Required: No

CardInput API Version 2023-11-27 542

Amazon Q Business API Reference

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

CardInput API Version 2023-11-27 543

Amazon Q Business API Reference

CardStatus
Service: QApps

The current status and value of a card in an active Amazon Q App session.

Contents

currentState

The current state of the card.

Type: String

Valid Values: IN_PROGRESS | WAITING | COMPLETED

Required: Yes
currentValue

The current value or result associated with the card.

Type: String

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

CardStatus API Version 2023-11-27 544

Amazon Q Business API Reference

CardValue
Service: QApps

The value or result associated with a card in a Amazon Q App session.

Contents

cardId

The unique identifier of the card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
value

The value or result associated with the card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 5000.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

CardValue API Version 2023-11-27 545

Amazon Q Business API Reference

Category
Service: QApps

A category used to classify and filter library items for Amazon Q Apps.

Contents

id

The unique identifier of the category.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
title

The title or name of the category.

Type: String

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

Category API Version 2023-11-27 546

Amazon Q Business API Reference

ConversationMessage
Service: QApps

A message in a conversation, used as input for generating an Amazon Q App definition.

Contents

body

The text content of the conversation message.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 7000.

Required: Yes
type

The type of the conversation message.

Type: String

Valid Values: USER | SYSTEM

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

ConversationMessage API Version 2023-11-27 547

Amazon Q Business API Reference

DocumentAttribute
Service: QApps

A document attribute or metadata field.

Contents

name

The identifier for the attribute.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: [a-zA-Z0-9_][a-zA-Z0-9_-]*

Required: Yes
value

The value of the attribute.

Type: DocumentAttributeValue object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttribute API Version 2023-11-27 548

Amazon Q Business API Reference

DocumentAttributeValue
Service: QApps

The value of a document attribute. You can only provide one value for a document attribute.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

dateValue

A date expressed as an ISO 8601 string.

It's important for the time zone to be included in the ISO 8601 date-time format. For example,
2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at
12:30PM (plus 10 seconds) in Central European Time.

Type: Timestamp

Required: No
longValue

A long integer value.

Type: Long

Required: No
stringListValue

A list of strings.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

DocumentAttributeValue API Version 2023-11-27 549

Amazon Q Business API Reference

stringValue

A string.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

DocumentAttributeValue API Version 2023-11-27 550

Amazon Q Business API Reference

FileUploadCard
Service: QApps

A card in an Amazon Q App that allows the user to upload a file.

Contents

dependencies

Any dependencies or requirements for the file upload card.

Type: Array of strings

Required: Yes
id

The unique identifier of the file upload card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
title

The title of the file upload card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

Required: Yes

FileUploadCard API Version 2023-11-27 551

Amazon Q Business API Reference

allowOverride

A flag indicating if the user can override the default file for the upload card.

Type: Boolean

Required: No
fileId

The unique identifier of the file associated with the card.

Type: String

Required: No
filename

The name of the file being uploaded.

Type: String

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

FileUploadCard API Version 2023-11-27 552

Amazon Q Business API Reference

FileUploadCardInput
Service: QApps

Represents a file upload card. It can optionally receive a filename and fileId to set a default
file. If not received, the user must provide the file when the Q App runs.

Contents

id

The unique identifier of the file upload card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
title

The title or label of the file upload card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

Required: Yes
allowOverride

A flag indicating if the user can override the default file for the upload card.

Type: Boolean

Required: No

FileUploadCardInput API Version 2023-11-27 553

Amazon Q Business API Reference

fileId

The identifier of a pre-uploaded file associated with the card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: No
filename

The default filename to use for the file upload card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

FileUploadCardInput API Version 2023-11-27 554

Amazon Q Business API Reference

LibraryItemMember
Service: QApps

A library item is a snapshot of an Amazon Q App that can be published so the users in their
Amazon Q Apps library can discover it, clone it, and run it.

Contents

appId

The unique identifier of the Q App associated with the library item.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
appVersion

The version of the Q App associated with the library item.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

Required: Yes
categories

The categories associated with the library item.

Type: Array of Category objects

Array Members: Minimum number of 0 items. Maximum number of 3 items.

Required: Yes
createdAt

The date and time the library item was created.

Type: Timestamp

Required: Yes

LibraryItemMember API Version 2023-11-27 555

Amazon Q Business API Reference

createdBy

The user who created the library item.

Type: String

Required: Yes
libraryItemId

The unique identifier of the library item.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
ratingCount

The number of ratings the library item has received.

Type: Integer

Required: Yes
status

The status of the library item.

Type: String

Required: Yes
isRatedByUser

Whether the current user has rated the library item.

Type: Boolean

Required: No
updatedAt

The date and time the library item was last updated.

Type: Timestamp

LibraryItemMember API Version 2023-11-27 556

Amazon Q Business API Reference

Required: No
updatedBy

The user who last updated the library item.

Type: String

Required: No
userCount

The number of users who have the associated Q App.

Type: Integer

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

LibraryItemMember API Version 2023-11-27 557

Amazon Q Business API Reference

PredictAppDefinition
Service: QApps

The definition of an Amazon Q App generated based on input such as a conversation or problem
statement.

Contents

appDefinition

The definition specifying the cards and flow of the generated Q App.

Type: AppDefinitionInput object

Required: Yes
title

The title of the generated Q App definition.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
description

The description of the generated Q App definition.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2

PredictAppDefinition API Version 2023-11-27 558

Amazon Q Business API Reference

• AWS SDK for Ruby V3

PredictAppDefinition API Version 2023-11-27 559

Amazon Q Business API Reference

PredictQAppInputOptions
Service: QApps

The input options for generating an Q App definition.

Contents

Important
This data type is a UNION, so only one of the following members can be specified when
used or returned.

conversation

A conversation to use as input for generating the Q App definition.

Type: Array of ConversationMessage objects

Array Members: Minimum number of 1 item. Maximum number of 25 items.

Required: No
problemStatement

A problem statement to use as input for generating the Q App definition.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 10000.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

PredictQAppInputOptions API Version 2023-11-27 560

Amazon Q Business API Reference

PredictQAppInputOptions API Version 2023-11-27 561

Amazon Q Business API Reference

QPluginCard
Service: QApps

A card in an Q App that integrates with a third-party plugin or service.

Contents

dependencies

Any dependencies or requirements for the plugin card.

Type: Array of strings

Required: Yes
id

The unique identifier of the plugin card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
pluginId

The unique identifier of the plugin used by the card.

Type: String

Required: Yes
pluginType

The type or category of the plugin used by the card.

Type: String

Valid Values: SERVICE_NOW | SALESFORCE | JIRA | ZENDESK | CUSTOM

Required: Yes
prompt

The prompt or instructions displayed for the plugin card.

QPluginCard API Version 2023-11-27 562

Amazon Q Business API Reference

Type: String

Length Constraints: Minimum length of 0. Maximum length of 7000.

Required: Yes
title

The title or label of the plugin card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

QPluginCard API Version 2023-11-27 563

Amazon Q Business API Reference

QPluginCardInput
Service: QApps

The input shape for defining a plugin card in an Amazon Q App.

Contents

id

The unique identifier of the plugin card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
pluginId

The unique identifier of the plugin used by the card.

Type: String

Length Constraints: Fixed length of 36.

Required: Yes
prompt

The prompt or instructions displayed for the plugin card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 7000.

Required: Yes
title

The title or label of the plugin card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

QPluginCardInput API Version 2023-11-27 564

Amazon Q Business API Reference

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

Required: Yes

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

QPluginCardInput API Version 2023-11-27 565

Amazon Q Business API Reference

QQueryCard
Service: QApps

A card in a Amazon Q App that generates a response based on the Amazon Q Business service.

Contents

dependencies

Any dependencies or requirements for the query card.

Type: Array of strings

Required: Yes
id

The unique identifier of the query card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
outputSource

The source or type of output generated by the query card.

Type: String

Valid Values: approved-sources | llm

Required: Yes
prompt

The prompt or instructions displayed for the query card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 7000.

Required: Yes

QQueryCard API Version 2023-11-27 566

Amazon Q Business API Reference

title

The title or label of the query card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

Required: Yes
attributeFilter

The Amazon Q Business filters applied in this query card when resolving data sources

Type: AttributeFilter object

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

QQueryCard API Version 2023-11-27 567

Amazon Q Business API Reference

QQueryCardInput
Service: QApps

The input shape for defining a query card in an Amazon Q App.

Contents

id

The unique identifier of the query card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
prompt

The prompt or instructions displayed for the query card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 7000.

Required: Yes
title

The title or label of the query card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

QQueryCardInput API Version 2023-11-27 568

Amazon Q Business API Reference

Required: Yes
attributeFilter

Turns on filtering of responses based on document attributes or metadata fields.

Type: AttributeFilter object

Required: No
outputSource

The source or type of output to generate for the query card.

Type: String

Valid Values: approved-sources | llm

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

QQueryCardInput API Version 2023-11-27 569

Amazon Q Business API Reference

TextInputCard
Service: QApps

A card in an Amazon Q App that allows the user to input text.

Contents

dependencies

Any dependencies or requirements for the text input card.

Type: Array of strings

Required: Yes
id

The unique identifier of the text input card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
title

The title or label of the text input card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

Required: Yes

TextInputCard API Version 2023-11-27 570

Amazon Q Business API Reference

defaultValue

The default value to pre-populate in the text input field.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Required: No
placeholder

The placeholder text to display in the text input field.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

TextInputCard API Version 2023-11-27 571

Amazon Q Business API Reference

TextInputCardInput
Service: QApps

The input shape for defining a text input card in an Amazon Q App.

Contents

id

The unique identifier of the text input card.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
title

The title or label of the text input card.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
type

The type of the card.

Type: String

Valid Values: text-input | q-query | file-upload | q-plugin

Required: Yes
defaultValue

The default value to pre-populate in the text input field.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

TextInputCardInput API Version 2023-11-27 572

Amazon Q Business API Reference

Required: No
placeholder

The placeholder text to display in the text input field.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

TextInputCardInput API Version 2023-11-27 573

Amazon Q Business API Reference

UserAppItem
Service: QApps

An Amazon Q App associated with a user, either owned by the user or favorited.

Contents

appArn

The Amazon Resource Name (ARN) of the Q App.

Type: String

Required: Yes
appId

The unique identifier of the Q App.

Type: String

Pattern: [\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}

Required: Yes
createdAt

The date and time the user's association with the Q App was created.

Type: Timestamp

Required: Yes
title

The title of the Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Required: Yes
canEdit

A flag indicating whether the user can edit the Q App.

UserAppItem API Version 2023-11-27 574

Amazon Q Business API Reference

Type: Boolean

Required: No
description

The description of the Q App.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Required: No
status

The status of the user's association with the Q App.

Type: String

Required: No

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the
following:

• AWS SDK for C++

• AWS SDK for Java V2
• AWS SDK for Ruby V3

UserAppItem API Version 2023-11-27 575

Amazon Q Business API Reference

Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4
requests with a query string. Any action-specific parameters are listed in the topic for that action.
For more information about Signature Version 4, see Signing AWS API requests in the IAM User
Guide.

Action

The action to be performed.

Type: string

Required: Yes
Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string

Required: Yes
X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query
string instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: Conditional
X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region
you are targeting, the service you are requesting, and a termination string ("aws4_request").
The value is expressed in the following format: access_key/YYYYMMDD/region/service/
aws4_request.

API Version 2023-11-27 576

Amazon Q Business API Reference

For more information, see Create a signed AWS API request in the IAM User Guide.

Condition: Specify this parameter when you include authentication information in a query
string instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is not
required. When X-Amz-Date is used, it always overrides the value of the Date header. For more
information, see Elements of an AWS API request signature in the IAM User Guide.

Type: string

Required: Conditional
X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service
(AWS STS). For a list of services that support temporary security credentials from AWS STS, see
AWS services that work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from AWS STS, you must include the
security token.

Type: string

Required: Conditional
X-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.

Condition: Specify this parameter when you include authentication information in a query
string instead of in the HTTP authorization header.

API Version 2023-11-27 577

Amazon Q Business API Reference

Type: string

Required: Conditional
X-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Create a signed AWS API request in the IAM
User Guide.

Condition: Specify this parameter when you include authentication information in a query
string instead of in the HTTP authorization header.

Type: string

Required: Conditional

API Version 2023-11-27 578

Amazon Q Business API Reference

Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an
API action for this service, see the topic for that API action.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

ExpiredTokenException

The security token included in the request is expired

HTTP Status Code: 403

IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 403

InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

MalformedHttpRequestException

Problems with the request at the HTTP level, e.g. we can't decompress the body according to
the decompression algorithm specified by the content-encoding.

HTTP Status Code: 400

NotAuthorized

You do not have permission to perform this action.

HTTP Status Code: 401

OptInRequired

The AWS access key ID needs a subscription for the service.

API Version 2023-11-27 579

Amazon Q Business API Reference

HTTP Status Code: 403

RequestAbortedException

Convenient exception that can be used when a request is aborted before a reply is sent back
(e.g. client closed connection).

HTTP Status Code: 400

RequestEntityTooLargeException

Problems with the request at the HTTP level. The request entity is too large.

HTTP Status Code: 413

RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or
more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the
date stamp on the request is more than 15 minutes in the future.

HTTP Status Code: 400

RequestTimeoutException

Problems with the request at the HTTP level. Reading the Request timed out.

HTTP Status Code: 408

ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400

UnrecognizedClientException

The X.509 certificate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403

API Version 2023-11-27 580

Amazon Q Business API Reference

UnknownOperationException

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 404

ValidationError

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

API Version 2023-11-27 581