dialogbrain-com Referral API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Referral API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Referral
paths:
  /api/referral/code:
    get:
      tags:
      - Referral
      summary: Get Referral Code
      description: Get or create user's referral code.
      operationId: get_referral_code_api_referral_code_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__api__referral__ReferralCodeResponse'
  /api/referral/stats:
    get:
      tags:
      - Referral
      summary: Get Referral Stats
      description: Get detailed referral statistics for current user.
      operationId: get_referral_stats_api_referral_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralStatsResponse'
  /api/referral/list:
    get:
      tags:
      - Referral
      summary: Get Referral List
      description: Get paginated list of all referrals for current user.
      operationId: get_referral_list_api_referral_list_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          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:
                type: array
                items:
                  $ref: '#/components/schemas/ReferralListItem'
                title: Response Get Referral List Api Referral List Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/referral/validate/{code}:
    get:
      tags:
      - Referral
      summary: Validate Referral Code
      description: 'Validate a referral code (public endpoint, no auth required).


        Used by signup page to validate code before registration.'
      operationId: validate_referral_code_api_referral_validate__code__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          title: Code
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateCodeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/referral/affiliate/apply:
    post:
      tags:
      - Referral
      summary: Apply For Affiliate
      description: Apply to become an affiliate partner.
      operationId: apply_for_affiliate_api_referral_affiliate_apply_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AffiliateApplyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateApplyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/referral/affiliate/earnings:
    get:
      tags:
      - Referral
      summary: Get Affiliate Earnings
      description: Get affiliate earnings (affiliate users only).
      operationId: get_affiliate_earnings_api_referral_affiliate_earnings_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          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/AffiliateEarningsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/referral/affiliate/payout:
    post:
      tags:
      - Referral
      summary: Request Affiliate Payout
      description: 'Create a withdrawal request (заявка на вывод) for affiliate balance.


        No payout method is chosen — an admin processes the payout manually.

        Business validation failures (below minimum / insufficient balance)

        return success=False with a reason; only non-affiliates get 403.'
      operationId: request_affiliate_payout_api_referral_affiliate_payout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/referral/achievements:
    get:
      tags:
      - Referral
      summary: Get Achievements
      description: Get user's referral achievements and progress.
      operationId: get_achievements_api_referral_achievements_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementsResponse'
  /api/referral/tier:
    get:
      tags:
      - Referral
      summary: Get Tier Info
      description: Get user's current referrer tier and progress to next tier.
      operationId: get_tier_info_api_referral_tier_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierInfoResponse'
  /api/referral/code/create-child:
    post:
      tags:
      - Referral
      summary: Create Child Referral Code
      description: 'Create a child referral code for the current user.


        Auto-generated on signup, but can also be created manually.'
      operationId: create_child_referral_code_api_referral_code_create_child_post
      parameters:
      - name: parent_code
        in: query
        required: true
        schema:
          type: string
          title: Parent Code
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__api__referral__ReferralCodeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/referral/tree:
    get:
      tags:
      - Referral
      summary: Get Referral Tree
      description: 'Get referral tree starting from user''s code.


        Returns hierarchical structure with all descendants.'
      operationId: get_referral_tree_api_referral_tree_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreeNode'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ReferralListItem:
      properties:
        id:
          type: integer
          title: Id
        user_name:
          type: string
          title: User Name
        status:
          type: string
          title: Status
        fraud_score:
          type: integer
          title: Fraud Score
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        converted_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Converted At
        first_payment_cents:
          anyOf:
          - type: integer
          - type: 'null'
          title: First Payment Cents
        credits_awarded:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Awarded
      type: object
      required:
      - id
      - user_name
      - status
      - fraud_score
      - created_at
      - converted_at
      - first_payment_cents
      - credits_awarded
      title: ReferralListItem
    TierInfoResponse:
      properties:
        current_tier:
          type: string
          title: Current Tier
        conversions:
          type: integer
          title: Conversions
        next_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Tier
        conversions_to_next:
          type: integer
          title: Conversions To Next
        progress:
          type: number
          title: Progress
        perks:
          items:
            type: string
          type: array
          title: Perks
        multiplier:
          type: number
          title: Multiplier
      type: object
      required:
      - current_tier
      - conversions
      - conversions_to_next
      - progress
      - perks
      - multiplier
      title: TierInfoResponse
    MultiLevelStats:
      properties:
        level:
          type: integer
          title: Level
        signups:
          type: integer
          title: Signups
        conversions:
          type: integer
          title: Conversions
        credits_earned:
          type: integer
          title: Credits Earned
        commission_earned_cents:
          type: integer
          title: Commission Earned Cents
      type: object
      required:
      - level
      - signups
      - conversions
      - credits_earned
      - commission_earned_cents
      title: MultiLevelStats
    TreeNode:
      properties:
        userId:
          type: integer
          title: Userid
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        code:
          type: string
          title: Code
        level:
          type: integer
          title: Level
        signups:
          type: integer
          title: Signups
        conversions:
          type: integer
          title: Conversions
        creditsEarned:
          type: integer
          title: Creditsearned
        children:
          items:
            $ref: '#/components/schemas/TreeNode'
          type: array
          title: Children
          default: []
      type: object
      required:
      - userId
      - email
      - code
      - level
      - signups
      - conversions
      - creditsEarned
      title: TreeNode
    AchievementsResponse:
      properties:
        achievements:
          items:
            $ref: '#/components/schemas/Achievement'
          type: array
          title: Achievements
        unlocked_count:
          type: integer
          title: Unlocked Count
        total_count:
          type: integer
          title: Total Count
        next_achievement:
          anyOf:
          - $ref: '#/components/schemas/Achievement'
          - type: 'null'
      type: object
      required:
      - achievements
      - unlocked_count
      - total_count
      title: AchievementsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidateCodeResponse:
      properties:
        valid:
          type: boolean
          title: Valid
        referrer_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Referrer Name
        type:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
        bonus_credits:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bonus Credits
        signup_credits:
          anyOf:
          - type: integer
          - type: 'null'
          title: Signup Credits
        free_channels_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Free Channels Days
      type: object
      required:
      - valid
      title: ValidateCodeResponse
    ReferralSignup:
      properties:
        id:
          type: integer
          title: Id
        user_name:
          type: string
          title: User Name
        status:
          type: string
          title: Status
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        converted_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Converted At
        credits_awarded:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Awarded
      type: object
      required:
      - id
      - user_name
      - status
      - created_at
      - converted_at
      - credits_awarded
      title: ReferralSignup
    AffiliateEarning:
      properties:
        id:
          type: integer
          title: Id
        invoice_id:
          type: string
          title: Invoice Id
        referral_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Referral Name
        action_type:
          type: string
          title: Action Type
          default: payment
        amount_paid_cents:
          type: integer
          title: Amount Paid Cents
        commission_percent:
          type: number
          title: Commission Percent
        commission_cents:
          type: number
          title: Commission Cents
        status:
          type: string
          title: Status
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        paid_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Paid At
      type: object
      required:
      - id
      - invoice_id
      - amount_paid_cents
      - commission_percent
      - commission_cents
      - status
      - created_at
      - paid_at
      title: AffiliateEarning
    src__api__referral__ReferralCodeResponse:
      properties:
        code:
          type: string
          title: Code
        type:
          type: string
          title: Type
        bonus_credits_referrer:
          type: integer
          title: Bonus Credits Referrer
        bonus_credits_referred:
          type: integer
          title: Bonus Credits Referred
        revenue_share_percent:
          type: number
          title: Revenue Share Percent
        is_affiliate:
          type: boolean
          title: Is Affiliate
        total_signups:
          type: integer
          title: Total Signups
        total_conversions:
          type: integer
          title: Total Conversions
        total_credits_paid_out:
          type: integer
          title: Total Credits Paid Out
        share_url:
          type: string
          title: Share Url
      type: object
      required:
      - code
      - type
      - bonus_credits_referrer
      - bonus_credits_referred
      - revenue_share_percent
      - is_affiliate
      - total_signups
      - total_conversions
      - total_credits_paid_out
      - share_url
      title: ReferralCodeResponse
    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
    ReferralStatsResponse:
      properties:
        code:
          type: string
          title: Code
        type:
          type: string
          title: Type
        is_affiliate:
          type: boolean
          title: Is Affiliate
        revenue_share_percent:
          type: number
          title: Revenue Share Percent
          default: 0.0
        total_signups:
          type: integer
          title: Total Signups
        total_conversions:
          type: integer
          title: Total Conversions
        total_credits_paid_out:
          type: integer
          title: Total Credits Paid Out
        bonus_credits_balance:
          type: integer
          title: Bonus Credits Balance
        recent_signups:
          items:
            $ref: '#/components/schemas/ReferralSignup'
          type: array
          title: Recent Signups
        share_url:
          type: string
          title: Share Url
        multilevel_breakdown:
          items:
            $ref: '#/components/schemas/MultiLevelStats'
          type: array
          title: Multilevel Breakdown
          default: []
      type: object
      required:
      - code
      - type
      - is_affiliate
      - total_signups
      - total_conversions
      - total_credits_paid_out
      - bonus_credits_balance
      - recent_signups
      - share_url
      title: ReferralStatsResponse
    PayoutRequest:
      properties:
        amount_cents:
          type: integer
          title: Amount Cents
      type: object
      required:
      - amount_cents
      title: PayoutRequest
    AffiliateApplyResponse:
      properties:
        success:
          type: boolean
          title: Success
        status:
          type: string
          title: Status
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
      type: object
      required:
      - success
      - status
      title: AffiliateApplyResponse
    AffiliateEarningsResponse:
      properties:
        is_affiliate:
          type: boolean
          title: Is Affiliate
        total_earned_cents:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Earned Cents
          default: 0
        pending_cents:
          anyOf:
          - type: number
          - type: 'null'
          title: Pending Cents
          default: 0
        paid_cents:
          anyOf:
          - type: number
          - type: 'null'
          title: Paid Cents
          default: 0
        earnings:
          items:
            $ref: '#/components/schemas/AffiliateEarning'
          type: array
          title: Earnings
          default: []
      type: object
      required:
      - is_affiliate
      title: AffiliateEarningsResponse
    Achievement:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        unlocked:
          type: boolean
          title: Unlocked
        unlocked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Unlocked At
        progress:
          type: number
          title: Progress
        current:
          type: integer
          title: Current
        required:
          type: integer
          title: Required
      type: object
      required:
      - id
      - name
      - description
      - unlocked
      - progress
      - current
      - required
      title: Achievement
    PayoutResponse:
      properties:
        success:
          type: boolean
          title: Success
        payout_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Payout Id
        amount_cents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Amount Cents
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        available_cents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Available Cents
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        min_cents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Cents
      type: object
      required:
      - success
      title: PayoutResponse
    AffiliateApplyRequest:
      properties:
        reason:
          type: string
          title: Reason
      type: object
      required:
      - reason
      title: AffiliateApplyRequest