Kagura AI Admin Referrals API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Admin Referrals API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: admin-referrals
  description: 'Admin: referral grant ledger and per-grant revocation'
paths:
  /api/v1/admin/referrals:
    get:
      tags:
      - admin-referrals
      summary: List Referral Grants
      description: 'List referral grants, newest first.


        Args:

        user: Authenticated system admin.

        referrer_user_id: Restrict to a single inviter.

        include_revoked: Include already-revoked rows (default true).

        limit: Page size.

        offset: Page offset.

        db: Database session.


        Returns:

        A page of ledger rows plus the total count.'
      operationId: list_referral_grants_api_v1_admin_referrals_get
      parameters:
      - name: referrer_user_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Referrer User Id
      - name: include_revoked
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Include Revoked
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          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/AdminReferralListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/referrals/{grant_id}/revoke:
    post:
      tags:
      - admin-referrals
      summary: Revoke Referral Grant
      description: 'Revoke a grant and recompute both sides'' referral bonuses.


        Idempotent: revoking an already-revoked grant is a no-op that still returns

        the row, so an admin retry (or a double-click) is harmless.


        Args:

        grant_id: The ledger row to revoke.

        payload: Revocation reason.

        user: Authenticated system admin.

        db: Database session.


        Returns:

        The revoked grant.


        Raises:

        HTTPException: 404 if no such grant exists.

        ConflictError: 409 ``RES-002`` if a workspace row the recompute locks

        stays busy; nothing is revoked or audited (the admin retries).'
      operationId: revoke_referral_grant_api_v1_admin_referrals__grant_id__revoke_post
      parameters:
      - name: grant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Grant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminReferralGrantResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AdminReferralGrantResponse:
      properties:
        id:
          title: Id
        referrer_user_id:
          title: Referrer User Id
        referrer_workspace_id:
          title: Referrer Workspace Id
        referred_user_id:
          title: Referred User Id
        referred_workspace_id:
          title: Referred Workspace Id
        referrer_bonus_memories:
          title: Referrer Bonus Memories
        referred_bonus_memories:
          title: Referred Bonus Memories
        granted_at:
          title: Granted At
        revoked_at:
          title: Revoked At
        revoked_reason:
          title: Revoked Reason
      type: object
      required:
      - id
      - referrer_user_id
      - referrer_workspace_id
      - referred_user_id
      - referred_workspace_id
      - referrer_bonus_memories
      - referred_bonus_memories
      - granted_at
      - revoked_at
      - revoked_reason
      title: AdminReferralGrantResponse
      description: A ledger row with both sides visible.
    RevokeRequest:
      properties:
        reason:
          type: string
          maxLength: 500
          minLength: 1
          title: Reason
      type: object
      required:
      - reason
      title: RevokeRequest
      description: 'Revocation payload.


        ``reason`` is required — not optional-with-a-default. Revoking shrinks a

        live quota, so there is no non-destructive case in which an empty reason

        would be acceptable (contrast ``admin.py``''s conditional-reason rule for

        ``workspace_slot_bonus``, where a non-negative delta is harmless).'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    AdminReferralListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AdminReferralGrantResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - items
      - total
      - limit
      - offset
      title: AdminReferralListResponse
      description: Paged ledger listing.