Kagura AI Beta Invites API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Beta Invites API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: beta-invites
  description: 'Closed-beta invite links (Issue #1581): a signed-in user mints a one-time link that lets one new person through the signup gate. Session auth only except the public preview, and the whole surface 404s unless the deployment sets ENABLE_BETA_INVITES.'
paths:
  /api/v1/beta-invites/me:
    get:
      tags:
      - beta-invites
      summary: Get My Beta Invites
      description: 'Return the caller''s invite quota standing and their invites, newest first.


        Args:

        user: Authenticated session user.

        db: Database session.

        limit: Invites per page (1-100, default 50); quota counts remain global.

        offset: Number of invites to skip in the stable newest-first ordering.


        Returns:

        ``quota`` / ``used`` (= ``active`` + ``redeemed``) / ``remaining`` and the

        per-invite lifecycle, label and — for redeemed invites — admitted e-mail.'
      operationId: get_my_beta_invites_api_v1_beta_invites_me_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          maximum: 9223372036854775807
          minimum: 0
          default: 0
          title: Offset
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaInviteSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/beta-invites:
    post:
      tags:
      - beta-invites
      summary: Create Beta Invite
      description: 'Mint a one-time invite link. The URL is returned here and never again.


        Args:

        request: FastAPI request (IP / User-Agent for the audit row).

        user: Authenticated session user (the inviter).

        body: Optional ``{"label": ...}`` (#1595). Clients that predate it send

        no body at all, which keeps working.

        db: Database session.


        Returns:

        The invite id, its plaintext URL, its expiry and its label.


        Raises:

        BetaInviteQuotaExceededError: 409 ``BETA-INVITE-001`` at the cap.'
      operationId: create_beta_invite_api_v1_beta_invites_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/BetaInviteCreateRequest'
              - type: 'null'
              title: Body
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaInviteCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/beta-invites/{invite_id}/reissue:
    post:
      tags:
      - beta-invites
      summary: Reissue Beta Invite
      description: 'Replace an own ``active`` or ``expired`` invite with a fresh link (#1595).


        For a recipient who lost the link: only the hash is stored, so the URL cannot

        be shown again. The old invite is revoked and a new one carrying the same

        label is minted in one transaction; the quota standing of an ``active``

        invite is unchanged. Takes no body.


        Args:

        invite_id: The invite to replace.

        request: FastAPI request (IP / User-Agent for the audit rows).

        user: Authenticated session user.

        db: Database session.


        Returns:

        Exactly the create payload — the new invite and its plaintext URL, once.


        Raises:

        NotFoundException: 404 — unknown id, or someone else''s invite.

        BetaInviteAlreadyRedeemedError: 409 ``BETA-INVITE-002``.

        BetaInviteAlreadyRevokedError: 409 ``BETA-INVITE-003`` — also what the

        second request of a double-click gets; it mints nothing.

        BetaInviteQuotaExceededError: 409 ``BETA-INVITE-001`` — an ``expired``

        invite holds no slot, so reissuing one at the cap is refused (and the

        invite is left as it was).'
      operationId: reissue_beta_invite_api_v1_beta_invites__invite_id__reissue_post
      parameters:
      - name: invite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Invite Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaInviteCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/beta-invites/{invite_id}:
    delete:
      tags:
      - beta-invites
      summary: Revoke Beta Invite
      description: 'Revoke one of the caller''s own unused invites (frees its quota slot).


        Args:

        invite_id: The invite to revoke.

        request: FastAPI request (IP / User-Agent for the audit row).

        user: Authenticated session user.

        db: Database session.


        Returns:

        204 No Content.


        Raises:

        NotFoundException: 404 — unknown id, or someone else''s invite.

        BetaInviteAlreadyRedeemedError: 409 ``BETA-INVITE-002``.'
      operationId: revoke_beta_invite_api_v1_beta_invites__invite_id__delete
      parameters:
      - name: invite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Invite Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/beta-invites/{token}/preview:
    get:
      tags:
      - beta-invites
      summary: Preview Beta Invite
      description: 'Tell the public landing page whether a link is still usable. No auth.


        Read-only — previewing never consumes the invite. Reveals nothing about the

        inviter.


        Args:

        token: The plaintext token from the ``/join/{token}`` URL.

        request: FastAPI request (caller IP for the rate-limit bucket).

        db: Database session.


        Returns:

        ``{"valid": true, "expires_at": ...}`` for a usable link.


        Raises:

        RateLimitError: 429 when the caller''s per-IP bucket is exhausted.

        NotFoundException: 404 — unknown, revoked, or malformed token.

        BetaInviteGoneError: 410 — expired or already redeemed.'
      operationId: preview_beta_invite_api_v1_beta_invites__token__preview_get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaInvitePreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BetaInviteSummaryResponse:
      properties:
        quota:
          title: Quota
        used:
          title: Used
        active:
          title: Active
        redeemed:
          title: Redeemed
        remaining:
          title: Remaining
        invites:
          title: Invites
        next_offset:
          title: Next Offset
      type: object
      required:
      - quota
      - used
      - active
      - redeemed
      - remaining
      - invites
      title: BetaInviteSummaryResponse
      description: 'The caller''s quota standing. ``null`` quota / remaining = unlimited (admin).


        ``used`` counts the invites occupying a slot; ``active`` and ``redeemed`` are

        its two parts (``active + redeemed == used``), so a client never re-derives

        them from the list.'
    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
    BetaInviteCreateRequest:
      properties:
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
      type: object
      title: BetaInviteCreateRequest
      description: Optional body of ``POST /beta-invites`` (#1595). No body at all is valid.
    BetaInviteCreatedResponse:
      properties:
        id:
          title: Id
        url:
          title: Url
        expires_at:
          title: Expires At
        label:
          title: Label
      type: object
      required:
      - id
      - url
      - expires_at
      - label
      title: BetaInviteCreatedResponse
      description: 'A freshly minted invite — the only payload that ever carries the URL.


        Returned by both create and reissue.'
    BetaInvitePreviewResponse:
      properties:
        valid:
          title: Valid
        expires_at:
          title: Expires At
      type: object
      required:
      - valid
      - expires_at
      title: BetaInvitePreviewResponse
      description: What the public landing page may know about a usable link.