swagger: '2.0'
info:
  title: Eyenak AI API Documentation
  description: |2

    # Eyenak AI API Documentation

    Welcome to the Eyenak AI API documentation. This comprehensive guide provides detailed information about all available endpoints, authentication methods, and integration capabilities.

    ## Features

    - **AI Chat Communication**: Interact with multiple EyeNak AI models with streaming support
    - **Image Generation**: Create AI-generated images using EyeNak Pro and EyeNak Ultra
    - **Video Generation**: Generate AI videos from text prompts with iPhone-style effects
    - **Text Enhancement**: AI-powered text improvement and rewriting
    - **Voice Features**: Voice-to-text transcription and text-to-speech generation
    - **Session Management**: Manage chat sessions with history and analytics
    - **Authentication**: JWT-based secure authentication with 2FA support
    - **Profile & Analytics**: Comprehensive user statistics and activity tracking
    - **Gamification**: Achievements, streaks, and user engagement features
    - **Payment & Wallet**: Integrated payment processing and wallet management

    ## Authentication

    Most endpoints require authentication via:
    - **Session Cookie** (for web applications)
    - **JWT Token** (for mobile/external applications)

    Include the JWT token in the Authorization header:

    ```
    Authorization: Bearer <your-jwt-token>
    ```

    ## Browsing Available Endpoints

    Use the interactive documentation pages:
    - **Swagger UI**: `/api/docs/swagger/` - Interactive exploration and testing
    - **ReDoc**: `/api/docs/redoc/` - Beautiful API documentation
    - **Developer Portal**: `/api/docs/portal/` - Complete endpoint reference

    ## Support

    For API support, contact: support@eyenak.ai
  termsOfService: https://eyenak.ai/terms/
  contact:
    email: support@eyenak.ai
  license:
    name: Proprietary
  version: v2.0
host: eyenak.ai
schemes:
- https
basePath: /
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
security:
- Bearer: []
paths:
  /accounts/api/2fa/disable/:
    post:
      operationId: accounts_api_2fa_disable_create
      description: Disable 2FA (requires verification)
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/2fa/enable/:
    post:
      operationId: accounts_api_2fa_enable_create
      description: Enable 2FA and generate QR code
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/2fa/recovery/complete/:
    post:
      operationId: accounts_api_2fa_recovery_complete_create
      description: Complete the 2FA recovery process by disabling 2FA after verification
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - recovery_id
          type: object
          properties:
            recovery_id:
              description: Recovery request ID (from verify step)
              type: integer
      responses:
        '200':
          description: 2FA disabled successfully
        '400':
          description: Bad request - Recovery not verified or expired
        '404':
          description: Recovery request not found
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/email/remove/:
    post:
      operationId: accounts_api_2fa_recovery_email_remove_create
      description: Remove the recovery email from user profile
      parameters: []
      responses:
        '200':
          description: Recovery email removed successfully
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/email/update/:
    post:
      operationId: accounts_api_2fa_recovery_email_update_create
      description: Add or update recovery email for 2FA recovery. Sends a verification
        code to the new email.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - recovery_email
          type: object
          properties:
            recovery_email:
              description: Recovery email address
              type: string
      responses:
        '200':
          description: Verification code sent successfully
        '400':
          description: Bad request - Invalid email or same as primary
        '401':
          description: Unauthorized
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/email/verify/:
    post:
      operationId: accounts_api_2fa_recovery_email_verify_create
      description: Verify the recovery email with the 6-digit code sent
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - code
          type: object
          properties:
            code:
              description: 6-digit verification code
              type: string
      responses:
        '200':
          description: Recovery email verified successfully
        '400':
          description: Bad request - Invalid or expired code
        '401':
          description: Unauthorized
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/options/:
    get:
      operationId: accounts_api_2fa_recovery_options_list
      description: Get available 2FA recovery options for a user by email. Returns
        masked email/phone options.
      parameters:
      - name: email
        in: query
        description: User's email address
        required: true
        type: string
      responses:
        '200':
          description: Recovery options retrieved
          schema:
            type: object
            properties:
              options:
                type: array
                items:
                  type: object
              has_2fa:
                type: boolean
        '400':
          description: Bad request - Email required
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/phone/remove/:
    post:
      operationId: accounts_api_2fa_recovery_phone_remove_create
      description: Remove the recovery phone from user profile
      parameters: []
      responses:
        '200':
          description: Recovery phone removed successfully
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/phone/update/:
    post:
      operationId: accounts_api_2fa_recovery_phone_update_create
      description: Add or update recovery phone for SMS-based 2FA recovery. Sends
        a verification code via SMS.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - recovery_phone
          - dial_code_id
          type: object
          properties:
            recovery_phone:
              description: Recovery phone number
              type: string
            dial_code_id:
              description: Country dial code ID
              type: integer
      responses:
        '200':
          description: Verification code sent successfully
        '400':
          description: Bad request - Invalid phone or same as primary
        '401':
          description: Unauthorized
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/phone/verify/:
    post:
      operationId: accounts_api_2fa_recovery_phone_verify_create
      description: Verify the recovery phone with the 6-digit code sent
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - code
          type: object
          properties:
            code:
              description: 6-digit verification code
              type: string
      responses:
        '200':
          description: Recovery phone verified successfully
        '400':
          description: Bad request - Invalid or expired code
        '401':
          description: Unauthorized
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/request/:
    post:
      operationId: accounts_api_2fa_recovery_request_create
      description: Request 2FA recovery for users who lost their authenticator device.
        Sends verification code via email or SMS.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - email
          type: object
          properties:
            email:
              description: User email address
              type: string
            method:
              description: Recovery method (email or sms)
              type: string
              enum:
              - email
              - sms
      responses:
        '200':
          description: Verification code sent successfully
        '400':
          description: Bad request - Invalid email or method
        '429':
          description: Too many requests
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/settings/:
    get:
      operationId: accounts_api_2fa_recovery_settings_list
      description: Get current 2FA recovery options settings for the authenticated
        user
      parameters: []
      responses:
        '200':
          description: Recovery settings retrieved successfully
          schema:
            type: object
            properties:
              primary_email:
                type: string
              recovery_email:
                type: string
                nullable: true
              recovery_email_verified:
                type: boolean
              primary_phone:
                type: string
                nullable: true
              recovery_phone:
                type: string
                nullable: true
              recovery_phone_verified:
                type: boolean
              has_2fa:
                type: boolean
        '401':
          description: Unauthorized
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/recovery/verify/:
    post:
      operationId: accounts_api_2fa_recovery_verify_create
      description: Verify the 2FA recovery code sent via email/SMS
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - recovery_id
          - code
          type: object
          properties:
            recovery_id:
              description: Recovery request ID
              type: integer
            code:
              description: 6-digit verification code
              type: string
      responses:
        '200':
          description: Code verified successfully
        '400':
          description: Bad request - Invalid or expired code
        '404':
          description: Recovery request not found
      tags:
      - Security - 2FA Recovery
    parameters: []
  /accounts/api/2fa/status/:
    get:
      operationId: accounts_api_2fa_status_list
      description: Get current 2FA status for user
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/2fa/verify/:
    post:
      operationId: accounts_api_2fa_verify_create
      description: Verify 2FA code and enable 2FA
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/achievements/:
    get:
      operationId: accounts_api_achievements_list
      description: Get all achievements and user's progress
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/achievements/notifications/:
    get:
      operationId: accounts_api_achievements_notifications_list
      description: Get unlocked achievements that haven't been notified yet
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/activity-history/:
    get:
      operationId: accounts_api_activity-history_list
      description: Get comprehensive activity history with pagination and filters
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/activity/record/:
    post:
      operationId: accounts_api_activity_record_create
      description: Record user activity for streak tracking
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/change-language/:
    post:
      operationId: accounts_api_change-language_create
      description: ''
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/change-password/:
    post:
      operationId: accounts_api_change-password_create
      description: Change user password
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/change-theme/:
    post:
      operationId: accounts_api_change-theme_create
      description: Change user's theme preference
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/change-timezone/:
    post:
      operationId: accounts_api_change-timezone_create
      description: Change user's timezone preference
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/conversations-history/:
    get:
      operationId: accounts_api_conversations-history_list
      description: Get user's conversation history with pagination
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/delete-account/:
    post:
      operationId: accounts_api_delete-account_create
      description: Delete user account with OTP verification
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/enhancements-history/:
    get:
      operationId: accounts_api_enhancements-history_list
      description: Get user's AI text enhancement history with pagination and filtering
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/export-data/:
    post:
      operationId: accounts_api_export-data_create
      description: Export user data in JSON or CSV format
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/feature-upgrade/confirm/:
    post:
      operationId: accounts_api_feature-upgrade_confirm_create
      summary: Confirm Feature Upgrade Payment
      description: |2

        Confirm a completed feature upgrade purchase.

        Use this endpoint after:
        - Stripe payment success (verify PaymentIntent)
        - HyperPay payment callback (verify with resourcePath)

        For wallet payments, confirmation is automatic.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - transaction_id
          type: object
          properties:
            transaction_id:
              description: Transaction ID to confirm
              type: integer
            resource_path:
              description: HyperPay resource path (for HyperPay payments)
              type: string
      responses:
        '200':
          description: Payment confirmed successfully
          examples:
            application/json:
              success: true
              message: Feature upgrade confirmed!
              quantity_added: 150
        '400':
          description: Invalid request or already processed
        '404':
          description: Transaction not found
      tags:
      - Feature Upgrade
    parameters: []
  /accounts/api/feature-upgrade/history/:
    get:
      operationId: accounts_api_feature-upgrade_history_list
      summary: Get Feature Upgrade History
      description: |2

        Get paginated list of feature upgrade transaction history for the authenticated user.

        Returns all transactions including completed, pending, and failed ones.
      parameters:
      - name: page
        in: query
        description: 'Page number for pagination (default: 1)'
        type: integer
        default: 1
      responses:
        '200':
          description: Transaction history retrieved successfully
          examples:
            application/json:
              success: true
              transactions:
              - id: 1
                feature_name: AI Enhancement
                quantity: 150
                amount_display: $6.90
                status: completed
                payment_method: wallet
                created_at: '2024-01-15T10:30:00Z'
              total: 5
              page: 1
              per_page: 20
              total_pages: 1
      tags:
      - Feature Upgrade
    parameters: []
  /accounts/api/feature-upgrade/initiate/:
    post:
      operationId: accounts_api_feature-upgrade_initiate_create
      summary: Initiate Feature Upgrade Purchase
      description: |2

        Initiate a feature upgrade purchase.

        **Payment Methods:**
        - `wallet` - Pay using wallet balance (instant)
        - `stripe` - Pay via credit card (returns client_secret for Stripe.js)
        - `hyperpay` - Pay via HyperPay/MADA (returns checkout_url for redirect)

        **Custom Quantity:**
        - Pass `custom_quantity` instead of `pricing_tier_id` for custom amounts
        - Uses the best unit price (lowest per-unit cost)
        - Example: 150 units at $0.04/unit = $6.00 + VAT
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - feature_id
          type: object
          properties:
            feature_id:
              description: Feature ID to upgrade
              type: integer
            pricing_tier_id:
              description: Predefined pricing tier ID (optional if custom_quantity
                used)
              type: integer
            custom_quantity:
              description: Custom quantity (optional, uses best unit price)
              type: integer
            payment_method:
              type: string
              enum:
              - wallet
              - stripe
              - hyperpay
              default: stripe
      responses:
        '200':
          description: Purchase initiated successfully
          examples:
            application/json:
              success: true
              message: Feature upgrade purchased successfully!
              transaction_id: 123
              invoice_number: INV-202512-ABC123
              amount_paid: $6.90
              quantity_added: 150
        '400':
          description: Invalid request parameters
        '402':
          description: Insufficient wallet balance
        '404':
          description: Feature or pricing tier not found
        '500':
          description: Payment gateway error
      tags:
      - Feature Upgrade
    parameters: []
  /accounts/api/feature-upgrade/invoice/{transaction_id}/:
    get:
      operationId: accounts_api_feature-upgrade_invoice_read
      summary: Download Feature Upgrade Invoice
      description: |2

        Download PDF invoice for a completed feature upgrade transaction.

        The invoice includes:
        - Invoice number and date
        - User details
        - Feature name and quantity purchased
        - Price breakdown (subtotal, VAT, total)
        - Payment method used
      parameters:
      - name: transaction_id
        in: path
        description: ID of the transaction to download invoice for
        required: true
        type: integer
      responses:
        '200':
          description: PDF file download
        '400':
          description: Invoice not available for this transaction
        '404':
          description: Transaction not found
        '500':
          description: Error generating invoice
      tags:
      - Feature Upgrade
    parameters:
    - name: transaction_id
      in: path
      required: true
      type: string
  /accounts/api/feature-upgrade/pricing/:
    get:
      operationId: accounts_api_feature-upgrade_pricing_list
      summary: Get Feature Upgrade Pricing
      description: |2

        Get available upgrade pricing tiers for a specific feature.

        Returns:
        - Feature details (id, name, description)
        - Pricing tiers with quantities and prices
        - Custom quantity pricing info (unit price for custom purchases)
        - User's current quota and usage for the feature
      parameters:
      - name: feature_id
        in: query
        description: Feature ID to get pricing for
        required: true
        type: integer
      responses:
        '200':
          description: Pricing tiers retrieved successfully
          examples:
            application/json:
              success: true
              feature:
                id: 2
                name: AI Enhancement
                description: AI-powered text enhancement
              pricing_tiers:
              - id: 1
                quantity: 50
                price_usd: '3.00'
                unit_price_usd: '0.0600'
                is_popular: false
              - id: 2
                quantity: 250
                price_usd: '12.00'
                unit_price_usd: '0.0480'
                is_popular: true
              - id: 3
                quantity: 500
                price_usd: '20.00'
                unit_price_usd: '0.0400'
                is_popular: false
              custom_quantity:
                enabled: true
                unit_price_usd: '0.0400'
                min_quantity: 1
                max_quantity: 10000
              current_limit: 50
              current_usage: 10
              remaining: 40
        '400':
          description: Missing feature_id parameter
        '404':
          description: Feature not found
      tags:
      - Feature Upgrade
    parameters: []
  /accounts/api/login-history/:
    get:
      operationId: accounts_api_login-history_list
      description: Return login history items (successful and failed) and summary
        stats with server-side pagination.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/messages-history/:
    get:
      operationId: accounts_api_messages-history_list
      description: Get user's message history with pagination
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/payment/{reference}/:
    get:
      operationId: accounts_api_payment_read
      description: Get detailed information about a specific payment by reference.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters:
    - name: reference
      in: path
      required: true
      type: string
  /accounts/api/plan-usage-stats/:
    get:
      operationId: accounts_api_plan-usage-stats_list
      description: Get comprehensive plan usage statistics for the current user.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/register/:
    post:
      operationId: accounts_api_register_create
      description: User registration endpoint - creates new user and returns JWT token
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/request-delete-otp/:
    post:
      operationId: accounts_api_request-delete-otp_create
      description: Request OTP for account deletion
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/request-password-reset/:
    post:
      operationId: accounts_api_request-password-reset_create
      description: Send OTP to user email for password reset
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/resend-restore-otp/:
    post:
      operationId: accounts_api_resend-restore-otp_create
      description: Resend OTP for account restoration
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/reset-password/:
    post:
      operationId: accounts_api_reset-password_create
      description: Reset password using verified token
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/response-times/:
    get:
      operationId: accounts_api_response-times_list
      description: Get average response times for user's sessions
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/restore-account/:
    post:
      operationId: accounts_api_restore-account_create
      description: Restore archived account using OTP verification
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/sessions/:
    get:
      operationId: accounts_api_sessions_list
      description: Get all active sessions for the user
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/sessions/revoke-all/:
    post:
      operationId: accounts_api_sessions_revoke-all_create
      description: Revoke all sessions except current with detailed status messages
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/sessions/{session_id}/revoke/:
    post:
      operationId: accounts_api_sessions_revoke_create
      description: Revoke a specific session
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters:
    - name: session_id
      in: path
      required: true
      type: string
  /accounts/api/streak/:
    get:
      operationId: accounts_api_streak_list
      description: Get user's current streak information
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/token-history/:
    get:
      operationId: accounts_api_token-history_list
      description: Get user's wallet transaction history with pagination
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/update-profile/:
    post:
      operationId: accounts_api_update-profile_create
      description: Update user profile information
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/upload-profile-picture/:
    post:
      operationId: accounts_api_upload-profile-picture_create
      description: Upload user profile picture
      parameters: []
      responses:
        '201':
          description: ''
      consumes:
      - multipart/form-data
      - application/x-www-form-urlencoded
      tags:
      - accounts
    parameters: []
  /accounts/api/usage-trends/:
    get:
      operationId: accounts_api_usage-trends_list
      description: Get user's usage trends for the last 7 days
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/verify-2fa-login/:
    post:
      operationId: accounts_api_verify-2fa-login_create
      description: Verify 2FA code and complete login
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/verify-reset-otp/:
    post:
      operationId: accounts_api_verify-reset-otp_create
      description: Verify OTP for password reset
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/api/wallet-balance/:
    get:
      operationId: accounts_api_wallet-balance_list
      description: Get user's current wallet balance
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/check-auth/:
    get:
      operationId: accounts_check-auth_list
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/countries/:
    get:
      operationId: accounts_countries_list
      description: Get list of all countries with dial codes
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/login/email/:
    post:
      operationId: accounts_login_email_create
      description: ''
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/login/mobile/:
    post:
      operationId: accounts_login_mobile_create
      description: ''
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/login/otp/:
    post:
      operationId: accounts_login_otp_create
      description: ''
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/logout/:
    post:
      operationId: accounts_logout_create
      description: Logout user and clear session, but preserve language preference
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /accounts/otp/request/:
    post:
      operationId: accounts_otp_request_create
      description: ''
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - accounts
    parameters: []
  /chatbot/admin/api/audit-logs/:
    get:
      operationId: chatbot_admin_api_audit-logs_list
      summary: Get audit logs (admin)
      description: Get audit logs with filtering (admin only)
      parameters:
      - name: user_id
        in: query
        description: Filter by user ID
        type: string
      - name: action
        in: query
        description: Filter by action
        type: string
      - name: page
        in: query
        description: Page number
        type: integer
      responses:
        '200':
          description: Audit logs list
        '403':
          description: Permission denied
      tags:
      - Admin Features
    parameters: []
  /chatbot/admin/api/chat-history/:
    get:
      operationId: chatbot_admin_api_chat-history_list
      summary: Get chat history (admin)
      description: Get chat sessions with advanced filtering for admin investigation
      parameters:
      - name: user_id
        in: query
        description: Filter by user ID
        type: string
      - name: company_id
        in: query
        description: Filter by company ID
        type: string
      - name: page
        in: query
        description: Page number
        type: integer
      responses:
        '200':
          description: Chat sessions list
        '403':
          description: Permission denied
      tags:
      - Admin Features
    parameters: []
  /chatbot/admin/api/export/:
    post:
      operationId: chatbot_admin_api_export_create
      summary: Export chat data (admin)
      description: Export chat data as CSV or JSON (admin only)
      parameters:
      - name: data
        in: body
        required: true
        schema:
          type: object
          properties:
            format:
              type: string
              enum:
              - csv
              - json
            session_ids:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Exported data file
        '400':
          description: No sessions selected
        '403':
          description: Permission denied
      tags:
      - Admin Features
    parameters: []
  /chatbot/admin/api/messages/{session_id}/:
    get:
      operationId: chatbot_admin_api_messages_read
      summary: Get message history (admin)
      description: Get all messages for a session with full details (admin only)
      parameters: []
      responses:
        '200':
          description: Message history
        '403':
          description: Permission denied
        '404':
          description: Session not found
      tags:
      - Admin Features
    parameters:
    - name: session_id
      in: path
      required: true
      type: string
  /chatbot/admin/chat-history/:
    get:
      operationId: chatbot_admin_chat-history_list
      summary: Admin chat history panel
      description: Render the admin chat history investigation interface
      parameters: []
      responses:
        '200':
          description: Admin chat history interface
        '403':
          description: Permission denied
      tags:
      - Admin Features
    parameters: []
  /chatbot/api/actions/copy/:
    post:
      operationId: chatbot_api_actions_copy_create
      summary: Copy Message
      description: Track message copy action and return formatted text.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          type: object
          properties:
            message_id:
              description: Message ID to copy
              type: integer
      responses:
        '200':
          description: Message content
          schema:
            type: object
            properties:
              success:
                type: boolean
              content:
                description: Message content
                type: string
        '404':
          description: Message not found
      tags:
      - Message Actions
    parameters: []
  /chatbot/api/actions/rating/:
    post:
      operationId: chatbot_api_actions_rating_create
      summary: Submit Message Rating
      description: Submit thumbs up/down rating for a message with optional feedback
        text and categories.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          - rating
          type: object
          properties:
            message_id:
              description: Message ID to rate
              type: integer
            rating:
              description: 1 for thumbs up, -1 for thumbs down
              type: integer
              enum:
              - 1
              - -1
            feedback_text:
              description: Optional feedback text
              type: string
            feedback_categories:
              description: Feedback categories
              type: object
      responses:
        '200':
          description: Rating submitted
          schema:
            type: object
            properties:
              success:
                type: boolean
              rating_id:
                type: integer
              created:
                type: boolean
        '400':
          description: Invalid request
        '401':
          description: Authentication required
      tags:
      - Message Actions
    parameters: []
  /chatbot/api/actions/report/:
    post:
      operationId: chatbot_api_actions_report_create
      summary: Report Message
      description: Submit a report for inappropriate or problematic message content.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          - reason
          type: object
          properties:
            message_id:
              description: Message ID to report
              type: integer
            reason:
              type: string
              enum:
              - inappropriate_content
              - spam
              - harmful_content
              - factually_incorrect
              - privacy_concern
              - copyright
              - other
            description:
              description: Detailed description
              type: string
      responses:
        '200':
          description: Report submitted
        '400':
          description: Invalid request
        '401':
          description: Authentication required
      tags:
      - Message Actions
    parameters: []
  /chatbot/api/actions/track/:
    post:
      operationId: chatbot_api_actions_track_create
      summary: Track Message Action
      description: Track user actions on messages (copy, thumbs up/down, share, regenerate,
        branch, read aloud, report)
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          - action_type
          type: object
          properties:
            message_id:
              description: Message ID
              type: integer
            action_type:
              type: string
              enum:
              - copy
              - thumbs_up
              - thumbs_down
              - share
              - regenerate
              - branch
              - read_aloud
              - report
            metadata:
              description: Additional metadata
              type: object
      responses:
        '200':
          description: Success
          schema:
            type: object
            properties:
              success:
                type: boolean
              action_id:
                type: integer
              message:
                type: string
        '400':
          description: Invalid request
        '401':
          description: Authentication required
      tags:
      - Message Actions
    parameters: []
  /chatbot/api/admin/dashboard-stats/:
    get:
      operationId: chatbot_api_admin_dashboard-stats_list
      summary: Admin Dashboard Stats
      description: Get comprehensive dashboard statistics including users, sessions,
        tokens, images, and videos.
      parameters: []
      responses:
        '200':
          description: Dashboard statistics
          schema:
            type: object
            properties:
              users:
                type: object
              sessions:
                type: object
              messages:
                type: object
              tokens:
                type: object
              images:
                type: object
              videos:
                type: object
        '403':
          description: Admin access required
      tags:
      - Admin Dashboard
    parameters: []
  /chatbot/api/admin/feature-flags/:
    get:
      operationId: chatbot_api_admin_feature-flags_list
      summary: Get Feature Flags
      description: Get all feature flags for the platform.
      parameters: []
      responses:
        '200':
          description: Feature flags list
          schema:
            type: object
            properties:
              success:
                type: boolean
              flags:
                type: array
                items:
                  type: object
              count:
                type: integer
        '403':
          description: Admin access required
      tags:
      - Admin Dashboard
    parameters: []
  /chatbot/api/admin/gallery-data/:
    get:
      operationId: chatbot_api_admin_gallery-data_list
      summary: Get Gallery Data
      description: Get paginated gallery data for images and videos with filtering
        and search.
      parameters:
      - name: type
        in: query
        type: string
        enum:
        - image
        - video
        - all
        default: all
      - name: status
        in: query
        description: Filter by status
        type: string
      - name: user_id
        in: query
        description: Filter by user
        type: integer
      - name: search
        in: query
        description: Search in prompts
        type: string
      - name: page
        in: query
        type: integer
        default: 1
      - name: per_page
        in: query
        type: integer
        default: 24
      - name: sort
        in: query
        type: string
        default: -created_at
      responses:
        '200':
          description: Gallery data
        '403':
          description: Admin access required
      tags:
      - Admin Dashboard
    parameters: []
  /chatbot/api/admin/toggle-feature/{flag_id}/:
    post:
      operationId: chatbot_api_admin_toggle-feature_create
      summary: Toggle Feature Flag
      description: Toggle a feature flag on/off.
      parameters: []
      responses:
        '200':
          description: Feature flag toggled
        '403':
          description: Admin access required
        '404':
          description: Feature flag not found
      tags:
      - Admin Dashboard
    parameters:
    - name: flag_id
      in: path
      required: true
      type: string
  /chatbot/api/ai-providers/:
    get:
      operationId: chatbot_api_ai-providers_list
      summary: Get Available AI Providers
      description: |2

        Returns list of available AI providers for image and video generation.
        Providers are checked for API key availability and returned with their capabilities.
      parameters: []
      responses:
        '200':
          description: Provider list
          schema:
            type: object
            properties:
              image_providers:
                type: array
                items:
                  type: object
              video_providers:
                type: array
                items:
                  type: object
      tags:
      - AI Generation
    parameters: []
  /chatbot/api/ai-providers/admin/:
    get:
      operationId: chatbot_api_ai-providers_admin_list
      description: |2

        [ADMIN ONLY] Returns full AI provider details including actual names and pricing.
        This endpoint is restricted to admin/staff users only.
      parameters: []
      responses:
        '200':
          description: Full provider details with pricing
        '403':
          description: Admin access required
      tags:
      - Admin
    parameters: []
  /chatbot/api/analytics/costs/:
    get:
      operationId: chatbot_api_analytics_costs_list
      summary: Get cost analytics
      description: Get AI usage cost analytics with daily breakdown and model costs
      parameters:
      - name: days
        in: query
        description: Number of days to look back
        type: integer
        default: 30
      responses:
        '200':
          description: Cost analytics
      tags:
      - AI Analytics
    parameters: []
  /chatbot/api/analytics/dashboard/:
    get:
      operationId: chatbot_api_analytics_dashboard_list
      summary: Get analytics dashboard
      description: Get comprehensive dashboard statistics including sessions, messages,
        tokens, and costs
      parameters:
      - name: days
        in: query
        description: Number of days to look back (default 30)
        type: integer
      responses:
        '200':
          description: Dashboard statistics
          schema:
            type: object
            properties:
              overview:
                type: object
              recent:
                type: object
              trends:
                type: object
      tags:
      - AI Analytics
    parameters: []
  /chatbot/api/analytics/errors/:
    get:
      operationId: chatbot_api_analytics_errors_list
      summary: Get error analytics
      description: Get AI error tracking and analysis with trends and error types
      parameters:
      - name: days
        in: query
        description: Number of days to look back
        type: integer
        default: 7
      responses:
        '200':
          description: Error analytics
      tags:
      - AI Analytics
    parameters: []
  /chatbot/api/analytics/tokens/:
    get:
      operationId: chatbot_api_analytics_tokens_list
      summary: Get token usage analytics
      description: Get detailed token usage analytics with hourly breakdown and model
        efficiency
      parameters:
      - name: days
        in: query
        description: Number of days to look back
        type: integer
        default: 7
      responses:
        '200':
          description: Token usage analytics
      tags:
      - AI Analytics
    parameters: []
  /chatbot/api/analytics/users/:
    get:
      operationId: chatbot_api_analytics_users_list
      summary: Get user activity analytics
      description: Get user activity and engagement analytics
      parameters:
      - name: days
        in: query
        description: Number of days to look back
        type: integer
        default: 30
      responses:
        '200':
          description: User activity analytics
      tags:
      - AI Analytics
    parameters: []
  /chatbot/api/bookmark-message/:
    post:
      operationId: chatbot_api_bookmark-message_create
      summary: Bookmark Message
      description: Toggle bookmark status for a message.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          type: object
          properties:
            message_id:
              description: Message ID to bookmark
              type: integer
      responses:
        '200':
          description: Bookmark toggled
          schema:
            type: object
            properties:
              success:
                type: boolean
              is_bookmarked:
                type: boolean
        '404':
          description: Message not found
      tags:
      - Message Actions
    parameters: []
  /chatbot/api/consent/:
    get:
      operationId: chatbot_api_consent_list
      summary: Get User Consents
      description: Get all consent settings for the current user.
      parameters: []
      responses:
        '200':
          description: User consents
          schema:
            type: object
            properties:
              success:
                type: boolean
              consents:
                type: array
                items:
                  type: object
        '401':
          description: Authentication required
      tags:
      - User Consent
    parameters: []
  /chatbot/api/consent/update/:
    post:
      operationId: chatbot_api_consent_update_create
      summary: Update User Consent
      description: Update user consent for a specific type (data_collection, message_storage,
        analytics, ai_training, third_party_sharing).
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - consent_type
          - granted
          type: object
          properties:
            consent_type:
              type: string
              enum:
              - data_collection
              - message_storage
              - analytics
              - ai_training
              - third_party_sharing
            granted:
              description: Grant or revoke consent
              type: boolean
            consent_text:
              type: string
            version:
              type: string
              default: '1.0'
      responses:
        '200':
          description: Consent updated
        '400':
          description: Invalid consent type
      tags:
      - User Consent
    parameters: []
  /chatbot/api/edit/:
    post:
      operationId: chatbot_api_edit_create
      summary: Edit message and regenerate
      description: Edit a previous user message and regenerate the AI response (ChatGPT-style
        editing)
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          - new_message
          type: object
          properties:
            message_id:
              description: ID of the message to edit
              type: integer
            new_message:
              description: New message content
              type: string
            session_id:
              description: Chat session ID
              type: string
      responses:
        '200':
          description: Streaming NDJSON response with new AI output
        '401':
          description: Authentication required
        '404':
          description: Message not found
      tags:
      - AI Chat Communication
    parameters: []
  /chatbot/api/enhancement-result/{enhancement_id}/:
    get:
      operationId: chatbot_api_enhancement-result_read
      summary: Enhancement Result
      description: Get final enhancement result by enhancement_id
      parameters: []
      responses:
        '200':
          description: Result or in-progress
      tags:
      - Text Enhancement
    parameters:
    - name: enhancement_id
      in: path
      required: true
      type: string
  /chatbot/api/export/{session_id}/:
    get:
      operationId: chatbot_api_export_read
      summary: Export Conversation
      description: Export conversation in various formats (PDF, MD, JSON, HTML).
      parameters:
      - name: format
        in: query
        description: Export format
        type: string
        enum:
        - pdf
        - md
        - json
        - html
        default: md
      responses:
        '200':
          description: File download
        '400':
          description: Invalid format
        '404':
          description: Session not found
      tags:
      - Conversation Export
    parameters:
    - name: session_id
      in: path
      required: true
      type: string
  /chatbot/api/generate-video/:
    post:
      operationId: chatbot_api_generate-video_create
      summary: Generate AI Video
      description: |2

        Generate AI video from text prompt with optional iPhone-style camera effects.

        **Streaming Response:**
        This endpoint uses Server-Sent Events (SSE) to stream progress updates.
        The response will include:
        1. First event: `video_id` - Use this to connect to the progress stream
        2. Progress events: Real-time generation progress updates
        3. Final event: `complete` with video URL or `error` with message

        **Features:**
        - Realistic video generation using OpenAI DALL-E 3 for keyframes
        - iPhone-style camera effects (handheld shake, focus breathing, lens flare, etc.)
        - Multiple realism levels: standard, iphone, high, ultra
        - Reference image support for style consistency

        **iPhone Effects Configuration:**
        When `realism_level` is set to 'iphone', you can customize individual effects via `iphone_effects` JSON object:
        - `cameraShake`: Realistic handheld camera shake
        - `focusBreathing`: Autofocus breathing effect
        - `lensFlare`: Natural lens flare on bright areas
        - `exposureShift`: Dynamic exposure variation
        - `motionBlur`: Motion blur on movement
        - `filmGrain`: Authentic film grain/noise
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - prompt
          type: object
          properties:
            prompt:
              description: Video description prompt
              type: string
            duration:
              description: Duration in seconds (1-10)
              type: integer
              default: 4
            resolution:
              description: Video resolution
              type: string
              enum:
              - 640x480
              - 1280x720
              - 1920x1080
              default: 1280x720
            fps:
              description: Frames per second
              type: integer
              default: 24
            realism_level:
              description: Realism level
              type: string
              enum:
              - standard
              - iphone
              - high
              - ultra
              default: iphone
            natural_motion_enabled:
              description: Enable natural motion
              type: boolean
              default: true
            iphone_effects:
              description: iPhone effect toggles
              type: object
              properties:
                cameraShake:
                  type: boolean
                  default: true
                focusBreathing:
                  type: boolean
                  default: true
                lensFlare:
                  type: boolean
                  default: true
                exposureShift:
                  type: boolean
                  default: true
                motionBlur:
                  type: boolean
                  default: true
                filmGrain:
                  type: boolean
                  default: true
            reference_image_url:
              description: Optional reference image URL
              type: string
            session_id:
              description: Optional chat session ID
              type: string
            stream:
              description: 'Enable streaming response (default: true)'
              type: boolean
              default: true
      responses:
        '200':
          description: Video generation started
          schema:
            type: object
            properties:
              success:
                type: boolean
              id:
                description: Video generation ID
                type: integer
              video_url:
                type: string
              thumbnail_url:
                type: string
              video_data:
                type: object
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication required
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
        '503':
          description: Billing/service error
      tags:
      - AI Video Generation
    parameters: []
  /chatbot/api/init-image/:
    post:
      operationId: chatbot_api_init-image_create
      summary: Initialize Async Image Generation
      description: Initialize async image generation and return ID immediately for
        SSE tracking
      parameters: []
      responses:
        '200':
          description: Image generation initialized
          schema:
            type: object
            properties:
              success:
                type: boolean
              id:
                type: integer
              stream_url:
                type: string
              poll_url:
                type: string
      tags:
      - AI Image Generation
    parameters: []
  /chatbot/api/models/:
    get:
      operationId: chatbot_api_models_list
      summary: Get available EyeNak AI models
      description: Get list of all available EyeNak AI models with branded names (EyeNak
        Pro, EyeNak Swift, etc.)
      parameters: []
      responses:
        '200':
          description: List of available EyeNak AI models
          schema:
            type: object
            properties:
              success:
                type: boolean
              models:
                type: array
                items:
                  type: object
              default_model:
                type: string
      tags:
      - AI Model Preferences
    parameters: []
  /chatbot/api/models/admin/:
    get:
      operationId: chatbot_api_models_admin_list
      summary: Get all AI models (Admin)
      description: Admin-only endpoint to get all AI models with actual names (GPT-4o,
        Claude, etc.), costs, and full configuration details
      parameters: []
      responses:
        '200':
          description: List of all AI models with full details
          schema:
            type: object
            properties:
              success:
                type: boolean
              models:
                type: array
                items:
                  type: object
              default_model:
                type: string
              total_models:
                type: integer
        '401':
          description: Authentication required
        '403':
          description: Admin access required
      tags:
      - Admin - AI Models
    parameters: []
  /chatbot/api/preferences/:
    get:
      operationId: chatbot_api_preferences_list
      summary: Get model preferences
      description: Get current user's AI model preferences
      parameters:
      - name: session_id
        in: query
        description: Chat session ID
        required: true
        type: string
      responses:
        '200':
          description: User preferences
        '400':
          description: session_id is required
      tags:
      - AI Model Preferences
    post:
      operationId: chatbot_api_preferences_create
      description: Update user preferences
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - chatbot
    parameters: []
  /chatbot/api/project-insights/:
    post:
      operationId: chatbot_api_project-insights_create
      summary: Query project insights
      description: Send a natural language query to get insights from the project
        management database
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message
          type: object
          properties:
            message:
              description: User's question/query
              type: string
            session_id:
              description: Optional chat session ID
              type: string
            query_type:
              description: Type of query
              type: string
              enum:
              - boards
              - tasks
              - users
              - companies
              - custom
              - statistics
      responses:
        '200':
          description: Query result
          schema:
            type: object
            properties:
              response:
                type: string
              status:
                type: string
              data:
                type: object
        '401':
          description: Authentication required
      tags:
      - Project Insights
    parameters: []
  /chatbot/api/project-insights/health/:
    get:
      operationId: chatbot_api_project-insights_health_list
      summary: Project insights health check
      description: Check the health status and database connectivity of the project
        insights agent
      parameters: []
      responses:
        '200':
          description: Health status
          schema:
            type: object
            properties:
              status:
                type: string
              agent:
                type: string
              database:
                type: string
              tables_available:
                type: integer
        '500':
          description: Service unhealthy
      tags:
      - Project Insights
    parameters: []
  /chatbot/api/quick-enhance/:
    post:
      operationId: chatbot_api_quick-enhance_create
      summary: Quick Text Enhancement
      description: |2

        Quick inline text enhancement - provides single best suggestion.
        Supports both streaming (NDJSON) and non-streaming (JSON) modes.

        **Streaming mode** (stream=true) returns NDJSON events: start, delta, end, error
        **Non-streaming mode** returns JSON: {success, original, enhanced, language}
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - text
          type: object
          properties:
            text:
              description: Text to enhance
              type: string
            language:
              type: string
              enum:
              - en
              - ar
              default: en
            context:
              type: string
              enum:
              - chat
              - email
              - search
              - question
              - general
              default: general
            stream:
              description: Enable streaming mode
              type: boolean
              default: false
      responses:
        '200':
          description: Enhanced text
        '400':
          description: No text provided
        '429':
          description: Enhancement limit exceeded
      tags:
      - Text Enhancement
    parameters: []
  /chatbot/api/quota-info/:
    get:
      operationId: chatbot_api_quota-info_list
      summary: Get User Quota Info
      description: Get current user's quota information including message limits,
        image/video generation quotas, API limits, and cost tracking. All limits are
        dynamically based on user's purchased plan.
      parameters: []
      responses:
        '200':
          description: User quota information
          schema:
            type: object
            properties:
              messages:
                type: object
                properties:
                  limit:
                    type: integer
                  used:
                    type: integer
                  remaining:
                    type: integer
                  plan:
                    type: string
              images:
                type: object
                properties:
                  daily_limit:
                    type: integer
                  daily_used:
                    type: integer
                  daily_remaining:
                    type: integer
                  monthly_limit:
                    type: integer
                  monthly_used:
                    type: integer
                  monthly_remaining:
                    type: integer
              videos:
                type: object
              api:
                type: object
              cost:
                type: object
              plan_info:
                description: Current plan information
                type: object
        '401':
          description: Authentication required
        '500':
          description: Server error
      tags:
      - Quota Management
    parameters: []
  /chatbot/api/recent-activity/:
    get:
      operationId: chatbot_api_recent-activity_list
      summary: Get recent activity
      description: Get recent user activity including chat sessions
      parameters: []
      responses:
        '200':
          description: Recent activities
          schema:
            type: object
            properties:
              activities:
                type: array
                items:
                  type: object
        '401':
          description: Authentication required
      tags:
      - AI Analytics
    parameters: []
  /chatbot/api/recent-image/:
    get:
      operationId: chatbot_api_recent-image_list
      summary: Get Recent Image
      description: Get most recent image generation for recovery after connection
        loss
      parameters: []
      responses:
        '200':
          description: Recent image info
        '404':
          description: No recent image found
      tags:
      - AI Image Generation
    parameters: []
  /chatbot/api/recent-video/:
    get:
      operationId: chatbot_api_recent-video_list
      summary: Get Recent Video
      description: Get most recent video generation for recovery after connection
        loss
      parameters: []
      responses:
        '200':
          description: Recent video info
        '404':
          description: No recent video found
      tags:
      - AI Video Generation
    parameters: []
  /chatbot/api/restricted-content-status/:
    get:
      operationId: chatbot_api_restricted-content-status_list
      summary: Get Restricted Content Status
      description: Check if restricted content generation is enabled by admin. Returns
        the current state of restricted content settings.
      parameters: []
      responses:
        '200':
          description: Restricted content settings
          schema:
            type: object
            properties:
              success:
                type: boolean
              restricted_content_enabled:
                description: Whether restricted content is allowed
                type: boolean
              show_warning:
                description: Whether to show warning to users
                type: boolean
              warning_message:
                description: Warning message to display
                type: string
      tags:
      - AI Content Generation
    parameters: []
  /chatbot/api/retry/:
    post:
      operationId: chatbot_api_retry_create
      summary: Retry failed AI message
      description: Retry a failed message or regenerate an AI response with streaming
        output
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          type: object
          properties:
            message_id:
              description: ID of the message to retry
              type: integer
            session_id:
              description: Chat session ID
              type: string
      responses:
        '200':
          description: Streaming NDJSON response with retried AI output
        '401':
          description: Authentication required
        '404':
          description: Message not found
      tags:
      - AI Chat Communication
    parameters: []
  /chatbot/api/sessions/:
    get:
      operationId: chatbot_api_sessions_list
      summary: List chat sessions
      description: Get all chat sessions for the authenticated user with pagination
        support
      parameters:
      - name: offset
        in: query
        description: Pagination offset
        type: integer
        default: 0
      - name: limit
        in: query
        description: Items per page (max 50)
        type: integer
        default: 20
      responses:
        '200':
          description: List of chat sessions
          schema:
            type: object
            properties:
              sessions:
                type: array
                items:
                  type: object
              total:
                type: integer
              has_more:
                type: boolean
        '401':
          description: Authentication required
      tags:
      - Chat Session Management
    parameters: []
  /chatbot/api/sessions/{session_id}/:
    get:
      operationId: chatbot_api_sessions_read
      summary: Get session details
      description: Get all messages and metadata for a specific chat session
      parameters: []
      responses:
        '200':
          description: Session details with messages
          schema:
            type: object
            properties:
              session_id:
                type: string
              title:
                type: string
              messages:
                type: array
                items:
                  type: object
        '401':
          description: Authentication required
        '403':
          description: Permission denied
        '404':
          description: Session not found
      tags:
      - Chat Session Management
    parameters:
    - name: session_id
      in: path
      required: true
      type: string
  /chatbot/api/sessions/{session_id}/delete/:
    post:
      operationId: chatbot_api_sessions_delete_create
      summary: Delete chat session
      description: Delete a specific chat session and all its messages
      parameters: []
      responses:
        '200':
          description: Session deleted successfully
        '401':
          description: Authentication required
        '403':
          description: Permission denied
        '404':
          description: Session not found
      tags:
      - Chat Session Management
    delete:
      operationId: chatbot_api_sessions_delete_delete
      description: Delete a chat session
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - chatbot
    parameters:
    - name: session_id
      in: path
      required: true
      type: string
  /chatbot/api/sessions/{session_id}/update-title/:
    post:
      operationId: chatbot_api_sessions_update-title_create
      summary: Update session title
      description: Update the title of a chat session
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - title
          type: object
          properties:
            title:
              description: New session title
              type: string
      responses:
        '200':
          description: Title updated successfully
        '401':
          description: Authentication required
        '404':
          description: Session not found
      tags:
      - Chat Session Management
    parameters:
    - name: session_id
      in: path
      required: true
      type: string
  /chatbot/api/share/create/:
    post:
      operationId: chatbot_api_share_create_create
      summary: Create Share Link
      description: Create a shareable link for a message (like ChatGPT/DeepSeek).
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message_id
          type: object
          properties:
            message_id:
              description: Message ID to share
              type: integer
            include_context:
              description: Include context messages
              type: boolean
              default: true
            context_messages_count:
              description: Number of context messages
              type: integer
              default: 5
            expires_days:
              description: Days until expiration (null for no expiration)
              type: integer
      responses:
        '200':
          description: Share link created
          schema:
            type: object
            properties:
              success:
                type: boolean
              share_id:
                type: string
              share_url:
                type: string
        '404':
          description: Message not found
      tags:
      - Message Sharing
    parameters: []
  /chatbot/api/start-enhancement/:
    post:
      operationId: chatbot_api_start-enhancement_create
      summary: Start Enhancement (progress mode)
      description: Start an enhancement job with server-side progress tracking (SSE/poll).
        Returns enhancement_id.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - text
          type: object
          properties:
            text:
              type: string
            language:
              type: string
              enum:
              - en
              - ar
              default: en
            context:
              type: string
              enum:
              - chat
              - email
              - search
              - general
              - quick
              - professional
              - creative
              default: general
      responses:
        '200':
          description: Enhancement started
          schema:
            type: object
            properties:
              success:
                type: boolean
              enhancement_id:
                type: integer
              stream_url:
                type: string
              poll_url:
                type: string
        '400':
          description: No text provided
        '401':
          description: Authentication required
      tags:
      - Text Enhancement
    parameters: []
  /chatbot/api/stream/:
    post:
      operationId: chatbot_api_stream_create
      summary: Stream AI chat response
      description: Send a message and receive a streaming AI response in NDJSON format
        with incremental tokens (ChatGPT-style)
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - message
          type: object
          properties:
            message:
              description: User message to send
              type: string
            session_id:
              description: Chat session ID (optional)
              type: string
            lang:
              description: Language (en or ar)
              type: string
              enum:
              - en
              - ar
            deep_think:
              description: Enable deep thinking mode
              type: boolean
      responses:
        '200':
          description: Streaming NDJSON response
          schema:
            type: object
            properties:
              event:
                description: 'Event type: start, delta, end, error'
                type: string
              text:
                description: Incremental text token
                type: string
              response:
                description: Full response (on end event)
                type: string
              session_id:
                description: Chat session ID
                type: string
        '401':
          description: Authentication required
        '400':
          description: Bad request - Empty message or validation error
      tags:
      - AI Chat Communication
    parameters: []
  /chatbot/api/templates/:
    get:
      operationId: chatbot_api_templates_list
      summary: Get chat templates
      description: Get predefined chat prompt templates organized by category
      parameters:
      - name: lang
        in: query
        description: Language (en or ar)
        type: string
      - name: category
        in: query
        description: Category ID to filter by
        type: string
      - name: template
        in: query
        description: Specific template ID
        type: string
      - name: agent
        in: query
        description: Agent name to filter by
        type: string
      responses:
        '200':
          description: Chat templates
        '404':
          description: Template not found
      tags:
      - AI Chat Communication
    parameters: []
  /chatbot/api/user-stats/:
    get:
      operationId: chatbot_api_user-stats_list
      summary: Get user statistics
      description: Get comprehensive AI usage statistics for the authenticated user
      parameters: []
      responses:
        '200':
          description: User statistics
          schema:
            type: object
            properties:
              total_sessions:
                type: integer
              total_messages:
                type: integer
              month_sessions:
                type: integer
              month_messages:
                type: integer
        '401':
          description: Authentication required
      tags:
      - AI Analytics
    parameters: []
  /chatbot/api/video-status/{video_id}/:
    get:
      operationId: chatbot_api_video-status_read
      summary: Get Video Status
      description: Get video generation status and details. Use this to recover from
        network errors during video generation.
      parameters: []
      responses:
        '200':
          description: Video status
          schema:
            type: object
            properties:
              id:
                type: integer
              status:
                type: string
                enum:
                - pending
                - processing
                - completed
                - failed
              video_url:
                type: string
              thumbnail_url:
                type: string
              generation_time:
                type: number
              estimated_cost:
                type: number
              error_message:
                type: string
        '404':
          description: Video not found
        '401':
          description: Authentication required
      tags:
      - AI Video Generation
    parameters:
    - name: video_id
      in: path
      required: true
      type: string
  /chatbot/api/voice/speak/:
    post:
      operationId: chatbot_api_voice_speak_create
      summary: Text-to-Speech
      description: Generate speech from text (uses browser Web Speech Synthesis API
        on frontend, this is backup).
      parameters:
      - name: data
        in: body
        required: true
        schema:
          type: object
          properties:
            text:
              description: Text to convert to speech
              type: string
            message_id:
              description: Message ID for tracking
              type: integer
      responses:
        '200':
          description: TTS handled by browser
      tags:
      - Voice Features
    parameters: []
  /chatbot/api/voice/track/:
    post:
      operationId: chatbot_api_voice_track_create
      summary: Track Voice Command
      description: Track Voice Commands feature usage when user successfully uses
        voice input.
      parameters: []
      responses:
        '200':
          description: Voice command tracked
        '429':
          description: Voice commands limit exceeded
      tags:
      - Voice Features
    parameters: []
  /chatbot/api/voice/transcribe/:
    post:
      operationId: chatbot_api_voice_transcribe_create
      summary: Transcribe Voice to Text
      description: Transcribe voice audio using OpenAI Whisper API. Supports audio
        files from MediaRecorder API.
      parameters:
      - name: audio
        in: formData
        description: Audio file (webm, mp3, wav)
        required: true
        type: file
      - name: language
        in: formData
        description: Language code (en, ar, auto)
        type: string
        default: en
      responses:
        '200':
          description: Transcription successful
          schema:
            type: object
            properties:
              success:
                type: boolean
              text:
                description: Transcribed text
                type: string
              language:
                type: string
        '400':
          description: No audio file provided
        '429':
          description: Voice mode limit exceeded
      consumes:
      - multipart/form-data
      - application/x-www-form-urlencoded
      tags:
      - Voice Features
    parameters: []
  /chatbot/api/welcome/:
    get:
      operationId: chatbot_api_welcome_list
      summary: Get welcome message
      description: Get a personalized AI welcome message based on user's chat history
      parameters:
      - name: lang
        in: query
        description: Language (en or ar)
        type: string
        enum:
        - en
        - ar
      responses:
        '200':
          description: Welcome message
          schema:
            type: object
            properties:
              message:
                type: string
              personalized:
                type: boolean
      tags:
      - AI Chat Communication
    parameters: []
definitions: {}
