Amazon Q Q Plugins API

openapi: 3.2.0
info:
  title: QBusiness Plugins API
  version: '2023-11-27'
  description: Generated from AWS's published Smithy model for QBusiness. 5 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://qbusiness.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Plugins
paths:
  /applications/{applicationId}/plugins:
    post:
      operationId: CreatePlugin
      summary: Create Plugin
      description: Creates an Amazon Q Business plugin.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePluginResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePluginRequest'
      tags:
      - Plugins
    get:
      operationId: ListPlugins
      summary: List Plugins
      description: Lists configured Amazon Q Business plugins.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPluginsResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListPluginsRequest'
      tags:
      - Plugins
  /applications/{applicationId}/plugins/{pluginId}:
    get:
      operationId: GetPlugin
      summary: Get Plugin
      description: Gets information about an existing Amazon Q Business plugin.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPluginResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetPluginRequest'
      tags:
      - Plugins
    put:
      operationId: UpdatePlugin
      summary: Update Plugin
      description: Updates an Amazon Q Business plugin.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePluginResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePluginRequest'
      tags:
      - Plugins
    delete:
      operationId: DeletePlugin
      summary: Delete Plugin
      description: Deletes an Amazon Q Business plugin.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePluginResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletePluginRequest'
      tags:
      - Plugins
components:
  schemas:
    APISchema:
      type: object
      properties:
        payload:
          type: string
          description: The JSON or YAML-formatted payload defining the OpenAPI schema for a custom plugin.
        s3:
          $ref: '#/components/schemas/S3'
      description: Exactly one member is set.
    CreatePluginResponse:
      type: object
      properties:
        pluginId:
          type: string
          description: The identifier of the plugin created.
        pluginArn:
          type: string
          description: The Amazon Resource Name (ARN) of a plugin.
        buildStatus:
          type: string
          enum:
          - READY
          - CREATE_IN_PROGRESS
          - CREATE_FAILED
          - UPDATE_IN_PROGRESS
          - UPDATE_FAILED
          - DELETE_IN_PROGRESS
          - DELETE_FAILED
          description: The current status of a plugin. A plugin is modified asynchronously.
    Tag:
      type: object
      properties:
        key:
          type: string
          description: The key for the tag. Keys are not case sensitive and must be unique for the Amazon Q Business application or data source.
        value:
          type: string
          description: The value associated with the tag. The value may be an empty string but it can't be null.
      required:
      - key
      - value
    DeletePluginResponse:
      type: object
      properties: {}
    UpdatePluginResponse:
      type: object
      properties: {}
    S3:
      type: object
      properties:
        bucket:
          type: string
          description: The name of the S3 bucket that contains the file.
        key:
          type: string
          description: The name of the file.
      required:
      - bucket
      - key
    IdcAuthConfiguration:
      type: object
      properties:
        idcApplicationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM Identity Center Application used to configure authentication.
        roleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM role with permissions to perform actions on Amazon Web Services services on your behalf.
      required:
      - idcApplicationArn
      - roleArn
    Plugin:
      type: object
      properties:
        pluginId:
          type: string
          description: The identifier of the plugin.
        displayName:
          type: string
          description: The name of the plugin.
        type:
          type: string
          enum:
          - SERVICE_NOW
          - SALESFORCE
          - JIRA
          - ZENDESK
          - CUSTOM
          - QUICKSIGHT
          - SERVICENOW_NOW_PLATFORM
          - JIRA_CLOUD
          - SALESFORCE_CRM
          - ZENDESK_SUITE
          - ATLASSIAN_CONFLUENCE
          - GOOGLE_CALENDAR
          - MICROSOFT_TEAMS
          - MICROSOFT_EXCHANGE
          - PAGERDUTY_ADVANCE
          - SMARTSHEET
          - ASANA
          description: The type of the plugin.
        serverUrl:
          type: string
          description: The plugin server URL used for configuration.
        state:
          type: string
          enum:
          - ENABLED
          - DISABLED
          description: The current status of the plugin.
        buildStatus:
          type: string
          enum:
          - READY
          - CREATE_IN_PROGRESS
          - CREATE_FAILED
          - UPDATE_IN_PROGRESS
          - UPDATE_FAILED
          - DELETE_IN_PROGRESS
          - DELETE_FAILED
          description: The status of the plugin.
        createdAt:
          type: string
          format: date-time
          description: The timestamp for when the plugin was created.
        updatedAt:
          type: string
          format: date-time
          description: The timestamp for when the plugin was last updated.
    GetPluginRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application which contains the plugin.
        pluginId:
          type: string
          description: The identifier of the plugin.
      required:
      - applicationId
      - pluginId
    GetPluginResponse:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application which contains the plugin.
        pluginId:
          type: string
          description: The identifier of the plugin.
        displayName:
          type: string
          description: The name of the plugin.
        type:
          type: string
          enum:
          - SERVICE_NOW
          - SALESFORCE
          - JIRA
          - ZENDESK
          - CUSTOM
          - QUICKSIGHT
          - SERVICENOW_NOW_PLATFORM
          - JIRA_CLOUD
          - SALESFORCE_CRM
          - ZENDESK_SUITE
          - ATLASSIAN_CONFLUENCE
          - GOOGLE_CALENDAR
          - MICROSOFT_TEAMS
          - MICROSOFT_EXCHANGE
          - PAGERDUTY_ADVANCE
          - SMARTSHEET
          - ASANA
          description: The type of the plugin.
        serverUrl:
          type: string
          description: The source URL used for plugin configuration.
        authConfiguration:
          $ref: '#/components/schemas/PluginAuthConfiguration'
        customPluginConfiguration:
          $ref: '#/components/schemas/CustomPluginConfiguration'
        buildStatus:
          type: string
          enum:
          - READY
          - CREATE_IN_PROGRESS
          - CREATE_FAILED
          - UPDATE_IN_PROGRESS
          - UPDATE_FAILED
          - DELETE_IN_PROGRESS
          - DELETE_FAILED
          description: The current status of a plugin. A plugin is modified asynchronously.
        pluginArn:
          type: string
          description: The Amazon Resource Name (ARN) of the role with permission to access resources needed to create the plugin.
        state:
          type: string
          enum:
          - ENABLED
          - DISABLED
          description: The current state of the plugin.
        createdAt:
          type: string
          format: date-time
          description: The timestamp for when the plugin was created.
        updatedAt:
          type: string
          format: date-time
          description: The timestamp for when the plugin was last updated.
    UpdatePluginRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application the plugin is attached to.
        pluginId:
          type: string
          description: The identifier of the plugin.
        displayName:
          type: string
          description: The name of the plugin.
        state:
          type: string
          enum:
          - ENABLED
          - DISABLED
          description: The status of the plugin.
        serverUrl:
          type: string
          description: The source URL used for plugin configuration.
        customPluginConfiguration:
          $ref: '#/components/schemas/CustomPluginConfiguration'
        authConfiguration:
          $ref: '#/components/schemas/PluginAuthConfiguration'
      required:
      - applicationId
      - pluginId
    ListPluginsResponse:
      type: object
      properties:
        nextToken:
          type: string
          description: 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.
        plugins:
          type: array
          items:
            $ref: '#/components/schemas/Plugin'
          description: Information about a configured plugin.
    ListPluginsRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application the plugin is attached to.
        nextToken:
          type: string
          description: 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.
        maxResults:
          type: integer
          description: The maximum number of documents to return.
      required:
      - applicationId
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
          description: The message describing a ResourceNotFoundException.
        resourceId:
          type: string
          description: The identifier of the resource affected.
        resourceType:
          type: string
          description: The type of the resource affected.
      required:
      - message
      - resourceId
      - resourceType
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    InternalServerException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    CreatePluginRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application that will contain the plugin.
        displayName:
          type: string
          description: A the name for your plugin.
        type:
          type: string
          enum:
          - SERVICE_NOW
          - SALESFORCE
          - JIRA
          - ZENDESK
          - CUSTOM
          - QUICKSIGHT
          - SERVICENOW_NOW_PLATFORM
          - JIRA_CLOUD
          - SALESFORCE_CRM
          - ZENDESK_SUITE
          - ATLASSIAN_CONFLUENCE
          - GOOGLE_CALENDAR
          - MICROSOFT_TEAMS
          - MICROSOFT_EXCHANGE
          - PAGERDUTY_ADVANCE
          - SMARTSHEET
          - ASANA
          description: The type of plugin you want to create.
        authConfiguration:
          $ref: '#/components/schemas/PluginAuthConfiguration'
        serverUrl:
          type: string
          description: The source URL used for plugin configuration.
        customPluginConfiguration:
          $ref: '#/components/schemas/CustomPluginConfiguration'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: '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: _ . : / = + - @.'
        clientToken:
          type: string
          description: A token that you provide to identify the request to create your Amazon Q Business plugin.
      required:
      - applicationId
      - displayName
      - type
      - authConfiguration
    DeletePluginRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier the application attached to the Amazon Q Business plugin.
        pluginId:
          type: string
          description: The identifier of the plugin being deleted.
      required:
      - applicationId
      - pluginId
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
          description: The message describing a ServiceQuotaExceededException.
        resourceId:
          type: string
          description: The identifier of the resource affected.
        resourceType:
          type: string
          description: The type of the resource affected.
      required:
      - message
      - resourceId
      - resourceType
    BasicAuthConfiguration:
      type: object
      properties:
        secretArn:
          type: string
          description: The ARN of the Secrets Manager secret that stores the basic authentication credentials used for plugin configuration..
        roleArn:
          type: string
          description: The ARN of an IAM role used by Amazon Q Business to access the basic authentication credentials stored in a Secrets Manager secret.
      required:
      - secretArn
      - roleArn
    ValidationExceptionField:
      type: object
      properties:
        name:
          type: string
          description: The field name where the invalid entry was detected.
        message:
          type: string
          description: A message about the validation exception.
      required:
      - name
      - message
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    CustomPluginConfiguration:
      type: object
      properties:
        description:
          type: string
          description: A description for your custom plugin configuration.
        apiSchemaType:
          type: string
          enum:
          - OPEN_API_V3
          description: The type of OpenAPI schema to use.
        apiSchema:
          $ref: '#/components/schemas/APISchema'
      required:
      - description
      - apiSchemaType
    ValidationException:
      type: object
      properties:
        message:
          type: string
          description: The message describing the ValidationException.
        reason:
          type: string
          enum:
          - CANNOT_PARSE
          - FIELD_VALIDATION_FAILED
          - UNKNOWN_OPERATION
          description: The reason for the ValidationException.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
          description: The input field(s) that failed validation.
      required:
      - message
      - reason
    ConflictException:
      type: object
      properties:
        message:
          type: string
          description: The message describing a ConflictException.
        resourceId:
          type: string
          description: The identifier of the resource affected.
        resourceType:
          type: string
          description: The type of the resource affected.
      required:
      - message
      - resourceId
      - resourceType
    OAuth2ClientCredentialConfiguration:
      type: object
      properties:
        secretArn:
          type: string
          description: The ARN of the Secrets Manager secret that stores the OAuth 2.0 credentials/token used for plugin configuration.
        roleArn:
          type: string
          description: 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.
        authorizationUrl:
          type: string
          description: The redirect URL required by the OAuth 2.0 protocol for Amazon Q Business to authenticate a plugin user through a third party authentication server.
        tokenUrl:
          type: string
          description: The URL required by the OAuth 2.0 protocol to exchange an end user authorization code for an access token.
      required:
      - secretArn
      - roleArn
    PluginAuthConfiguration:
      type: object
      properties:
        basicAuthConfiguration:
          $ref: '#/components/schemas/BasicAuthConfiguration'
        oAuth2ClientCredentialConfiguration:
          $ref: '#/components/schemas/OAuth2ClientCredentialConfiguration'
        noAuthConfiguration:
          $ref: '#/components/schemas/NoAuthConfiguration'
        idcAuthConfiguration:
          $ref: '#/components/schemas/IdcAuthConfiguration'
      description: Exactly one member is set.
    NoAuthConfiguration:
      type: object
      properties: {}
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: qbusiness
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/qbusiness/service/2023-11-27/qbusiness-2023-11-27.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)