# API reference for Amazon Q Business
API reference

For information on Amazon Q Business APIs, see the [Amazon Q Business API reference](https://docs.aws.amazon.com/amazonq/latest/api-reference/Welcome.html).

For information about the IAM access control permissions you need to use this API, see [IAM roles for Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html) 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html)*
+ *[Amazon Q Business CLI Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/qbusiness/index.html)*
+ *[AWS General Reference](https://docs.aws.amazon.com/general/latest/gr/amazonq.html)*

The following pages list Amazon Q Business API actions categorized according to functionality. Links are provided to console procedures and CLI code examples within this User Guide, along with links to corresponding operations in the *Amazon Q Business API Reference*.

**Topics**
+ [

# Creating an Amazon Q Business application using APIs
](application-api.md)
+ [

# Creating an Amazon Q Business index using APIs
](index-api.md)
+ [

# Creating a retriever for an Amazon Q Business application using APIs
](retriever-api.md)
+ [

# Connecting an Amazon Q Business data source using APIs
](datasource-apis.md)
+ [

# Upload documents directly into a Amazon Q Business application using APIs
](document-upload-api.md)
+ [

# GetDocumentContent Output Schema
](document-content-schema.md)
+ [

# Creating and customizing an Amazon Q Business web experience using APIs
](web-experience-api.md)
+ [

# Chat and conversation management for an Amazon Q Business application using APIs
](conversation-api.md)
+ [

# Managing users and groups for an Amazon Q Business application using APIs
](user-group-management-api.md)
+ [

# Managing subscriptions for an Amazon Q Business application using APIs
](subscription-management-api.md)
+ [

# Creating Amazon Q Business plugins using APIs
](plugin-apis.md)
+ [

# Managing admin controls and guardrails using APIs
](guardrails-api.md)
+ [

# User feedback using Amazon Q Business APIs
](feedback-api.md)

# Creating an Amazon Q Business application using APIs
Creating an application

All Amazon Q Business application environment actions are supported both on the console and using APIs.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreateApplication](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html) | Creates an Amazon Q Business application | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/application-api.html) | 
| [DeleteApplication](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteApplication.html) | Deletes an Amazon Q Business application | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/application-api.html) | 
| [GetApplication](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetApplication.html) | Gets information about an existing Amazon Q Business application | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/application-api.html) | 
| [ListApplications](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListApplication.html) | Lists existing Amazon Q Business applications | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/application-api.html) | 
| [UpdateApplication](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateApplication.html) | Updates an existing Amazon Q Business application | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/application-api.html) | 

# Creating an Amazon Q Business index using APIs
Creating an index

All Amazon Q Business index actions are supported both on the console and using APIs.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreateIndex](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateIndex.html) | Creates an Amazon Q Business index | [Creating an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html) | 
| [DeleteIndex](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteIndex.html) | Deletes an Amazon Q Business index | [Deleting an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-native-retriever-actions.html#delete-native-retriever) | 
| [GetIndex](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetIndex.html) | Gets information about an existing Amazon Q Business index | [Getting properties of an Amazon Q Business index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-native-retriever-actions.html#describe-native-retriever) | 
| [ListIndices](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListIndices.html) | Lists existing Amazon Q Business indices | [Listing properties of an Amazon Q Business index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-native-retriever-actions.html#list-native-retriever) | 
| [UpdateIndex](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) | Updates an existing Amazon Q Business index | [Updating an Amazon Q Business index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-native-retriever-actions.html#update-native-retriever) | 

# Creating a retriever for an Amazon Q Business application using APIs
Creating a retriever

You can't create an Amazon Q Business retriever using the AWS Management Console. If you use the console, Amazon Q Business creates a retriever for you when you create an Amazon Q Business index. If you're using an Amazon Kendra index as retriever, adding an Amazon Kendra index will also add a retriever. 

**Note**  
You can only add an Amazon Kendra index as retriever if you have existing Amazon Kendra indexes.

When you use the APIs, you must create a retriever for your Amazon Q Business index separately.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreateRetriever](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateRetriever.html) | Creates an Amazon Q Business or Amazon Kendra retriever | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/retriever-api.html) | 
| [DeleteRetriever](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteRetriever.html) | Deletes an Amazon Q Business or Amazon Kendra retriever | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/retriever-api.html) | 
| [GetRetriever](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetRetriever.html) | Gets information about an existing Amazon Q Business or Amazon Kendra retriever | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/retriever-api.html) | 
| [ListRetrievers](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListRetrievers.html) | Lists existing Amazon Q Business or Amazon Kendra retrievers | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/retriever-api.html) | 
| [UpdateRetriever](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateRetriever.html) | Updates an existing Amazon Q Business or Amazon Kendra retriever | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/retriever-api.html) | 

# Connecting an Amazon Q Business data source using APIs
Connecting a data source

Amazon Q Business supports data source connector configuration through both the console and the APIs.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) | Creates and connects Amazon Q Business data source | [Configuring Amazon Q Business data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-sources.html) | 
| [DeleteDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteDataSource.html) | Deletes an Amazon Q Business data source | [Deleting a data source connector](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#delete-datasource) | 
| [GetDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetDataSource.html) | Gets information about an existing Amazon Q Business data source | [Getting data source connector properties](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#describe-datasource) | 
| [ListDataSources](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListDataSources.html) | Lists existing Amazon Q Business data sources | [Listing data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#list-datasources) | 
| [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) | Updates an existing Amazon Q Business data source | [Updating data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#update-datasources) | 
| [StartDataSourceSyncJobs](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_StartDataSourceSyncJobs.html) | Starts an Amazon Q Business data source sync job | [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs) | 
| [StopDataSourceSyncJobs](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_StopDataSourceSyncJobs.html) | Stops an Amazon Q Business data source sync job | [Stopping data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#end-datasource-sync-jobs) | 
| [ListDataSourceSyncJobs](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListDataSourceSyncJobs.html) | Lists data source sync jobs | [Listing data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#list-datasource-sync-jobs) | 

# Upload documents directly into a Amazon Q Business application using APIs
Upload documents directly

Amazon Q Business supports direct document uploads into an Amazon Q Business index using both the console and the APIs.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [BatchPutDocument](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html) | Adds one or more documents to an Amazon Q Business index | [Upload documents](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/upload-docs.html) | 
| [BatchDeleteDocument](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html) | Asynchronously deletes one or more documents added using the BatchPutDocument API from an Amazon Q Business index | [Deleting uploaded documents](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/delete-doc-upload.html) | 

# GetDocumentContent Output Schema
GetDocumentContent Output Schema

When you use the [GetDocumentContent](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetDocumentContent.html) API with `outputFormat` set to `EXTRACTED`, the response returns extracted text content in JSON format. The output schema is presented in JSON format:

```
{
   // always V1 for now
   schemaVersionId: string;
   
   // always JSON for now
   outputFormat: string;
   
   // content for plain-text documents
   plainTextDocumentContent: string;
   
   // content for non-plaintext documents such as PDF, DOCX, PPTX, Audio, Video
   nonPlainTextDocumentContent: List<ExtractedDocumentBodyElement>;
}
```

The schema for non-plaintext documents includes the `ExtractedDocumentBodyElement` which includes:

```
{
   text: string;
   
  // Allowed values: TEXT, ARTICLE, SECTION, DIV, IMAGE_DESCRIPTION, CODE,
  // TABLE, LIST, URL, HEADER, FOOTER, FORM, MENU, AUDIO, VIDEO
   elementType: string;
   
   horizontalHeaderIndex: integer;
   verticalHeaderIndex: integer;
   htmlDocumentTitle: string;
   sectionTitle: string;
   sectionBody: string;
   tableCaption: string;
   tableFooter: string;
   tableRowHeaders: List<List<string>>;
   tableColumnHeaders: List<List<string>>;
   tableRows: List<List<string>>;
   tableRowsCount: integer;
   tableColumnsCount: integer;
   tableId: string;
   
   tokens: List<struct>;
   {
        value: string;
        startOffsets: integer;
        endOffsets: integer;
   }
   
   tableType: string;
   tableSummary: string;
   
   columnInfoList: List<struct>;
   {
        columnName: string;
        columnSummary: string;
        columnType: string;
        columnRepresentativeValues: List<string>
   }
   
   // Audio/Video specific fields below
   overallSummary: string;
   
   audioSummaryList: List<struct>;
   {
        summaryText: string;
        startTimeMilliseconds: string;
        endTimeMilliseconds: string;
   }
   
   videoSummaryList: List<struct>;
   {
        summaryText: string;
        startTimeMilliseconds: string;
        endTimeMilliseconds: string;
   }
   
   audioTranscriptList: List<struct>;
   {
        transcriptText: string;
        startTimeMilliseconds: string;
        endTimeMilliseconds: string;
   }
   
   videoTranscriptList: List<struct>;
   {
        transcriptText: string;
        startTimeMilliseconds: string;
        endTimeMilliseconds: string;
   }   
}
```

## Example Output
Example Output

### Plaintext Document Example


For plaintext documents, the extracted content is returned in the `plainTextDocumentContent` field:

```
{
  "schemaVersionId": "V1",
  "outputFormat": "JSON",
  "plainTextDocumentContent": "This is the extracted text content from a plain text document."
}
```

# Creating and customizing an Amazon Q Business web experience using APIs
Creating a web experience

If you use the console to create your Amazon Q Business application, a web experience is created automatically and connected to your chosen data source.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html) | Creates an Amazon Q Business web experience | [Creating a web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#create-experience) | 
| [DeleteWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteWebExperience.html) | Deletes an Amazon Q Business web experience | [Deleting an Amazon Q Business web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#delete-web-experience) | 
| [GetWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetWebExperience.html) | Gets information about an Amazon Q Business web experience | [Getting Amazon Q Business web experience properties](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#describe-web-experience) | 
| [ListWebExperiences](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListWebExperiences.html) | Lists Amazon Q Business web experiences | [Listing Amazon Q Business web experiences](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#list-web-experiences) | 
| [UpdateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateWebExperience.html) | Updates an Amazon Q Business web experience | [Updating an Amazon Q Business web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#update-web-experience) | 

# Chat and conversation management for an Amazon Q Business application using APIs
Chat and conversation management

Chatting in an Amazon Q Business web experience preview and a deployed Amazon Q Business web experience uses the following API operations.

**Important**  
Amazon Q Business Chat and ChatSync APIs are intended to be activated by end user interactions, not programmatic access. To protect availability, requests exceeding normal user patterns may be throttled. If throttling occurs, first wait and retry later as it is often temporary. However, if throttling persists—or if you believe the throttling is in error—contact AWS Support for troubleshooting assistance.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [Chat](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Chat.html) | Starts or continues a streaming Amazon Q Business conversation  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/conversation-api.html) | 
| [ChatSync](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ChatSync.html) | Starts or continues a non-streaming Amazon Q Business conversation | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/conversation-api.html) | 
| [DeleteConversation](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteConversation.html) | Deletes an Amazon Q Business web experience conversation | [Conversation management](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-web-experience.html#conversation-mgmt) | 
| [ListConversations](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListConversations.html) | Lists conversations in an Amazon Q Business web experience | [Conversation management](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-web-experience.html#conversation-mgmt) | 
| [ListMessages](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListMessages.html) | Lists messages in an Amazon Q Business web experience | [Using Amazon Q Business web experiences](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-web-experience.html) | 

This section outlines how to use Amazon Q Business APIs to make authenticated API calls, and how to configure a streaming chat conversation.

**Topics**
+ [

## Setting up a streaming Amazon Q Business chat using APIs
](#chat-stream-api)

## Setting up a streaming Amazon Q Business chat using APIs
Setting up a streaming chat

Amazon Q Business provides a streaming [Chat](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Chat.html) API that you can use to deliver chat responses to your end users as a continuing series of partial results. When you use the streaming API, chat responses are transmitted using sequential data packets.

You can configure streaming for your Amazon Q Business application environment in two ways: using WebSockets directly, or using an AWS SDK. The information in this section can be used to for both methods.

If you use WebSockets to configure streaming, a secure WebSockets connection is created to a [supported Amazon Q Business endpoint](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quotas-regions.html#regions). An example endpoint may look like this: *wss://qbusiness-websocket.us-west-2.api.aws:443/chat*.

**Important**  
We strongly recommend using SDKs to configure streaming instead of using WebSockets directly. SDKs are the simplest and most reliable method for chat streams. To start streaming using an AWS SDK, see [Chat](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Chat.html) in the Amazon Q Business API Reference.

**Note**  
The `qbusiness.<region>.api.aws:8443` has been deprecated in favor of qbusiness-websocket. Use the `qbusiness-websocket.<region>.api.aws:443` endpoint. Although the `qbusiness.<region>.api.aws:8443` endpoint will continue to work it, we recommend using—or migrating to—the new endpoint.

**Topics**
+ [

### Setting up a WebSocket stream
](#setting-up-websocket)
+ [

### Handling WebSocket streaming errors
](#websocket-errors)
+ [

### Event stream encoding
](#streaming-event-stream)
+ [

### Data frames
](#streaming-data-frames)

### Setting up a WebSocket stream


The key components for a [WebSocket protocol](https://datatracker.ietf.org/doc/html/rfc6455) for streaming requests with Amazon Q Business are:
+ The upgrade request. This contains the query parameters for your request, and a signature that Amazon Q Business uses as a seed signature.
+ One or more messages in event stream encoding that contain metadata and chat bytes.

The following section outlines the steps to set up your WebSocket stream.

1. Attach the following policy to the IAM role that makes the request. See [Adding IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policy-api) for more information.

------
#### [ JSON ]

****  

   ```
   {
   "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "MyQBusinessWebsocketPolicy",
                   "Effect": "Allow",
                   "Action": "qbusiness:Chat",
                   "Resource": "*"
           }
       ]
   }
   ```

------

1. To start the session, create a presigned URL in the following format. Line breaks have been added for readability.

   ```
   GET wss://qbusiness-websocket.us-west-2.api.aws:443/chat?
   &X-Amz-Algorithm=AWS4-HMAC-SHA256
   &X-Amz-Credential=access-key%2FYYYYMMDD%2Fus-west-2%2Fqbusiness-websocket%2Faws4_request
   &X-Amz-Date=YYYYMMDDTHHMMSSZ
   &X-Amz-Expires=300
   &X-Amz-Security-Token=security-token
   &X-Amz-Signature=string
   &X-Amz-SignedHeaders=host
   &chat-input={"applicationId":"application_id","userId":"test_user@amazon.com","userGroups":null,"clientToken":str(uuid.uuid4())}
   ```
**Note**  
The maximum value for `X-Amz-Expires` is 300 seconds (5 minutes).

   Additional operations and parameters are listed in the [API Reference](https://docs.aws.amazon.com/amazonq/latest/api-reference/Welcome.html); parameters common to all AWS API operations are listed in the [Common Parameters](https://docs.aws.amazon.com/amazonq/latest/api-reference/CommonParameters.html) section.

   To construct the URL for your request and create the [Signature Version 4 signature](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html), refer to the following steps. Examples are in pseudocode.

   1. Create a canonical request. A canonical request is a string that includes information from your request in a standardized format. This ensures that when AWS receives the request, it can calculate the same signature you created for your URL. For more information, see [Create a Canonical Request for Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html).

      ```
      # HTTP verb
      method = "GET"
      # Service name
      service = "qbusiness"
      # Region
      region = "us-west-2"
      # Amazon Q Business streaming endpoint
      endpoint = "wss://qbusiness-websocket.us-west-2.api.aws:443"
      # Host
      host = "qbusiness-websocket.us-west-2.api.aws"
      # Date and time of request
      amz-date = YYYYMMDDTHHMMSSZ
      # Date without time for credential scope
      datestamp = YYYYMMDD
      ```

   1. Create a canonical URI, which is the part of the URI between the domain and the query string.

      ```
      canonical_uri = "/chat"
      ```

   1. Create the canonical headers and signed headers. Note the trailing `\n` in the canonical headers.
      + Append the lowercase header name followed by a colon ( : ).
      + Append a comma-separated list of values for that header. Do not sort values in headers that have multiple values.
      + Append a new line (`\n`).

      ```
      canonical_headers = "host:" + host + "\n"
      signed_headers = "host"
      ```

   1. Match the algorithm to the hashing algorithm. Use `SHA-256`.

      ```
      algorithm = "AWS4-HMAC-SHA256"
      ```

   1. Create the credential scope, which scopes the derived key to the date, AWS Region, and service. For example, `20240415/us-west-2/qbusiness/aws4_request`.

      ```
      credential_scope = datestamp + "/" + region + "/" + service + "/" + "aws4_request"
      ```

   1. Create the canonical query string. Query string values must be URI-encoded and sorted by name.
      + Sort the parameter names by character code point in ascending order. Parameters with duplicate names should be sorted by value. For example, a parameter name that begins with the uppercase letter F precedes a parameter name that begins with the lowercase letter b.
      + Do not URI-encode any of the unreserved characters that RFC 3986 defines: A-Z, a-z, 0-9, hyphen ( - ), underscore ( \$1 ), period ( . ), and tilde ( \$1 ).
      + Percent-encode all other characters with %XY, where X and Y are hexadecimal characters (0-9 and uppercase A-F). For example, the space character must be encoded as %20 (don't include '\$1', as some encoding schemes do); extended UTF-8 characters must be in the form %XY%ZA%BC.
      + Double-encode any equals ( = ) characters in parameter values.

      ```
      canonical_querystring  = "X-Amz-Algorithm=" + algorithm
      canonical_querystring += "&X-Amz-Credential="+ access key + "%2F" + credential_scope
      canonical_querystring += "&X-Amz-Date=" + amz_date 
      canonical_querystring += "&X-Amz-Expires=300"
      canonical_querystring += "&X-Amz-Security-Token=" + URI-Encode(token, 'UTF-8', safe='')
      canonical_querystring += "&X-Amz-SignedHeaders=" + signed_headers
      chat_input_string = {
          "applicationId": "application_id",
          "userId": "testuser@amazon.com",
          "userGroups": None,
          "clientToken": str(uuid.uuid4()),
          "conversationId": None,
          "parentMessageId": None
      }
      canonical_querystring += "&" + "chat-input" + "=" + URI-Encode(json.dumps(chat_input_string), 'UTF-8')
      ```

   1. Create a hash of the payload. For a `GET` request, the payload is an empty string.

      ```
      payload_hash = HashSHA256(("").Encode("utf-8")).Digest()
      ```

   1. Combine the following elements to create the canonical request.

      ```
      canonical_request = method + '\n' 
         + canonical_uri + '\n' 
         + canonical_querystring + '\n' 
         + canonical_headers + '\n' 
         + signed_headers + '\n' 
         + payload_hash
                                          
       string_to_sign =  algorithm + '\n' 
         + amz_date + '\n' 
         + new_credential_scope + '\n' 
         + hashed_canonical_request
      ```

1. Create the string to sign, which contains meta information about your request. You use the string to sign in the next step when you calculate the request signature. For more information, see [Create a String to Sign for Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html).

   ```
   hashed_canonical_request = HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
   new_credential_scope = datestamp + '/' + region + '/qbusiness/aws4_request'
   string_to_sign=algorithm + "\n"
      + amz_date + "\n"
      + new_credential_scope + "\n"
      + HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
   ```

1. Calculate the signature. To do this, derive a signing key from your AWS secret access key. For a greater degree of protection, the derived key is specific to the date, service, and AWS Region. Use this derived key to sign the request. For more information, see [Calculate the Signature for AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4-calculate-signature.html).

   Make sure you implement the `GetSignatureKey` function to derive your signing key. If you have not yet derived a signing key, refer to [Examples of how to derive a signing key for Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-v4-examples.html).

   ```
   #Create the signing key
   signing_key = GetSignatureKey(secret_key, datestamp, region, service)
                   
   # Sign the string_to_sign using the signing key
   signature = HMAC.new(signing_key, (string_to_sign).Encode("utf-8"), Sha256()).HexDigest
   ```

   The function `HMAC(key, data)` represents an HMAC-SHA256 function that returns results in binary format.

1. Add signing information to the request and create the request URL.

   After you calculate the signature, add it to the query string. For more information, see [Add the Signature to the Request](https://docs.aws.amazon.com/general/latest/gr/sigv4-add-signature-to-request.html).

   First, add the authentication information to the query string.

   ```
   canonical_querystring += "&X-Amz-Signature=" + signature
   ```

   Second, create the URL for the request.

   ```
   request_url = endpoint + canonical_uri + "?" + canonical_querystring
   ```

   Use the request URL with your WebSocket library to make the request to Amazon Q Business.

1. The request to Amazon Q Business must include the following headers. Typically these headers are managed by your WebSocket client library.

   ```
   Host: qbusiness-websocketus-west-2.amazonaws.com 
   Connection: Upgrade
   Upgrade: websocket
   Origin: URI-of-WebSocket-client
   Sec-WebSocket-Version: 13
   Sec-WebSocket-Key: randomly-generated-string <calculated at runtime>
   ```

1. When Amazon Q Business receives your WebSocket request, it responds with a WebSocket upgrade response. Typically your WebSocket library manages this response and sets up a socket for communications with Amazon Q Business.

   The following is the response from Amazon Q Business. Line breaks have been added for readability.

   ```
   HTTP/1.1 101 WebSocket Protocol Handshake
   Connection: upgrade
   Upgrade: websocket
   websocket-origin: wss://qbusiness-websocket.us-west-2.api.aws:443/chat
   websocket-location: qbusiness-websocket.us-west-2.amazonaws.com/api.aws:443/chat?
   &X-Amz-Algorithm=AWS4-HMAC-SHA256
   &X-Amz-Credential=access-key%2FYYYYMMDD%2Fus-west-2%2Fqbusiness%2Faws4_request
   &X-Amz-Date=YYYYMMDDTHHMMSSZ
   &X-Amz-Expires=300
   &X-Amz-Security-Token=security_token
   &X-Amz-SignedHeaders=host
   &chat-input=%7B%22applicationId%22%3A%20%22aa419bef-ac4e-4c57-9224-f603e185ac09%22%2C%20%22userId%22%3A%20%testuser%40amazon.com%22%2C%20%22userGroups%22%3A%20null%2C%20%22clientToken%22%3A%20%2283eb07d9-193c-420c-97c6-f2f343d13591%22%2C%20%22conversationId%22%3A%20null%2C%20%22parentMessageId%22%3A%20null%7D
   &X-Amz-Signature=Signature Version 4 signature
   x-amzn-RequestId: RequestId
   sec-websocket-accept: hash-of-the-Sec-WebSocket-Key-header
   ```

1. Make your WebSocket streaming request.

   After the WebSocket connection is established, the client can start sending a sequence of chat frames, each encoded using event stream encoding.

   Each data frame contains three headers combined with a chunk of raw text bytes; the following table describes these headers.    
<a name="table-websocket-frame-diagram-event-headers"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/conversation-api.html)

1. To end the data stream, send an end of input event in an event stream encoded message.    
<a name="table-websocket-frame-response-headers"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/conversation-api.html)

   When you decode the binary response, you end up with a JSON structure containing the chat output.

### Handling WebSocket streaming errors


If an exception occurs while processing your request, Amazon Q Business responds with a terminal WebSocket frame containing an event stream encoded response. This response contains the headers described in the following table; the body of the response contains a descriptive error message.


| Header name byte length | Header name (string) | Header value type | Value string byte length | Value string (UTF-8) | 
| --- | --- | --- | --- | --- | 
| 13 | :content-type | 7 | 16 | application/json | 
| 15 | :exception-type | 7 | varies | varies, see below | 
| 13 | :message-type | 7 | 9 | exception | 

The `exception-type` header contains one of the following values:
+ `BadRequestException`: There was a client error when the stream was created, or an error occurred while streaming data. Make sure that your client is ready to accept data and try your request again.
+ `InternalFailureException`: Amazon Q Business had a problem during the handshake with the client. Try your request again.

Amazon Q Business can also return any of the common service errors. For a list, see [Common Errors](https://docs.aws.amazon.com/amazonq/latest/api-reference/CommonErrors.html).

### Event stream encoding


Amazon Q Business uses a format called event stream encoding for streaming chat.

Event stream encoding provides bidirectional communication between a client and a server. Chats sent to the Amazon Q Business service are encoded in this format. The response from Amazon Q Business also uses this encoding.

Each message consists of two sections: the prelude and the data. The prelude consists of:

1. The total byte length of the message

1. The combined byte length of all headers

The data section consists of:

1. Headers

1. Payload

Each section ends with a 4-byte big-endian integer cyclic redundancy check (CRC) checksum. The message CRC checksum is for both the prelude section and the data section. Amazon Q Business uses CRC32 (often referred to as GZIP CRC32) to calculate both CRCs. For more information about CRC32, see [https://www.ietf.org/rfc/rfc1952.txt](https://www.ietf.org/rfc/rfc1952.txt).

Total message overhead, including the prelude and both checksums, is 16 bytes.

The following diagram shows the components that make up a message and a header. There are multiple headers per message.

![\[A schematic of the components of a message and a header for a streaming transcription.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/frame-diagram-frame-overview.png)


Each message contains the following components:
+ **Prelude**: Consists of two, 4-byte fields, for a fixed total of 8 bytes.
  + *First 4 bytes*: The big-endian integer byte-length of the entire message, inclusive of this 4-byte length field.
  + *Second 4 bytes*: The big-endian integer byte-length of the 'headers' portion of the message, excluding the 'headers' length field itself.
+ **Prelude CRC**: The 4-byte CRC checksum for the prelude portion of the message, excluding the CRC itself. The prelude has a separate CRC from the message CRC. That ensures that Amazon Q Business can detect corrupted byte-length information immediately without causing errors, such as buffer overruns.
+ **Headers**: Metadata annotating the message; for example, message type and content type. Messages have multiple headers, which are key:value pairs, where the key is a UTF-8 string. Headers can appear in any order in the 'headers' portion of the message, and each header can appear only once.
+ **Payload**: The streaming chat content to be transcribed.
+ **Message CRC**: The 4-byte CRC checksum from the start of the message to the start of the checksum. That is, everything in the message except the CRC itself.

The header frame is the authorization frame for the streaming chat. Amazon Q Business uses the authorization header's value as the seed for generating a chain of authorization headers for the data frames in the request.

Each header contains the following components; there are multiple headers per frame.
+ **Header name byte-length**: The byte-length of the header name.
+ **Header name**: The name of the header that indicates the header type. For valid values, see the following frame descriptions.
+ **Header value type**: A number indicating the header value. The following list shows the possible values for the header and what they indicate.
  + `0` – TRUE
  + `1` – FALSE
  + `2` – BYTE
  + `3` – SHORT
  + `4` – INTEGER
  + `5` – LONG
  + `6` – BYTE ARRAY
  + `7` – STRING
  + `8` – TIMESTAMP
  + `9` – UUID
+ **Value string byte length**: The byte length of the header value string.
+ **Header value**: The value of the header string. Valid values for this field depend on the type of header.

### Data frames


Each streaming request contains one or more data frames. There are two steps to creating a data frame:

1. Combine raw `ChatInput` data with metadata to create the payload of your request.

1. Combine the payload with a signature to form the event message that is sent to Amazon Q Business.

# Managing users and groups for an Amazon Q Business application using APIs
User and group management

Amazon Q Business provides APIs to manage users and groups in your Amazon Q Business. You can't configure user management using the console—Amazon Q Business automatically invokes these API operations for you when you configure your data source connector connection. You can use these APIs to implement your own user and group management solution if you create a Amazon Q Business application environment programmatically.

**Note**  
As of Dec 17, 2024, Amazon Q Business will recognize all email addresses as case-insensitive and recognize subaddresses as equivalent to the original email address. For example, JohnDoe@example.com, johndoe@example.com, and johndoe\$1work@example.com will be considered the same email address. For assistance with applications or to report a concern, contact Support, sign into the [AWS Support Center](https://console.aws.amazon.com/support/home#/) .


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreateUser](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateUser.html) | Creates a universally unique identifier (UUID) mapped to a list of local user ids within an application | [User mapping](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html#user-mapping) | 
| [GetUser](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetUser.html) | Describes the universally unique identifier (UUID) associated with a local user in a data source | [User mapping](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html#user-mapping) | 
| [UpdateUser](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateUser.html) | Updates information associated with a user id | [User mapping](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html#user-mapping) | 
| [PutGroup](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutGroup.html) | Creates, or updates, a mapping of users to groups | [Group mapping](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html#group-mapping) | 
| [DeleteGroup](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteGrooup.html) | 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 | [Group mapping](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html#group-mapping) | 
| [GetGroup](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetGroup.html) | Describes a group by group name | [Group mapping](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html#group-mapping) | 
| [ListGroups](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListGroups.html) | Provides a list of groups that are mapped to users | [Group mapping](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html#group-mapping) | 

# Managing subscriptions for an Amazon Q Business application using APIs
Subscription management

Amazon Q Business provides APIs to manage subscriptions in your Amazon Q Business application. You can use these APIs to implement your own subscription management solution if you create a Amazon Q Business application environment programmatically.

**Note**  
As of Dec 17, 2024, Amazon Q Business will recognize all email addresses as case-insensitive and recognize subaddresses as equivalent to the original email address. For example, JohnDoe@example.com, johndoe@example.com, and johndoe\$1work@example.com will be considered the same email address. For assistance with applications or to report a concern, contact Support, sign into the [AWS Support Center](https://console.aws.amazon.com/support/home#/) .


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreateSubscription](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateSubscription.html) | Subscribes an IAM Identity Center user or a group to a pricing tier for an Amazon Q Business application  If you're using IAM federation to manage user and group access to Amazon Q Business, subscriptions are created automatically when a user logs in to their Amazon Q Business application.  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/subscription-management-api.html) | 
| [CancelSubscription](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CancelSubscription.html) | Unsubscribes a user or a group from their pricing tier in an Amazon Q Business application | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/subscription-management-api.html) | 
| [ListSubscriptions](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListSubscriptions.html) | Lists all subscriptions created in an Amazon Q Business application | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/subscription-management-api.html) | 
| [UpdateSubscription](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateSubscription.html) | Updates the pricing tier for an Amazon Q Business subscription | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/subscription-management-api.html) | 

# Creating Amazon Q Business plugins using APIs
Plugins

Amazon Q Business supports plugin creation through both the console and the APIs.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [CreatePlugin](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreatePlugin.html) | Creates an Amazon Q Business plugin | [Configuring plugins with Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html) | 
| [DeletePlugin](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeletePlugin.html) | Deletes an Amazon Q Business plugin | [Deleting a plugin](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugin-management.html#plugin-delete) | 
| [GetPlugin](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetPlugin.html) | Gets information about an existing Amazon Q Business plugin | [Getting plugin properties](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugin-management.html#plugin-properties) | 
| [UpdatePlugin](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdatePlugin.html) | Updates an Amazon Q Business plugin | [Updating a plugin](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugin-management.html#plugin-update) | 
| [ListPlugins](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPlugins.html) | Lists properties of an Amazon Q Business plugin | [Listing plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugin-management.html#plugin-list) | 
| [ListPluginActions](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginActions.html) | Lists configured Amazon Q Business actions for a specific plugin in an Amazon Q Business application. Returns empty responses for custom and legacy built-in plugins. | [Listing configured plugin actions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugin-management.html#plugin-list-actions) | 
| [ListPluginTypeActions](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginTypeActions.html) | Lists configured Amazon Q Business actions for any plugin type. Returns empty responses for custom and legacy built-in plugins. | [Listing available plugin actions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugin-management.html#plugin-list-actions-type) | 
| [ListPluginTypeMetadata](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListPluginTypeMetadata.html) | Lists metadata for all Amazon Q Business plugin types. Returns empty responses for custom and legacy built-in plugins. | [Listing plugin metadata](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugin-management.html#plugin-list-metadata) | 

# Managing admin controls and guardrails using APIs
Admin controls and guardrails

Amazon Q Business supports admin controls and guardrails configuration through both the console and the APIs.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [UpdateChatControlsConfiguration](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateChatControlsConfiguration.html) | Updates an set of chat controls configured for an existing Amazon Q Business application | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-api.html) | 
| [DeleteChatControlsConfiguration](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteChatControlsConfiguration.html) | Deletes chat controls configured for an existing Amazon Q Business application | [Deleting topic controls](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-management.html) | 
| [GetChatControlsConfiguration](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetChatControlsConfiguration.html) | Gets information about chat controls configured for an existing Amazon Q Business application. |  [Getting topic control properties](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-management.html#topic-control-properties) | 

# User feedback using Amazon Q Business APIs
User feedback

Amazon Q Business captures end user feedback to chat responses to help address any technical issues. You can't configure this feature using the console.


****  

| API action | API description | Relevant User Guide topic | 
| --- | --- | --- | 
| [PutFeedback](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutFeedback.html) | Enables your end user to provide feedback on their Amazon Q Business generated chat responses. | [Using web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-web-experience.html#provide-feedback) |