dialogbrain-com Group Discovery API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Group Discovery API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: group-discovery
paths:
  /api/groups/discovery/sessions:
    post:
      tags:
      - group-discovery
      summary: Create Discovery Session
      description: 'Create a new group discovery session.


        A session tracks search parameters and found groups.'
      operationId: create_discovery_session_api_groups_discovery_sessions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovery/sessions/{session_id}:
    get:
      tags:
      - group-discovery
      summary: Get Discovery Session
      description: Get a discovery session by ID.
      operationId: get_discovery_session_api_groups_discovery_sessions__session_id__get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: integer
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovery/sessions/{session_id}/search:
    post:
      tags:
      - group-discovery
      summary: Search Groups In Session
      description: Search for public groups and add results to the session.
      operationId: search_groups_in_session_api_groups_discovery_sessions__session_id__search_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: integer
          title: Session Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchGroupsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchGroupsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovery/sessions/{session_id}/add-from-search:
    post:
      tags:
      - group-discovery
      summary: Add Group From Search
      description: Add a group from search results to the session.
      operationId: add_group_from_search_api_groups_discovery_sessions__session_id__add_from_search_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: integer
          title: Session Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchResultItem'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovery/sessions/{session_id}/add-link:
    post:
      tags:
      - group-discovery
      summary: Add Group From Link
      description: Add a group from an invite link (t.me/... or @username).
      operationId: add_group_from_link_api_groups_discovery_sessions__session_id__add_link_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: integer
          title: Session Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddLinkRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered:
    get:
      tags:
      - group-discovery
      summary: List Discovered Groups
      description: 'List discovered groups with optional filters.


        By default, excludes dismissed groups.'
      operationId: list_discovered_groups_api_groups_discovered_get
      parameters:
      - name: channel
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by channel: telegram, whatsapp, etc.'
          title: Channel
        description: 'Filter by channel: telegram, whatsapp, etc.'
      - name: lifecycle
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by lifecycle: discovered, bookmarked, monitored, dismissed'
          title: Lifecycle
        description: 'Filter by lifecycle: discovered, bookmarked, monitored, dismissed'
      - name: min_score
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum overall score
          title: Min Score
        description: Minimum overall score
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupsListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/{group_id}:
    get:
      tags:
      - group-discovery
      summary: Get Discovered Group
      description: Get a discovered group by ID.
      operationId: get_discovered_group_api_groups_discovered__group_id__get
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - group-discovery
      summary: Delete Discovered Group
      description: Delete a discovered group.
      operationId: delete_discovered_group_api_groups_discovered__group_id__delete
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/{group_id}/scan:
    post:
      tags:
      - group-discovery
      summary: Start Group Scan
      description: 'Start an async scan for a group.


        Returns 202 Accepted immediately. Poll /scan-status for progress.'
      operationId: start_group_scan_api_groups_discovered__group_id__scan_post
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartScanRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/{group_id}/scan-status:
    get:
      tags:
      - group-discovery
      summary: Get Group Scan Status
      description: Get current scan status for a group.
      operationId: get_group_scan_status_api_groups_discovered__group_id__scan_status_get
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/{group_id}/rescan:
    post:
      tags:
      - group-discovery
      summary: Rescan Group
      description: Reset and rescan a group.
      operationId: rescan_group_api_groups_discovered__group_id__rescan_post
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartScanRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/{group_id}/lifecycle:
    post:
      tags:
      - group-discovery
      summary: Set Group Lifecycle
      description: 'Set the lifecycle state for a group.


        Lifecycle states:

        - discovered: Initial state after finding group

        - bookmarked: User interested, saved for later

        - monitored: User committed, thread created for sync

        - dismissed: Hidden from lists


        Setting lifecycle to ''monitored'' will create a thread

        and start syncing messages via channel-sync-service.'
      operationId: set_group_lifecycle_api_groups_discovered__group_id__lifecycle_post
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetLifecycleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/{group_id}/join:
    post:
      tags:
      - group-discovery
      summary: Join Discovered Group
      description: 'Join a discovered Telegram group.


        This will:

        1. Actually join the Telegram group using the workspace''s account

        2. Create a thread for syncing messages

        3. Update lifecycle to ''monitored''

        4. Enable auto-reply for the group (in draft mode)'
      operationId: join_discovered_group_api_groups_discovered__group_id__join_post
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JoinGroupRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JoinGroupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/{group_id}/leave:
    post:
      tags:
      - group-discovery
      summary: Leave Discovered Group
      description: Leave a group that was previously joined.
      operationId: leave_discovered_group_api_groups_discovered__group_id__leave_post
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaveGroupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/bulk-scan:
    post:
      tags:
      - group-discovery
      summary: Bulk Start Scans
      description: Start scans for multiple groups.
      operationId: bulk_start_scans_api_groups_discovered_bulk_scan_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkScanRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Bulk Start Scans Api Groups Discovered Bulk Scan Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/discovered/bulk-lifecycle:
    post:
      tags:
      - group-discovery
      summary: Bulk Set Lifecycle
      description: Set lifecycle for multiple groups.
      operationId: bulk_set_lifecycle_api_groups_discovered_bulk_lifecycle_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkLifecycleRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Bulk Set Lifecycle Api Groups Discovered Bulk Lifecycle Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SearchResultItem:
      properties:
        external_group_id:
          type: string
          title: External Group Id
        channel:
          type: string
          title: Channel
        title:
          type: string
          title: Title
        username:
          anyOf:
          - type: string
          - type: 'null'
          title: Username
        member_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Member Count
        group_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Type
        can_preview_history:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Can Preview History
        already_discovered:
          type: boolean
          title: Already Discovered
          default: false
        is_member:
          type: boolean
          title: Is Member
          default: false
      type: object
      required:
      - external_group_id
      - channel
      - title
      - username
      - member_count
      - group_type
      - can_preview_history
      title: SearchResultItem
      description: Search result item.
    GroupsListResponse:
      properties:
        groups:
          items:
            $ref: '#/components/schemas/GroupResponse'
          type: array
          title: Groups
        total:
          type: integer
          title: Total
      type: object
      required:
      - groups
      - total
      title: GroupsListResponse
      description: List of discovered groups.
    SetLifecycleRequest:
      properties:
        lifecycle:
          type: string
          title: Lifecycle
      type: object
      required:
      - lifecycle
      title: SetLifecycleRequest
      description: Request to set group lifecycle.
    BulkScanRequest:
      properties:
        group_ids:
          items:
            type: integer
          type: array
          title: Group Ids
        keywords:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Keywords
      type: object
      required:
      - group_ids
      title: BulkScanRequest
      description: Request to start bulk scans.
    StartScanRequest:
      properties:
        keywords:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Keywords
      type: object
      title: StartScanRequest
      description: Request to start a scan.
    SearchGroupsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/SearchResultItem'
          type: array
          title: Results
        query:
          type: string
          title: Query
      type: object
      required:
      - results
      - query
      title: SearchGroupsResponse
      description: Search results response.
    BulkLifecycleRequest:
      properties:
        group_ids:
          items:
            type: integer
          type: array
          title: Group Ids
        lifecycle:
          type: string
          title: Lifecycle
      type: object
      required:
      - group_ids
      - lifecycle
      title: BulkLifecycleRequest
      description: Request to set lifecycle for multiple groups.
    SearchGroupsRequest:
      properties:
        query:
          type: string
          title: Query
        limit:
          type: integer
          title: Limit
          default: 20
        channel:
          type: string
          title: Channel
          default: telegram
      type: object
      required:
      - query
      title: SearchGroupsRequest
      description: Request to search for groups.
    JoinGroupResponse:
      properties:
        success:
          type: boolean
          title: Success
        chat_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Chat Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        thread_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Thread Id
        already_member:
          type: boolean
          title: Already Member
          default: false
        auto_reply_enabled:
          type: boolean
          title: Auto Reply Enabled
          default: false
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - success
      title: JoinGroupResponse
      description: Response for joining a group.
    LeaveGroupResponse:
      properties:
        success:
          type: boolean
          title: Success
        already_left:
          type: boolean
          title: Already Left
          default: false
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - success
      title: LeaveGroupResponse
      description: Response for leaving a group.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ScanStatusResponse:
      properties:
        status:
          type: string
          title: Status
        progress:
          type: integer
          title: Progress
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        scan_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Scan Mode
      type: object
      required:
      - status
      - progress
      - error_code
      - scan_mode
      title: ScanStatusResponse
      description: Scan status response.
    JoinGroupRequest:
      properties:
        enable_auto_reply:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Auto Reply
      type: object
      title: JoinGroupRequest
      description: Request body for joining a group.
    CreateSessionRequest:
      properties:
        keywords:
          items:
            type: string
          type: array
          title: Keywords
        channel:
          type: string
          title: Channel
          default: telegram
        niche:
          anyOf:
          - type: string
          - type: 'null'
          title: Niche
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        geo:
          anyOf:
          - type: string
          - type: 'null'
          title: Geo
      type: object
      required:
      - keywords
      title: CreateSessionRequest
      description: Request to create a discovery session.
    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
    GroupResponse:
      properties:
        id:
          type: integer
          title: Id
        session_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Session Id
        channel:
          type: string
          title: Channel
        external_group_id:
          type: string
          title: External Group Id
        channel_ref:
          type: string
          title: Channel Ref
        title:
          type: string
          title: Title
        username:
          anyOf:
          - type: string
          - type: 'null'
          title: Username
        invite_link:
          anyOf:
          - type: string
          - type: 'null'
          title: Invite Link
        group_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Type
        can_preview_history:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Can Preview History
        member_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Member Count
        admin_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Admin Count
        about:
          anyOf:
          - type: string
          - type: 'null'
          title: About
        lifecycle:
          type: string
          title: Lifecycle
        scan_status:
          type: string
          title: Scan Status
        scan_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Scan Mode
        scan_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Scan Error
        scan_progress:
          type: integer
          title: Scan Progress
        overall_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Overall Score
        topic_relevance_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Topic Relevance Score
        engagement_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Engagement Score
        spam_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Spam Score
        dm_friendly_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Dm Friendly Score
        activity_health_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Activity Health Score
        score_confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Score Confidence
        is_disqualified:
          type: boolean
          title: Is Disqualified
        disqualify_reasons:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Disqualify Reasons
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - id
      - session_id
      - channel
      - external_group_id
      - channel_ref
      - title
      - username
      - invite_link
      - group_type
      - can_preview_history
      - member_count
      - admin_count
      - about
      - lifecycle
      - scan_status
      - scan_mode
      - scan_error
      - scan_progress
      - overall_score
      - topic_relevance_score
      - engagement_score
      - spam_score
      - dm_friendly_score
      - activity_health_score
      - score_confidence
      - is_disqualified
      - disqualify_reasons
      - created_at
      title: GroupResponse
      description: Discovered group response.
    AddLinkRequest:
      properties:
        link:
          type: string
          title: Link
        channel:
          type: string
          title: Channel
          default: telegram
      type: object
      required:
      - link
      title: AddLinkRequest
      description: Request to add a group from invite link.
    SessionResponse:
      properties:
        id:
          type: integer
          title: Id
        keywords:
          items:
            type: string
          type: array
          title: Keywords
        channel:
          type: string
          title: Channel
        niche:
          anyOf:
          - type: string
          - type: 'null'
          title: Niche
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        geo:
          anyOf:
          - type: string
          - type: 'null'
          title: Geo
        status:
          type: string
          title: Status
        groups_found:
          type: integer
          title: Groups Found
        groups_qualified:
          type: integer
          title: Groups Qualified
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
      type: object
      required:
      - id
      - keywords
      - channel
      - niche
      - language
      - geo
      - status
      - groups_found
      - groups_qualified
      - created_at
      - completed_at
      title: SessionResponse
      description: Discovery session response.