openapi: 3.2.0
info:
  title: Pipeshub User Groups API
  version: 1.0.0
  contact:
    name: API Support
    email: support@pipeshub.com
  description: 'Operations tagged User Groups across 2 of this provider''s published API definitions: pipeshub-openapi.yaml, pipeshub-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{instance_url}/api/v1'
  description: Base API URL
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL (without /api/v1)
- url: '{instance_url}'
  description: Root URL (used for MCP endpoints mounted at /mcp)
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL
security:
- bearerAuth: []
- oauth2: []
tags:
- name: User Groups
  description: User group management operations
paths:
  /userGroups:
    post:
      tags:
      - User Groups
      summary: Create user group
      description: 'Create a new user group within the organization.


        **Allowed Types:**


        - `standard` - Regular user group

        - `everyone` - Automatically includes all organization users

        - `custom` - Custom group with manual membership management


        **Note:** Groups of type `admin` cannot be created — it is a system group.


        **Validation:**


        - Both `name` and `type` are required

        - `name` must be unique across non-deleted groups in the organization'
      operationId: createUserGroup
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:write
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Display name for the group
                  example: Engineering Team
                type:
                  type: string
                  enum:
                  - standard
                  - everyone
                  - custom
                  description: Group type
                  example: custom
              required:
              - name
              - type
      responses:
        '201':
          description: User group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: 'Invalid request. Possible reasons:


            - Missing or empty `name` or `type`

            - `type` is not one of: standard, everyone, custom

            - Group name or type `admin` is not allowed

            - A group with the same name already exists

            - Requester does not have admin privileges

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requester account not found (missing userId or orgId in token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database save failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - User Groups
      summary: Get all user groups
      description: 'Retrieve all user groups in the organization.


        Returns paginated groups with their member counts (not member details).

        Soft-deleted groups are excluded. Supports filtering by name and date range.


        **Query Parameters:**


        - `page` / `limit` — pagination (defaults: 1 / 25, max limit: 100)

        - `search` — case-insensitive substring match on group name

        - `createdAfter` / `createdBefore` — filter by creation date (ISO 8601)'
      operationId: getAllUserGroups
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:read
      parameters:
      - name: page
        in: query
        required: false
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        description: Number of groups per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: search
        in: query
        required: false
        description: Search groups by name (case-insensitive)
        schema:
          type: string
      - name: createdAfter
        in: query
        required: false
        description: Filter groups created on or after this date (ISO 8601)
        schema:
          type: string
          format: date
      - name: createdBefore
        in: query
        required: false
        description: Filter groups created on or before this date (ISO 8601)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Paginated list of user groups with user counts
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  groups:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        _id:
                          type: string
                          format: ObjectId
                        name:
                          type: string
                        type:
                          type: string
                          enum:
                          - admin
                          - standard
                          - everyone
                          - custom
                        orgId:
                          type: string
                        userCount:
                          type: integer
                          description: Number of users in this group
                        slug:
                          type: string
                        isDeleted:
                          type: boolean
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                  pagination:
                    type: object
                    additionalProperties: false
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasNextPage:
                        type: boolean
                      hasPrevPage:
                        type: boolean
        '400':
          description: Requester does not have admin privileges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requester account not found (missing userId or orgId in token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database query failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /userGroups/{groupId}:
    get:
      tags:
      - User Groups
      summary: Get user group by ID
      description: Retrieve a specific user group by its ID. Accessible by any authenticated user.
      operationId: getUserGroupById
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:read
      parameters:
      - name: groupId
        in: path
        required: true
        description: Unique identifier of the user group
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: User group details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: Invalid `groupId` format (must be a 24-character hex ObjectId)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database query failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - User Groups
      summary: Update user group
      description: 'Rename an existing user group.


        Only the `name` field can be updated. Groups of type `admin` or `everyone`

        cannot be renamed.'
      operationId: updateUserGroup
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:write
      parameters:
      - name: groupId
        in: path
        required: true
        description: Unique identifier of the user group to update
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          example: 507f1f77bcf86cd799439011
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: New display name for the group
                  example: Engineering Team - Updated
              required:
              - name
      responses:
        '200':
          description: User group updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: 'Invalid request. Possible reasons:


            - Missing or empty `name`

            - Invalid `groupId` format (must be a 24-character hex ObjectId)

            - Requester does not have admin privileges

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Groups of type `admin` or `everyone` cannot be renamed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'Resource not found. Possible reasons:


            - User group not found or deleted

            - Requester account not found (missing userId or orgId in token)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database save failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - User Groups
      summary: Delete user group
      description: 'Soft-delete a user group by setting `isDeleted: true`.


        **Restriction:** Only groups of type `custom` can be deleted. Attempting to

        delete a group of any other type (`admin`, `everyone`, `standard`) returns 403.'
      operationId: deleteUserGroup
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:write
      parameters:
      - name: groupId
        in: path
        required: true
        description: Unique identifier of the user group to delete
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: User group soft-deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: 'Invalid request. Possible reasons:


            - Invalid `groupId` format (must be a 24-character hex ObjectId)

            - Requester does not have admin privileges

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Only custom groups can be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'Resource not found. Possible reasons:


            - User group not found or already deleted

            - Requester account not found (missing userId or orgId in token)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database save failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /userGroups/add-users:
    post:
      tags:
      - User Groups
      summary: Add users to group
      description: 'Add one or more users to one or more groups.


        **Request validation** (Zod at route layer): `userIds` and `groupIds` are required

        non-empty arrays; each entry must be a 24-character hex MongoDB ObjectId.


        Uses `$addToSet` — users already in a group are silently skipped.

        If none of the provided `groupIds` match active groups in the organization,

        a 400 is returned.'
      operationId: addUsersToGroup
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:write
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                groupIds:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    pattern: ^[a-fA-F0-9]{24}$
                  description: IDs of groups to add users to
                userIds:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    pattern: ^[a-fA-F0-9]{24}$
                  description: User IDs to add
              required:
              - groupIds
              - userIds
      responses:
        '200':
          description: Users added to groups successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - message
                properties:
                  message:
                    type: string
                    example: Users added to groups successfully
        '400':
          description: 'Invalid request. Possible reasons:


            - Invalid request body (Zod validation — missing/empty `userIds` or `groupIds`, malformed ObjectIds)

            - No matching groups found or updated

            - Requester does not have admin privileges

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requester account not found (missing userId or orgId in token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database update failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /userGroups/remove-users:
    post:
      tags:
      - User Groups
      summary: Remove users from group
      description: 'Remove one or more users from one or more groups.


        **Request validation** (Zod at route layer): same as `POST /userGroups/add-users` —

        `userIds` and `groupIds` required non-empty arrays of 24-character hex ObjectIds.


        Uses `$pullAll` — users not in a group are silently skipped.

        If none of the provided `groupIds` match active groups in the organization,

        a 400 is returned.'
      operationId: removeUsersFromGroup
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:write
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                groupIds:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    pattern: ^[a-fA-F0-9]{24}$
                userIds:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    pattern: ^[a-fA-F0-9]{24}$
              required:
              - groupIds
              - userIds
      responses:
        '200':
          description: Users removed from groups successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - message
                properties:
                  message:
                    type: string
                    example: Users removed from groups successfully
        '400':
          description: 'Invalid request. Possible reasons:


            - Invalid request body (Zod validation — missing/empty `userIds` or `groupIds`, malformed ObjectIds)

            - No matching groups found or updated

            - Requester does not have admin privileges

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requester account not found (missing userId or orgId in token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database update failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /userGroups/users/{userId}:
    get:
      tags:
      - User Groups
      summary: Get groups for a user
      description: 'Retrieve all groups that a specific user belongs to. Returns an array of

        group objects with `name` and `type` fields. Returns an empty array if the

        user is not in any groups — no 404 is raised.


        **Path validation:** `userId` must be a 24-character hex MongoDB ObjectId (Zod at route layer).


        Accessible by any authenticated user (no admin check).'
      operationId: getGroupsForUser
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:read
      parameters:
      - name: userId
        in: path
        required: true
        description: Unique identifier of the user
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          example: 507f1f77bcf86cd799439012
      responses:
        '200':
          description: User's groups retrieved successfully (empty array if none)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                  - _id
                  - name
                  - type
                  properties:
                    _id:
                      type: string
                      format: ObjectId
                    name:
                      type: string
                    type:
                      type: string
                      enum:
                      - admin
                      - standard
                      - everyone
                      - custom
        '400':
          description: Invalid `userId` path parameter (Zod validation)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database query failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /userGroups/{groupId}/users:
    get:
      tags:
      - User Groups
      summary: Get users in group
      description: 'Retrieve paginated users that belong to a specific user group, with profile pictures.


        Returns user details (`fullName`, `email`) with profile picture data URIs.

        Supports pagination and search by name or email. Accessible by any authenticated user.'
      operationId: getUsersInGroup
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:read
      parameters:
      - name: groupId
        in: path
        required: true
        description: Unique identifier of the user group
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: search
        in: query
        required: false
        description: Search users by name or email
        schema:
          type: string
      responses:
        '200':
          description: Paginated users in group with profile pictures
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  users:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        _id:
                          type: string
                          format: ObjectId
                        fullName:
                          type:
                          - string
                          - 'null'
                        email:
                          type:
                          - string
                          - 'null'
                        profilePicture:
                          type:
                          - string
                          - 'null'
                          description: Base64 data URI or null
                  pagination:
                    type: object
                    additionalProperties: false
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasNextPage:
                        type: boolean
                      hasPrevPage:
                        type: boolean
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Invalid `groupId` format (must be a 24-character hex ObjectId)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User group not found or already deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database query failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /userGroups/stats/list:
    get:
      tags:
      - User Groups
      summary: Get group statistics
      description: 'Retrieve aggregated statistics for all non-deleted user groups in the

        organization. Groups by group name and returns the group count, total user

        count, and average users per group. Accessible by any authenticated user.'
      operationId: getGroupStatistics
      security:
      - bearerAuth: []
      - oauth2:
        - usergroup:read
      responses:
        '200':
          description: Group statistics retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                  - _id
                  - count
                  - totalUsers
                  - avgUsers
                  properties:
                    _id:
                      type: string
                      description: Group name (aggregation key)
                    count:
                      type: integer
                    totalUsers:
                      type: integer
                    avgUsers:
                      type: number
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Database aggregation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /userGroups/health:
    get:
      tags:
      - User Groups
      summary: User groups module health check
      description: Returns the health status of the user groups module. No authentication required.
      operationId: getUserGroupsHealth
      security: []
      responses:
        '200':
          description: Service healthy
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - status
                - timestamp
                properties:
                  status:
                    type: string
                    enum:
                    - healthy
                  timestamp:
                    type: string
                    format: date-time
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
components:
  schemas:
    ErrorResponse:
      type: object
      additionalProperties: false
      description: 'Standard error envelope returned by all errors routed through `ErrorMiddleware`.

        Applies to all `BaseError` subclasses including `HttpError`, `ValidationError`, and others.

        The `code` field is a machine-readable string identifying the error type (e.g.

        `HTTP_UNAUTHORIZED`, `HTTP_NOT_FOUND`, `VALIDATION_ERROR`, `INTERNAL_ERROR`).

        '
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          properties:
            requestId:
              type: string
              description: 'Identifier for this request, echoed so a bug report can quote it.

                Absent when the request never reached the middleware that assigns one.

                '
            code:
              type: string
              description: 'Machine-readable error code. For application errors it takes the form `HTTP_<VARIANT>`

                For unhandled runtime errors (e.g. database unavailable) it is `INTERNAL_ERROR`.

                '
              example: HTTP_BAD_REQUEST
            message:
              type: string
              description: Human-readable description of the error
              example: Admin access required
            metadata:
              type: object
              description: Additional context (only present in development environments)
              additionalProperties: true
      required:
      - error
    UserGroup:
      type: object
      description: User group for organizing users within an organization
      properties:
        _id:
          type: string
          format: ObjectId
          description: Unique group identifier
        slug:
          type: string
          description: Unique slug for the group
        type:
          type: string
          enum:
          - admin
          - standard
          - everyone
          - custom
          description: 'Group type:

            - admin: System admin group (cannot be modified)

            - standard: Default user group

            - everyone: All users group (cannot be modified)

            - custom: User-created custom group

            '
        name:
          type: string
          description: Group name (unique within organization)
          minLength: 1
        orgId:
          type: string
          format: ObjectId
          description: Organization ID
        users:
          type: array
          items:
            type: string
            format: ObjectId
          description: Member user IDs (MongoDB ObjectId strings)
        isDeleted:
          type: boolean
          description: Soft delete flag
          default: false
        deletedBy:
          type: string
          format: ObjectId
          description: ID of user who deleted this group
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601)
      required:
      - type
      - name
      - orgId
      - users
      - isDeleted
      - _id
      - createdAt
      - updatedAt
      - slug
      - __v
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token for authenticated requests.


        A personal access token (see the **Personal Access Tokens** tag) is a

        `phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.

        The prefix is display-only, added for secret-scanner detectability; the

        gateway strips it before verifying the token, so send it exactly as

        issued, prefix included.

        '
    scopedToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Scoped JWT token for service-to-service authentication.

        Format: "Bearer {scoped_token}"

        Required scopes vary by endpoint.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 authentication with fine-grained scopes.

        Supports authorization_code (with PKCE) and client_credentials flows.

        OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.

        For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the OAuth app creator — see **OAuth Provider** tag.

        '
      flows:
        authorizationCode:
          authorizationUrl: /api/v1/oauth2/authorize
          tokenUrl: /api/v1/oauth2/token
          refreshUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:read: Read semantic search results and history
            semantic:write: Execute semantic search
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            crawl:delete: Delete crawling jobs
        clientCredentials:
          tokenUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:write: Execute semantic search
            semantic:read: Read semantic search results and history
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
x-refined-from:
- pipeshub-openapi.yaml
- pipeshub-openapi.yml