Wispr Flow Sandbox User API

openapi: 3.2.0
info:
  title: Wispr Backend Sandbox User API
  description: Wispr Backend API
  version: 0.5.2
tags:
- name: sandbox-user
paths:
  /api/v1/sandbox-user/create-and-signin:
    post:
      tags:
      - sandbox-user
      summary: Create and sign in a sandbox user
      description: 'Create a sandbox user and sign in.

        **Authentication Required**: Must be logged in with a @wispr.ai email address.

        This endpoint:

        1. Creates a Supabase user with @wispr.test email

        2. Creates all necessary database records with onboarding NOT completed

        3. Returns auth tokens for immediate sign-in'
      operationId: create_and_signin_sandbox_user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxUserRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSandboxUserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyHeaderPatched: []
  /api/v1/sandbox-user/destroy:
    delete:
      tags:
      - sandbox-user
      summary: Destroy a sandbox user
      description: 'Destroy a sandbox user by deleting all associated data from all tables and services.

        This endpoint:

        1. Validates the user has a @wispr.test email

        2. Checks if user is the only member of an enterprise and deletes the enterprise if so

        3. Uses the existing compliance-ready user deletion service

        4. Deletes data from: main DB (incl. Subscription via CASCADE), usage DB, Customer.io, Segment, PostHog, ClickHouse

        5. Cancels any active subscriptions via Stripe

        6. Deletes from Supabase Auth

        **WARNING**: This permanently deletes all data for the sandbox user and their enterprise if they''re the only member.'
      operationId: destroy_sandbox_user
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestroySandboxUserResponse'
      security:
      - ApiKeyHeaderPatched: []
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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateSandboxUserResponse:
      properties:
        access_token:
          type: string
          title: Access Token
          description: Access token for authentication
        refresh_token:
          type: string
          title: Refresh Token
          description: Refresh token
        email:
          type: string
          title: Email
          description: The sandbox user's email
        user_id:
          type: string
          title: User Id
          description: The sandbox user's ID
        password:
          type: string
          title: Password
          description: The sandbox user's password (use with email to sign into client apps)
      type: object
      required:
      - access_token
      - refresh_token
      - email
      - user_id
      - password
      title: CreateSandboxUserResponse
      description: Response model for sandbox user creation.
    CreateSandboxUserRequest:
      properties:
        plan:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan
          description: Subscription plan type (free, pro, student, team, business)
        billing_interval:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Interval
          description: Billing interval (monthly, yearly)
        skip_default_trial:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Skip Default Trial
          description: Seed user.skip_default_trial column
        bonus_ends_at:
          anyOf:
          - type: integer
            format: int64
          - type: 'null'
          title: Bonus Ends At
          description: Seed user.bonus_ends_at column (Unix epoch seconds)
        words_this_week:
          anyOf:
          - type: integer
          - type: 'null'
          title: Words This Week
          description: Seed user_stats.words_this_week column
        first_weekly_limit_hit_at:
          anyOf:
          - type: integer
            format: int64
          - type: 'null'
          title: First Weekly Limit Hit At
          description: Seed user_stats.first_weekly_limit_hit_at column (Unix epoch seconds)
        is_student:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Student
          description: Seed user.is_student column
      type: object
      title: CreateSandboxUserRequest
      description: Request model for creating a sandbox user.
    DestroySandboxUserResponse:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable message
        failed_services:
          items:
            type: string
          type: array
          title: Failed Services
          description: List of services that failed to delete data
      type: object
      required:
      - message
      title: DestroySandboxUserResponse
      description: Response model for sandbox user destruction.
  securitySchemes:
    ApiKeyHeaderPatched:
      type: apiKey
      in: header
      name: Authorization
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key