Equity Rank Referral API

openapi: 3.2.0
info:
  title: Equity Rank Com Referral API
  version: 0.1.0
  description: 'Operations tagged referral across 2 of this provider''s published API definitions: openapi.json, equity-rank-com-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Referral
paths:
  /api/referral/code:
    get:
      tags:
      - Referral
      summary: Get Or Create Code
      description: 'Return the current user''s referral code and link.

        Creates one if none exists yet.

        Also returns total_referred and bonus_days_earned for display.'
      operationId: get_or_create_code_api_referral_code_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Or Create Code Api Referral Code Get
      security:
      - HTTPBearer: []
  /api/referral/redeem:
    post:
      tags:
      - Referral
      summary: Redeem Code
      description: 'Redeem a referral code.

        Called by a new user during or after trial start (or auto-fired by the

        Stripe customer.subscription.created webhook via _redeem_referral_for_user).


        Rules:

        - Code must exist and have redeemed_at IS NULL (the template row)

        - Referrer cannot redeem their own code

        - Each user can only redeem one code ever

        - If referrer already has 30 bonus days, mark as redeemed but do not extend Stripe trial'
      operationId: redeem_code_api_referral_redeem_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Redeem Code Api Referral Redeem Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/referral/stats:
    get:
      tags:
      - Referral
      summary: Get Referral Stats
      description: Return the referrer's code, count of successful referrals, and total bonus days.
      operationId: get_referral_stats_api_referral_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Referral Stats Api Referral Stats Get
      security:
      - HTTPBearer: []
  /api/referral/activation-event:
    post:
      tags:
      - Referral
      summary: Activation Event
      description: 'Record an ACT-03 activation event server-side (survives ad-blockers).


        On ''initiated'', also tag the AUTHENTICATED caller''s unredeemed referral row

        source=''activation_trigger'' — this inviter-row PATCH is the AUTHORITATIVE

        K-factor attribution. The deep-link''s `er_src=activation` marker (Plan 01) is

        a secondary, forward-compat signal only and is NOT relied on here.


        Body: {"event": "shown" | "initiated"}. user_id comes from the verified

        session (get_current_user), never the body — the body''s only field is the

        event name, validated against a fixed allowlist (T-32-07 / T-32-08).'
      operationId: activation_event_api_referral_activation_event_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationEventRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Activation Event Api Referral Activation Event Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    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
    ActivationEventRequest:
      properties:
        event:
          type: string
          title: Event
      type: object
      required:
      - event
      title: ActivationEventRequest
    RedeemRequest:
      properties:
        code:
          type: string
          title: Code
      type: object
      required:
      - code
      title: RedeemRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- equity-rank-com-openapi.yml