openapi: 3.1.0
info:
  title: Arthur Scope Agents V1 Groups V1 API
  version: 0.1.0
tags:
- name: Groups V1
paths:
  /api/v1/organization/group_memberships:
    get:
      tags:
      - Groups V1
      summary: Search Group Memberships
      description: Searches memberships for the intersection of user and group IDs. Requires organization_list_group_memberships permission.
      operationId: search_group_memberships
      security:
      - OAuth2AuthorizationCode:
        - organization_list_group_memberships
      parameters:
      - name: user_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
          description: Filter memberships to select user IDs.
          title: User Ids
        description: Filter memberships to select user IDs.
      - name: group_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
          description: Filter memberships to select group IDs.
          title: Group Ids
        description: Filter memberships to select group IDs.
      - name: group_name
        in: query
        required: false
        schema:
          type: string
          description: Filter memberships by group name. A name matches if it contains the input string case-insensitive.
          title: Group Name
        description: Filter memberships by group name. A name matches if it contains the input string case-insensitive.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: The page to return starting from 1 up to total_pages.
          default: 1
          title: Page
        description: The page to return starting from 1 up to total_pages.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: The number of records per page. The max is 1000.
          default: 20
          title: Page Size
        description: The number of records per page. The max is 1000.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_GroupMembership_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/organization/groups:
    get:
      tags:
      - Groups V1
      summary: List Groups
      description: Fetches all groups. Requires organization_list_groups permission.
      operationId: get_groups
      security:
      - OAuth2AuthorizationCode:
        - organization_list_groups
      parameters:
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/GroupSort'
          description: Override the field used for sorting. Optional.
          default: name
        description: Override the field used for sorting. Optional.
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Override the sort order of the returned list. Optional.
          default: asc
        description: Override the sort order of the returned list. Optional.
      - name: name
        in: query
        required: false
        schema:
          type: string
          description: Filter the list of groups by name. Optional.
          title: Name
        description: Filter the list of groups by name. Optional.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: The page to return starting from 1 up to total_pages.
          default: 1
          title: Page
        description: The page to return starting from 1 up to total_pages.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: The number of records per page. The max is 1000.
          default: 20
          title: Page Size
        description: The number of records per page. The max is 1000.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_Group_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Groups V1
      summary: Create Group
      description: Requires organization_create_group permission.
      operationId: post_group
      security:
      - OAuth2AuthorizationCode:
        - organization_create_group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostGroup'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/groups/{group_id}:
    get:
      tags:
      - Groups V1
      summary: Get Group
      description: Fetches group by ID. Requires group_read permission.
      operationId: get_group
      security:
      - OAuth2AuthorizationCode:
        - group_read
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Groups V1
      summary: Update Group
      description: Updates group by ID. Requires group_update permission.
      operationId: patch_group
      security:
      - OAuth2AuthorizationCode:
        - group_update
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchGroup'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Groups V1
      summary: Delete Group
      description: Deletes group by ID. Requires group_delete permission.
      operationId: delete_group
      security:
      - OAuth2AuthorizationCode:
        - group_delete
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      responses:
        '204':
          description: Group deleted.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/groups/{group_id}/users:
    get:
      tags:
      - Groups V1
      summary: Get Group Users
      description: Fetches group users by group ID. Requires group_list_users permission.
      operationId: get_group_users
      security:
      - OAuth2AuthorizationCode:
        - group_list_users
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/UserSort'
          description: Override the field used for sorting the returned list. Optional.
          default: name
        description: Override the field used for sorting the returned list. Optional.
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Override the sort order used. Optional.
          default: asc
        description: Override the sort order used. Optional.
      - name: search
        in: query
        required: false
        schema:
          type: string
          description: Search for users by name or email.
          title: Search
        description: Search for users by name or email.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: The page to return starting from 1 up to total_pages.
          default: 1
          title: Page
        description: The page to return starting from 1 up to total_pages.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: The number of records per page. The max is 1000.
          default: 20
          title: Page Size
        description: The number of records per page. The max is 1000.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_User_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Groups V1
      summary: Assign User To Group
      description: Assign user to group by group ID. Requires group_create_group_membership permission.
      operationId: assign_users_to_group
      security:
      - OAuth2AuthorizationCode:
        - group_create_group_membership
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostGroupMembership'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Groups V1
      summary: Remove Users From Group In Bulk
      description: Remove all users from group by group ID. Requires group_delete_group_membership permission.
      operationId: remove_users_from_group
      security:
      - OAuth2AuthorizationCode:
        - group_delete_group_membership
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteGroupMembership'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PatchGroup:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: The group's name.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The group's description.
      type: object
      title: PatchGroup
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GroupSort:
      type: string
      enum:
      - name
      - created_at
      - updated_at
      title: GroupSort
    User:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time of record creation.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time of last record update.
        organization_id:
          type: string
          format: uuid4
          title: Organization Id
          description: The ID of the Arthur organization the user belongs to.
        id:
          type: string
          format: uuid4
          title: Id
          description: Unique user ID assigned by Arthur.
        first_name:
          type: string
          title: First Name
          description: The user's first name.
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
          description: The user's last name.
        email:
          anyOf:
          - type: string
            format: email
          - type: 'null'
          title: Email
          description: The user's email, if provided.
        picture:
          anyOf:
          - type: string
          - type: 'null'
          title: Picture
          description: A url to the user's profile picture, if one exists.
        user_type:
          $ref: '#/components/schemas/UserType'
          description: The type of user.
        data_plane_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Data Plane Id
          description: Arthur data plane ID. Only set for data plane users.
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
          description: Arthur client ID for this user. Only set for service account type users.
        organization_name:
          type: string
          title: Organization Name
          description: Name of user's Arthur organization.
      type: object
      required:
      - created_at
      - updated_at
      - organization_id
      - id
      - first_name
      - last_name
      - user_type
      - organization_name
      title: User
    PostGroup:
      properties:
        name:
          type: string
          title: Name
          description: The name of the group.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The group's description.
        identity_provider_mapping_name:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Identity Provider Mapping Name
          description: Sets the mapping name of the group from an IDP. If set, the group will become managed by the IDP and user management will not be available in Arthur. This can only be set when the group is created.
      type: object
      required:
      - name
      title: PostGroup
    DeleteGroupMembership:
      properties:
        user_ids:
          items:
            type: string
            format: uuid4
          type: array
          title: User Ids
          description: The ID of the user to remove from the group.
      type: object
      required:
      - user_ids
      title: DeleteGroupMembership
    UserSort:
      type: string
      enum:
      - name
      - email
      - created_at
      - updated_at
      title: UserSort
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Group:
      properties:
        name:
          type: string
          title: Name
          description: The name of the group.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The group's description.
        identity_provider_mapping_name:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Identity Provider Mapping Name
          description: Sets the mapping name of the group from an IDP. If set, the group will become managed by the IDP and user management will not be available in Arthur. This can only be set when the group is created.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time of record creation.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time of last record update.
        id:
          type: string
          format: uuid4
          title: Id
          description: Unique group ID assigned by Arthur.
        organization_id:
          type: string
          format: uuid4
          title: Organization Id
          description: The ID of the organization the group belongs to.
        members:
          type: integer
          title: Members
          description: The number of members in the group.
      type: object
      required:
      - name
      - created_at
      - updated_at
      - id
      - organization_id
      - members
      title: Group
    NotFoundError:
      properties:
        detail:
          type: string
          title: Detail
          default: Resource not found
      type: object
      title: NotFoundError
    InternalServerError:
      properties:
        detail:
          type: string
          title: Detail
          default: Internal server error
      type: object
      title: InternalServerError
    ResourceList_Group_:
      properties:
        records:
          items:
            $ref: '#/components/schemas/Group'
          type: array
          title: Records
          description: List of records.
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination information.
      type: object
      required:
      - records
      - pagination
      title: ResourceList[Group]
    BadRequestError:
      properties:
        detail:
          type: string
          title: Detail
          default: Bad Request
      type: object
      title: BadRequestError
    UserType:
      type: string
      enum:
      - user
      - data_plane
      - service_account
      title: UserType
    Pagination:
      properties:
        page:
          type: integer
          title: Page
          description: The current page number. Page 1 is the first page.
          default: 1
        page_size:
          type: integer
          title: Page Size
          description: Number of records per page.
          default: 20
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages.
        total_records:
          type: integer
          title: Total Records
          description: Total number of records across all pages.
      type: object
      required:
      - total_pages
      - total_records
      title: Pagination
    PostGroupMembership:
      properties:
        user_ids:
          items:
            type: string
            format: uuid4
          type: array
          title: User Ids
          description: The ID of the user to add to the group.
      type: object
      required:
      - user_ids
      title: PostGroupMembership
    GroupMembership:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time of record creation.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time of last record update.
        group:
          $ref: '#/components/schemas/Group'
          description: Group info of the membership.
        group_id:
          type: string
          format: uuid4
          title: Group Id
          description: The ID of the organization the group belongs to.
        user_id:
          type: string
          format: uuid4
          title: User Id
          description: The ID of the user that belongs to the group.
      type: object
      required:
      - created_at
      - updated_at
      - group
      - group_id
      - user_id
      title: GroupMembership
    ResourceList_User_:
      properties:
        records:
          items:
            $ref: '#/components/schemas/User'
          type: array
          title: Records
          description: List of records.
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination information.
      type: object
      required:
      - records
      - pagination
      title: ResourceList[User]
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    ResourceList_GroupMembership_:
      properties:
        records:
          items:
            $ref: '#/components/schemas/GroupMembership'
          type: array
          title: Records
          description: List of records.
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination information.
      type: object
      required:
      - records
      - pagination
      title: ResourceList[GroupMembership]
  securitySchemes:
    OAuth2AuthorizationCode:
      type: oauth2
      flows:
        authorizationCode:
          refreshUrl: https://platform-auth.arthur.ai/realms/arthur/protocol/openid-connect/token
          scopes: {}
          authorizationUrl: https://platform-auth.arthur.ai/realms/arthur/protocol/openid-connect/auth
          tokenUrl: https://platform-auth.arthur.ai/realms/arthur/protocol/openid-connect/token