superdocs-app Users API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Users API'
  description: 'Typebar (formerly SuperDocs): AI-powered document editing with multi-tenant organization support'
  version: 2.0.0
servers:
- url: https://api.superdocs.app
tags:
- name: Users
paths:
  /v1/users/me:
    get:
      tags:
      - Users
      summary: Get Current User Profile
      description: 'Get current user''s profile information


        Returns user profile with subscription tier and usage limits'
      operationId: get_current_user_profile_v1_users_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
      security:
      - HTTPBearer: []
    patch:
      tags:
      - Users
      summary: Update User Profile
      description: 'Update current user''s profile


        Allows updating display name, timezone, language, and preferences'
      operationId: update_user_profile_v1_users_me_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v1/users/me/usage:
    get:
      tags:
      - Users
      summary: Get User Usage Stats
      description: 'Get detailed usage statistics for current user


        Returns operation counts, token usage, and success rates by operation type'
      operationId: get_user_usage_stats_v1_users_me_usage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStatsResponse'
      security:
      - HTTPBearer: []
  /v1/users/me/sessions:
    get:
      tags:
      - Users
      summary: Get User Sessions
      description: 'List all chat sessions for current user


        Returns list of sessions with last activity and message counts'
      operationId: get_user_sessions_v1_users_me_sessions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UserSessionResponse'
                type: array
                title: Response Get User Sessions V1 Users Me Sessions Get
      security:
      - HTTPBearer: []
  /v1/users/me/sessions/{session_id}:
    delete:
      tags:
      - Users
      summary: Delete User Session
      description: 'Delete a specific chat session


        Removes all messages for the given session ID (user must own the session)'
      operationId: delete_user_session_v1_users_me_sessions__session_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/users/me/limits:
    get:
      tags:
      - Users
      summary: Check User Limits
      description: 'Check current usage limits and remaining operations


        Returns real-time usage information with reset date'
      operationId: check_user_limits_v1_users_me_limits_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /v1/users/me/api-keys:
    get:
      tags:
      - Users
      summary: List Api Keys
      description: 'List all API keys for the current user (masked).


        Returns key prefix and last 4 characters for identification.'
      operationId: list_api_keys_v1_users_me_api_keys_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ApiKeyListItem'
                type: array
                title: Response List Api Keys V1 Users Me Api Keys Get
      security:
      - HTTPBearer: []
    post:
      tags:
      - Users
      summary: Create Api Key
      description: 'Create a new API key for the current user.


        The raw key is returned ONCE in the response. It cannot be retrieved again.'
      operationId: create_api_key_v1_users_me_api_keys_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v1/users/me/api-keys/{key_id}:
    delete:
      tags:
      - Users
      summary: Revoke Api Key
      description: 'Revoke (soft delete) an API key.


        The key will be marked as inactive and can no longer be used for authentication.'
      operationId: revoke_api_key_v1_users_me_api_keys__key_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateApiKeyResponse:
      properties:
        id:
          type: string
          title: Id
          description: Key identifier (UUID). Use this to revoke the key later.
        name:
          type: string
          title: Name
          description: Label you assigned to this key.
        key:
          type: string
          title: Key
          description: The full API key (sk_... format). Copy this now — it cannot be retrieved again.
        key_prefix:
          type: string
          title: Key Prefix
          description: First 7 characters of the key (e.g., 'sk_a1b2') for identification.
        created_at:
          type: string
          title: Created At
          description: ISO 8601 timestamp when the key was created.
      type: object
      required:
      - id
      - name
      - key
      - key_prefix
      - created_at
      title: CreateApiKeyResponse
      description: Newly created API key. The raw key is shown only once — save it immediately.
    CreateApiKeyRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: A label for this key (e.g., 'My App', 'CI Pipeline').
      type: object
      required:
      - name
      title: CreateApiKeyRequest
      description: Create a new API key.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UserSessionResponse:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Unique session identifier.
        last_message_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Message At
          description: ISO 8601 timestamp of the most recent message.
        message_count:
          type: integer
          title: Message Count
          description: Total number of messages in this session.
      type: object
      required:
      - session_id
      - message_count
      title: UserSessionResponse
      description: Summary of a user's chat session.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UsageStatsResponse:
      properties:
        user_id:
          type: string
          title: User Id
          description: User identifier.
        subscription_tier:
          type: string
          title: Subscription Tier
          description: 'Current plan: ''free'', ''plus'', ''pro'', or ''enterprise''.'
        monthly_limit:
          type: integer
          title: Monthly Limit
          description: Maximum operations allowed per month. -1 means unlimited.
        monthly_used:
          type: integer
          title: Monthly Used
          description: Operations used this billing cycle.
        monthly_remaining:
          type: integer
          title: Monthly Remaining
          description: Operations remaining this cycle.
        monthly_reset_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Monthly Reset At
          description: ISO 8601 timestamp when the monthly counter resets.
        total_sessions:
          type: integer
          title: Total Sessions
          description: Total number of chat sessions created.
        total_documents:
          type: integer
          title: Total Documents
          description: Total number of documents processed.
        total_operations:
          type: integer
          title: Total Operations
          description: Lifetime total operations across all billing cycles.
        current_month_stats:
          additionalProperties: true
          type: object
          title: Current Month Stats
          description: Breakdown of this month's operations by type, including counts, tokens used, and success rates.
      type: object
      required:
      - user_id
      - subscription_tier
      - monthly_limit
      - monthly_used
      - monthly_remaining
      - total_sessions
      - total_documents
      - total_operations
      - current_month_stats
      title: UsageStatsResponse
      description: Detailed usage statistics for the current billing cycle.
    UpdateProfileRequest:
      properties:
        display_name:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Display Name
          description: New display name.
        timezone:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Timezone
          description: IANA timezone (e.g., 'America/New_York').
        language:
          anyOf:
          - type: string
            maxLength: 10
          - type: 'null'
          title: Language
          description: Preferred language code (e.g., 'en', 'es').
        preferences:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Preferences
          description: 'User preferences to update (e.g., {approval_mode: ''ask_every_time'', model_tier: ''pro''}).'
      type: object
      title: UpdateProfileRequest
      description: Update user profile fields.
    UserProfileResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique user identifier (UUID).
        email:
          type: string
          title: Email
          description: User's email address.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: User's display name.
        photo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Photo Url
          description: URL to user's profile photo.
        email_verified:
          type: boolean
          title: Email Verified
          description: Whether the user's email has been verified.
        auth_provider:
          type: string
          title: Auth Provider
          description: 'Authentication method: ''email'' or ''google''.'
        subscription_tier:
          type: string
          title: Subscription Tier
          description: 'Current plan: ''free'', ''plus'', ''pro'', or ''enterprise''.'
        subscription_status:
          type: string
          title: Subscription Status
          description: 'Subscription status: ''active'', ''canceled'', or ''past_due''.'
        monthly_operation_limit:
          type: integer
          title: Monthly Operation Limit
          description: Maximum operations allowed per month. -1 means unlimited.
        monthly_operations_used:
          type: integer
          title: Monthly Operations Used
          description: Operations used this billing cycle.
        monthly_remaining:
          type: integer
          title: Monthly Remaining
          description: Operations remaining this cycle.
        preferences:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Preferences
          description: User preferences (e.g., approval_mode, model_tier).
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: ISO 8601 timestamp when the account was created.
        last_login_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Login At
          description: ISO 8601 timestamp of the last login.
      type: object
      required:
      - id
      - email
      - email_verified
      - auth_provider
      - subscription_tier
      - subscription_status
      - monthly_operation_limit
      - monthly_operations_used
      - monthly_remaining
      title: UserProfileResponse
      description: User profile with subscription and usage information.
    ApiKeyListItem:
      properties:
        id:
          type: string
          title: Id
          description: Key identifier (UUID).
        name:
          type: string
          title: Name
          description: Label assigned to this key.
        key_prefix:
          type: string
          title: Key Prefix
          description: First 7 characters of the key (e.g., 'sk_a1b2').
        last_four:
          type: string
          title: Last Four
          description: Last 4 characters of the key for identification.
        is_active:
          type: boolean
          title: Is Active
          description: Whether the key is active. Revoked keys show as false.
        created_at:
          type: string
          title: Created At
          description: ISO 8601 timestamp when the key was created.
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Used At
          description: ISO 8601 timestamp of last use, or null if never used.
      type: object
      required:
      - id
      - name
      - key_prefix
      - last_four
      - is_active
      - created_at
      title: ApiKeyListItem
      description: API key summary (masked for security).
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer