dialogbrain-com Group Scoring API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Group Scoring API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: group-scoring
paths:
  /api/groups/synced/scores:
    get:
      tags:
      - group-scoring
      summary: List Group Scores
      description: 'List synced groups with their engagement states and value segments.


        Returns all synced groups with optional score data. Groups without scores

        will have score=null.


        Auto-calculates scores if user has groups but no scores exist yet.'
      operationId: list_group_scores_api_groups_synced_scores_get
      parameters:
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by state: new, active, warm, cooling, dormant'
          title: State
        description: 'Filter by state: new, active, warm, cooling, dormant'
      - name: segment
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by segment: strong, medium, low, noise'
          title: Segment
        description: 'Filter by segment: strong, medium, low, noise'
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by group title
          title: Search
        description: Search by group title
      - name: channel
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by channel
          title: Channel
        description: Filter by channel
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupScoreListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/synced/scores/counts:
    get:
      tags:
      - group-scoring
      summary: Get Group Counts
      description: 'Get summary counts of groups by state and segment.


        Returns just the counts without the actual group data.'
      operationId: get_group_counts_api_groups_synced_scores_counts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__api__group_scoring__CountsResponse'
  /api/groups/synced/scores/info:
    get:
      tags:
      - group-scoring
      summary: Get Score Info
      description: 'Get display info for states and segments.


        Returns labels, icons, and colors for UI rendering.'
      operationId: get_score_info_api_groups_synced_scores_info_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/groups/synced/{thread_id}/refresh:
    post:
      tags:
      - group-scoring
      summary: Refresh Group Score
      description: 'Force recalculate score for a specific group.


        Triggers full recalculation based on current message data.'
      operationId: refresh_group_score_api_groups_synced__thread_id__refresh_post
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: integer
          title: Thread Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/synced/refresh-all:
    post:
      tags:
      - group-scoring
      summary: Refresh All Group Scores
      description: 'Recalculate scores for all synced groups.


        This may take a while for users with many groups.'
      operationId: refresh_all_group_scores_api_groups_synced_refresh_all_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/groups/synced/{thread_id}/members:
    get:
      tags:
      - group-scoring
      summary: Get Group Members
      description: 'Get list of members (participants) in a group.


        Returns entities that have sent messages in the group, with optional

        linkage to person records if they exist.'
      operationId: get_group_members_api_groups_synced__thread_id__members_get
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: integer
          title: Thread Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMembersListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/groups/synced/{thread_id}/member-count:
    get:
      tags:
      - group-scoring
      summary: Get Group Member Count
      description: 'Return the best available member count for a group across all workspace rows.


        Uses MAX(member_count) so that even if the current user''s thread row has a

        stale zero, we surface the real count from any other workspace member''s row.

        Works for both included and excluded groups.'
      operationId: get_group_member_count_api_groups_synced__thread_id__member_count_get
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: integer
          title: Thread Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    src__api__group_scoring__StateCounts:
      properties:
        new:
          type: integer
          title: New
          default: 0
        active:
          type: integer
          title: Active
          default: 0
        warm:
          type: integer
          title: Warm
          default: 0
        cooling:
          type: integer
          title: Cooling
          default: 0
        dormant:
          type: integer
          title: Dormant
          default: 0
      type: object
      title: StateCounts
      description: Count of groups by engagement state.
    src__api__group_scoring__CountsResponse:
      properties:
        states:
          $ref: '#/components/schemas/src__api__group_scoring__StateCounts'
          default:
            new: 0
            active: 0
            warm: 0
            cooling: 0
            dormant: 0
        segments:
          $ref: '#/components/schemas/src__api__group_scoring__SegmentCounts'
          default:
            strong: 0
            medium: 0
            low: 0
            noise: 0
      type: object
      title: CountsResponse
      description: Both state and segment counts.
    GroupWithScoreResponse:
      properties:
        id:
          type: integer
          title: Id
        title:
          type: string
          title: Title
        channel:
          type: string
          title: Channel
        channel_ref:
          type: string
          title: Channel Ref
        member_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Member Count
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        score:
          anyOf:
          - $ref: '#/components/schemas/GroupScoreResponse'
          - type: 'null'
      type: object
      required:
      - id
      - title
      - channel
      - channel_ref
      title: GroupWithScoreResponse
      description: Group with optional score data.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GroupScoreResponse:
      properties:
        thread_id:
          type: integer
          title: Thread Id
        title:
          type: string
          title: Title
        channel:
          type: string
          title: Channel
        engagement_state:
          type: string
          title: Engagement State
        segment:
          type: string
          title: Segment
        value_score:
          type: number
          title: Value Score
        recency_score:
          type: number
          title: Recency Score
        state_reason_codes:
          items:
            type: string
          type: array
          title: State Reason Codes
          default: []
        total_messages:
          type: integer
          title: Total Messages
          default: 0
        user_messages:
          type: integer
          title: User Messages
          default: 0
        unique_senders:
          type: integer
          title: Unique Senders
          default: 0
        messages_last_7d:
          type: integer
          title: Messages Last 7D
          default: 0
        messages_last_30d:
          type: integer
          title: Messages Last 30D
          default: 0
        spam_ratio:
          type: number
          title: Spam Ratio
          default: 0.0
        last_message_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Message At
        last_user_message_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last User Message At
        calculated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Calculated At
      type: object
      required:
      - thread_id
      - title
      - channel
      - engagement_state
      - segment
      - value_score
      - recency_score
      title: GroupScoreResponse
      description: Group score breakdown.
    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
    GroupScoreListResponse:
      properties:
        groups:
          items:
            $ref: '#/components/schemas/GroupWithScoreResponse'
          type: array
          title: Groups
        total:
          type: integer
          title: Total
        counts:
          $ref: '#/components/schemas/src__api__group_scoring__CountsResponse'
          default:
            states:
              active: 0
              cooling: 0
              dormant: 0
              new: 0
              warm: 0
            segments:
              low: 0
              medium: 0
              noise: 0
              strong: 0
      type: object
      required:
      - groups
      - total
      title: GroupScoreListResponse
      description: Paginated list of groups with scores.
    GroupMemberResponse:
      properties:
        entity_id:
          type: integer
          title: Entity Id
        name:
          type: string
          title: Name
        username:
          anyOf:
          - type: string
          - type: 'null'
          title: Username
        channel_ref:
          type: string
          title: Channel Ref
        channel:
          type: string
          title: Channel
        person_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Person Id
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
      type: object
      required:
      - entity_id
      - name
      - channel_ref
      - channel
      title: GroupMemberResponse
      description: A member (participant) in a group.
    GroupMembersListResponse:
      properties:
        members:
          items:
            $ref: '#/components/schemas/GroupMemberResponse'
          type: array
          title: Members
        total:
          type: integer
          title: Total
      type: object
      required:
      - members
      - total
      title: GroupMembersListResponse
      description: List of group members.
    src__api__group_scoring__SegmentCounts:
      properties:
        strong:
          type: integer
          title: Strong
          default: 0
        medium:
          type: integer
          title: Medium
          default: 0
        low:
          type: integer
          title: Low
          default: 0
        noise:
          type: integer
          title: Noise
          default: 0
      type: object
      title: SegmentCounts
      description: Count of groups by value segment.