Amazon Q Q Groups API

openapi: 3.2.0
info:
  title: QBusiness Groups API
  version: '2023-11-27'
  description: Generated from AWS's published Smithy model for QBusiness. 4 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://qbusiness.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Groups
paths:
  /applications/{applicationId}/indices/{indexId}/groups/{groupName}:
    delete:
      operationId: DeleteGroup
      summary: Delete Group
      description: 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.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteGroupResponse'
        '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/DeleteGroupRequest'
      tags:
      - Groups
    get:
      operationId: GetGroup
      summary: Get Group
      description: Describes a group by group name.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGroupResponse'
        '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/GetGroupRequest'
      tags:
      - Groups
  /applications/{applicationId}/indices/{indexId}/groups:
    get:
      operationId: ListGroups
      summary: List Groups
      description: Provides a list of groups that are mapped to users.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGroupsResponse'
        '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/ListGroupsRequest'
      tags:
      - Groups
    put:
      operationId: PutGroup
      summary: Put Group
      description: 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. There are two options for creating groups, either passing group members inline or using an S3 file via the S3PathForGroupMembers field. For inline groups, there is a limit of 1000 members per group and for provided S3 files there is a limit of 100 thousand members. When creating a group using an S3 file, you provide both an S3 file and a RoleArn for Amazon Q Buisness to access the file.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutGroupResponse'
        '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/PutGroupRequest'
      tags:
      - Groups
components:
  schemas:
    ListGroupsResponse:
      type: object
      properties:
        nextToken:
          type: string
          description: 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.
        items:
          type: array
          items:
            $ref: '#/components/schemas/GroupSummary'
          description: Summary information for list of groups that are mapped to users.
    ErrorDetail:
      type: object
      properties:
        errorMessage:
          type: string
          description: The message explaining the Amazon Q Business request error.
        errorCode:
          type: string
          enum:
          - InternalError
          - InvalidRequest
          - ResourceInactive
          - ResourceNotFound
          description: The code associated with the Amazon Q Business request error.
    ListGroupsRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application for getting a list of groups mapped to users.
        indexId:
          type: string
          description: The identifier of the index for getting a list of groups mapped to users.
        updatedEarlierThan:
          type: string
          format: date-time
          description: The timestamp identifier used for the latest PUT or DELETE action for mapping users to their groups.
        dataSourceId:
          type: string
          description: The identifier of the data source for getting a list of groups mapped to users.
        nextToken:
          type: string
          description: 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.
        maxResults:
          type: integer
          description: The maximum number of returned groups that are mapped to users.
      required:
      - applicationId
      - indexId
      - updatedEarlierThan
    GetGroupResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/GroupStatusDetail'
        statusHistory:
          type: array
          items:
            $ref: '#/components/schemas/GroupStatusDetail'
          description: The status history of the group.
    PutGroupRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application in which the user and group mapping belongs.
        indexId:
          type: string
          description: The identifier of the index in which you want to map users to their groups.
        groupName:
          type: string
          description: 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".
        dataSourceId:
          type: string
          description: 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:
          type: string
          enum:
          - INDEX
          - DATASOURCE
          description: The type of the group.
        groupMembers:
          $ref: '#/components/schemas/GroupMembers'
        roleArn:
          type: string
          description: The Amazon Resource Name (ARN) of an IAM role that has access to the S3 file that contains your list of users that belong to a group.
      required:
      - applicationId
      - indexId
      - groupName
      - type
      - groupMembers
    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
    DeleteGroupResponse:
      type: object
      properties: {}
    MemberUser:
      type: object
      properties:
        userId:
          type: string
          description: The identifier of the user you want to map to a group.
        type:
          type: string
          enum:
          - INDEX
          - DATASOURCE
          description: The type of the user.
      required:
      - userId
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    InternalServerException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    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
    DeleteGroupRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application in which the group mapping belongs.
        indexId:
          type: string
          description: The identifier of the index you want to delete the group from.
        groupName:
          type: string
          description: The name of the group you want to delete.
        dataSourceId:
          type: string
          description: 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.
      required:
      - applicationId
      - indexId
      - groupName
    MemberGroup:
      type: object
      properties:
        groupName:
          type: string
          description: The name of the sub group.
        type:
          type: string
          enum:
          - INDEX
          - DATASOURCE
          description: The type of the sub group.
      required:
      - groupName
    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
    PutGroupResponse:
      type: object
      properties: {}
    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
    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
    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
    GroupSummary:
      type: object
      properties:
        groupName:
          type: string
          description: The name of the group the summary information is for.
    GroupStatusDetail:
      type: object
      properties:
        status:
          type: string
          enum:
          - FAILED
          - SUCCEEDED
          - PROCESSING
          - DELETING
          - DELETED
          description: The status of a group.
        lastUpdatedAt:
          type: string
          format: date-time
          description: The Unix timestamp when the Amazon Q Business application was last updated.
        errorDetail:
          $ref: '#/components/schemas/ErrorDetail'
    GroupMembers:
      type: object
      properties:
        memberGroups:
          type: array
          items:
            $ref: '#/components/schemas/MemberGroup'
          description: 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".
        memberUsers:
          type: array
          items:
            $ref: '#/components/schemas/MemberUser'
          description: A list of users that belong to a group. For example, a list of interns all belong to the "Interns" group.
        s3PathForGroupMembers:
          $ref: '#/components/schemas/S3'
    GetGroupRequest:
      type: object
      properties:
        applicationId:
          type: string
          description: The identifier of the application id the group is attached to.
        indexId:
          type: string
          description: The identifier of the index the group is attached to.
        groupName:
          type: string
          description: The name of the group.
        dataSourceId:
          type: string
          description: The identifier of the data source the group is attached to.
      required:
      - applicationId
      - indexId
      - groupName
  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)