openapi: 3.0.3
info:
  title: Barcodes.dev API
  description: |
    Comprehensive barcode and QR code generation API with two distinct versions:

    ## API Versions

    ### API v1 - Public Access
    - **Base Path**: `/api/v1/`
    - **Authentication**: Optional (anonymous usage allowed)
    - **Rate Limiting**: Applied to all requests
    - **Features**: Basic barcode and QR code generation

    ### API v2 - Authenticated Access
    - **Base Path**: `/api/v2/`
    - **Authentication**: Required (API key)
    - **Rate Limiting**: Tier-based limits
    - **Features**: All v1 features plus batch generation, account management

    ## Getting Started

    1. **For v1 (Anonymous)**: Start making requests immediately
    2. **For v2 (Authenticated)**: Register at `/register` to get your API key

    ## Authentication

    v2 endpoints require an API key in the `X-API-Key` header:
    ```
    X-API-Key: bcd_your_api_key_here
    ```

  version: 2.0.0
  contact:
    name: API Support
    url: https://barcodes.dev/api-docs
    email: api@barcodes.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://barcodes.dev
    description: Production server
  - url: http://localhost:5001
    description: Local development server

tags:
  - name: v1-barcode
    description: API v1 - Linear barcode generation (public)
  - name: v1-qr
    description: API v1 - QR code generation (public)
  - name: v1-utility
    description: API v1 - Utility endpoints (public)
  - name: v2-barcode
    description: API v2 - Linear barcode generation (authenticated)
  - name: v2-qr
    description: API v2 - QR code generation (authenticated)
  - name: v2-batch
    description: API v2 - Batch generation (authenticated)
  - name: v2-postal
    description: API v2 - Postal code generation (authenticated)
  - name: v2-account
    description: API v2 - Account management (authenticated)
  - name: v2-utility
    description: API v2 - Utility endpoints (authenticated)
  - name: authentication
    description: User registration and authentication

security:
  - ApiKeyAuth: []
  - {} # Allow no authentication for v1 endpoints

paths:
  # API v1 Endpoints (Public)
  /api/v1/barcode:
    post:
      tags:
        - v1-barcode
      summary: Generate Linear Barcode (v1)
      description: |
        Generate traditional 1D barcodes. No authentication required, but rate limited.

        **Rate Limits**: 100 requests/hour for anonymous users, tier-based for API key users.
      security:
        - {}
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinearBarcodeRequest'
            examples:
              basic:
                summary: Basic Code128
                value:
                  text: "EXAMPLE-123"
                  barcode_type: "code128"
                  image_format: "PNG"
      responses:
        '200':
          description: Barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BarcodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v1/qrcode:
    post:
      tags:
        - v1-qr
      summary: Generate QR Code (v1)
      description: Generate QR codes with customization options. No authentication required.
      security:
        - {}
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QRCodeRequest'
            examples:
              basic:
                summary: Basic QR Code
                value:
                  text: "https://example.com"
                  error_correction: "M"
      responses:
        '200':
          description: QR code generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QRCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v1/usage:
    get:
      tags:
        - v1-utility
      summary: Get Usage Statistics (v1)
      description: Get current usage statistics. API key optional for anonymous usage.
      security:
        - {}
        - ApiKeyAuth: []
      responses:
        '200':
          description: Usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'

  /api/v1/version:
    get:
      tags:
        - v1-utility
      summary: Get API Version Info (v1)
      description: Get version and system information for API v1.
      security:
        - {}
      responses:
        '200':
          description: Version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'

  # API v2 Endpoints (Authenticated)
  /api/v2/barcode:
    post:
      tags:
        - v2-barcode
      summary: Generate Linear Barcode (v2)
      description: |
        Generate traditional 1D barcodes with enhanced features. Requires API key authentication.

        **Enhanced Features**:
        - User tier information in response
        - Better error handling
        - Priority processing
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinearBarcodeRequest'
            examples:
              authenticated:
                summary: Authenticated Barcode Generation
                value:
                  text: "AUTH-BARCODE-456"
                  barcode_type: "code128"
                  image_format: "PNG"
      responses:
        '200':
          description: Barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedBarcodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/qrcode:
    post:
      tags:
        - v2-qr
      summary: Generate QR Code (v2)
      description: Generate QR codes with enhanced features and user tier information.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QRCodeRequest'
            examples:
              enhanced:
                summary: Enhanced QR Code
                value:
                  text: "https://authenticated.example.com"
                  error_correction: "H"
                  box_size: 12
                  border: 6
      responses:
        '200':
          description: QR code generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedQRCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/batch:
    post:
      tags:
        - v2-batch
      summary: Batch Generate Codes (v2 Exclusive)
      description: |
        Generate multiple barcodes and QR codes in a single request. Maximum 10 items per batch.

        **v2 Exclusive Feature**: Only available with API key authentication.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            examples:
              mixed_batch:
                summary: Mixed Barcode and QR Code Batch
                value:
                  batch:
                    - type: "barcode"
                      text: "BATCH-001"
                      barcode_type: "code128"
                    - type: "qrcode"
                      text: "https://batch.example.com"
                      error_correction: "M"
                    - type: "barcode"
                      text: "BATCH-002"
                      barcode_type: "ean13"
      responses:
        '200':
          description: Batch processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/postal:
    post:
      tags:
        - v2-postal
      summary: Generate Postal Barcode (v2)
      description: |
        Generate postal service barcodes for various countries and services. Requires API key authentication.

        **Supported Postal Types**:
        - USPS: usps_imd, usps_postnet, usps_planet
        - Royal Mail: royal_mail, ukroyalmail
        - Australia Post: australia_post, auspost
        - Netherlands: netherlands_kix
        - Japan Post: japan_post, japanpost
        - Korea Post: korea_post
        - Deutsche Post: dpleit, dpident
        - Channel Code: channel
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostalRequest'
            examples:
              usps_imd:
                summary: USPS Intelligent Mail
                value:
                  text: "0123456709498765432101234567891"
                  postal_type: "usps_imd"
                  image_format: "PNG"
              royal_mail:
                summary: Royal Mail 4-State
                value:
                  text: "B31HQ1A"
                  postal_type: "royal_mail"
                  image_format: "PNG"
              australia_post:
                summary: Australia Post
                value:
                  text: "1139549554"
                  postal_type: "australia_post"
                  image_format: "PNG"
      responses:
        '200':
          description: Postal barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      tags:
        - v2-postal
      summary: Generate Postal Barcode via GET (v2)
      description: Generate postal barcodes using query parameters. Requires API key authentication.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: text
          in: query
          required: true
          schema:
            type: string
          description: Data to encode in postal barcode
          example: "0123456709498765432101234567891"
        - name: postal_type
          in: query
          required: true
          schema:
            type: string
            enum: [usps_imd, usps_postnet, usps_planet, royal_mail, ukroyalmail, australia_post, auspost, netherlands_kix, japan_post, japanpost, korea_post, dpleit, dpident, channel]
          description: Type of postal barcode
          example: "usps_imd"
        - name: image_format
          in: query
          schema:
            type: string
            enum: [PNG, JPEG, WEBP]
            default: PNG
          description: Output image format
        - name: output
          in: query
          schema:
            type: string
            enum: [base64, file]
            default: base64
          description: Response format
      responses:
        '200':
          description: Postal barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalResponse'
            application/octet-stream:
              description: Binary image file (when output=file)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/account:
    get:
      tags:
        - v2-account
      summary: Get Account Information (v2 Exclusive)
      description: |
        Get detailed account information including tier, usage limits, and current usage.

        **v2 Exclusive Feature**: Only available with API key authentication.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Account information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/usage:
    get:
      tags:
        - v2-utility
      summary: Get Enhanced Usage Statistics (v2)
      description: Get detailed usage statistics with account information.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Enhanced usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedUsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/version:
    get:
      tags:
        - v2-utility
      summary: Get API Version Info (v2)
      description: Get version and system information for API v2 with user context.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Enhanced version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedVersionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Authentication Endpoints
  /register:
    post:
      tags:
        - authentication
      summary: Register New Account
      description: Register a new user account and receive an API key.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - email
                - agree_terms
              properties:
                email:
                  type: string
                  format: email
                  description: User email address
                agree_terms:
                  type: boolean
                  description: Must agree to terms of service
      responses:
        '201':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key for v2 endpoints. Get your key by registering at `/register`.

        Format: `bcd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

  schemas:
    LinearBarcodeRequest:
      type: object
      required:
        - text
        - barcode_type
      properties:
        text:
          type: string
          description: Text to encode in the barcode
          example: "123456789012"
        barcode_type:
          type: string
          enum: [
            # Code 128 Family
            code128, gs1, gs1_128, ean14, nve18, sscc18, hibc_128, dpd,
            # EAN/UPC Family
            ean, ean2, ean5, ean8, ean13, upc, upca, upce, isbn, isbn10, isbn13, sbn, jan,
            # Code 39 Family
            code39, excode39, code32, hibc_39, vin, logmars,
            # Other Linear Codes
            code93, code11, codabar,
            # Code 2 of 5 Family
            c25standard, c25iata, c25ind, c25inter, itf, c25logic, itf14, dpleit, dpident,
            # Plessey Family
            plessey, msi, msi_plessey,
            # Telepen
            telepen, telepen_num,
            # Pharmaceutical
            pharma, pharmacode, pzn,
            # GS1 DataBar
            dbar_omn, dbar_ltd, dbar_exp, databar_omn, databar_ltd, databar_exp,
            gs1_databar_omn, gs1_databar_ltd, gs1_databar_exp,
            # Postal & Special
            koreapost, channel,
            # Legacy/Aliases
            gtin
          ]
          description: Type of barcode to generate
          example: "code128"
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
          description: Output image format
        output:
          type: string
          enum: [base64, file]
          default: base64
          description: Response format (base64 JSON or file download)

    QRCodeRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Text to encode in the QR code
          example: "https://example.com"
        error_correction:
          type: string
          enum: [L, M, Q, H]
          default: M
          description: Error correction level
        box_size:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: Size of each box in pixels
        border:
          type: integer
          minimum: 0
          maximum: 20
          default: 4
          description: Border size in boxes
        fill_color:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          default: "#000000"
          description: Foreground color (hex)
        back_color:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          default: "#ffffff"
          description: Background color (hex)
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
          description: Output image format
        output:
          type: string
          enum: [base64, file]
          default: base64
          description: Response format

    BatchRequest:
      type: object
      required:
        - batch
      properties:
        batch:
          type: array
          minItems: 1
          maxItems: 10
          description: Array of generation requests (max 10)
          items:
            oneOf:
              - $ref: '#/components/schemas/BatchBarcodeItem'
              - $ref: '#/components/schemas/BatchQRCodeItem'

    BatchBarcodeItem:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum: [barcode]
        text:
          type: string
        barcode_type:
          type: string
          enum: [
            # Most common types for batch operations
            code128, code39, ean13, ean8, upca, upce, isbn, gs1_128,
            pharma, pharmacode, pzn, vin, dbar_omn, itf14,
            # Additional common types
            code93, code11, codabar, jan, gtin, msi, telepen,
            c25inter, itf, dpd, hibc_128, hibc_39, channel
          ]
          default: code128
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG

    BatchQRCodeItem:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum: [qrcode]
        text:
          type: string
        error_correction:
          type: string
          enum: [L, M, Q, H]
          default: M
        box_size:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        border:
          type: integer
          minimum: 0
          maximum: 20
          default: 4
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG

    PostalRequest:
      type: object
      required:
        - text
        - postal_type
      properties:
        text:
          type: string
          description: Data to encode in postal barcode
          example: "0123456709498765432101234567891"
        postal_type:
          type: string
          enum: [usps_imd, usps_postnet, usps_planet, royal_mail, ukroyalmail, australia_post, auspost, netherlands_kix, japan_post, japanpost, korea_post, dpleit, dpident, channel]
          description: Type of postal barcode to generate
          example: "usps_imd"
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
          description: Output image format
        output:
          type: string
          enum: [base64, file]
          default: base64
          description: Response format (base64 JSON or file download)

    PostalResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Base64 encoded image data
        barcode_data:
          type: string
          description: Base64 encoded image data (for POST requests)
        message:
          type: string
          description: Success message with postal type
          example: "USPS Intelligent Mail generated successfully"
        format:
          type: string
          example: "PNG"
        encoding:
          type: string
          example: "base64"
        postal_type:
          type: string
          example: "usps_imd"
        text:
          type: string
          example: "0123456709498765432101234567891"
        user_tier:
          type: string
          enum: [free, basic, pro, enterprise]
          description: User account tier
          example: "free"

    BarcodeResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Base64 encoded image data
        format:
          type: string
          example: "PNG"
        encoding:
          type: string
          example: "base64"
        barcode_type:
          type: string
          example: "code128"
        text:
          type: string
          example: "123456789012"

    EnhancedBarcodeResponse:
      allOf:
        - $ref: '#/components/schemas/BarcodeResponse'
        - type: object
          properties:
            user_tier:
              type: string
              enum: [free, basic, pro, enterprise]
              description: User account tier
              example: "free"

    QRCodeResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Base64 encoded image data
        format:
          type: string
          example: "PNG"
        encoding:
          type: string
          example: "base64"
        error_correction:
          type: string
          example: "M"
        border:
          type: integer
          example: 4
        box_size:
          type: integer
          example: 10
        text:
          type: string
          example: "https://example.com"

    EnhancedQRCodeResponse:
      allOf:
        - $ref: '#/components/schemas/QRCodeResponse'
        - type: object
          properties:
            user_tier:
              type: string
              enum: [free, basic, pro, enterprise]
              example: "free"

    BatchResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        batch_results:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Original position in batch
              success:
                type: boolean
              data:
                type: string
                description: Base64 encoded image (if successful)
              format:
                type: string
              encoding:
                type: string
              error:
                type: string
                description: Error message (if failed)
        total_processed:
          type: integer
          example: 3
        user_tier:
          type: string
          enum: [free, basic, pro, enterprise]
          example: "free"

    AccountResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        account:
          type: object
          properties:
            id:
              type: integer
              example: 123
            email:
              type: string
              format: email
              example: "user@example.com"
            tier:
              type: string
              enum: [free, basic, pro, enterprise]
              example: "free"
            active:
              type: boolean
              example: true
            created_at:
              type: string
              format: date-time
              example: "2024-01-01T00:00:00"
            monthly_limit:
              type: integer
              example: 1000
              description: Monthly request limit (-1 for unlimited)
            current_usage:
              type: integer
              example: 150
            remaining:
              oneOf:
                - type: integer
                - type: string
              example: 850
              description: Remaining requests or 'unlimited'

    UsageResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        usage_stats:
          type: object
          properties:
            current_usage:
              type: integer
              example: 150
            monthly_limit:
              type: integer
              example: 1000
            remaining:
              type: integer
              example: 850
            reset_date:
              type: string
              format: date-time

    EnhancedUsageResponse:
      allOf:
        - $ref: '#/components/schemas/UsageResponse'
        - type: object
          properties:
            usage_stats:
              type: object
              properties:
                account_details:
                  type: object
                  properties:
                    tier:
                      type: string
                      enum: [free, basic, pro, enterprise]
                    created_at:
                      type: string
                      format: date-time
                    api_version:
                      type: string
                      example: "2.0"

    VersionResponse:
      type: object
      properties:
        version:
          type: string
          example: "2.0.0"
        api_version:
          type: string
          example: "1.0"
        build_date:
          type: string
          format: date-time
        environment:
          type: string
          example: "production"

    EnhancedVersionResponse:
      allOf:
        - $ref: '#/components/schemas/VersionResponse'
        - type: object
          properties:
            api_version:
              type: string
              example: "2.0"
            authenticated_user:
              type: string
              enum: [free, basic, pro, enterprise]
              description: Current user tier

    RegistrationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Account created successfully"
        api_key:
          type: string
          example: "bcd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          description: Your new API key for v2 endpoints
        user:
          type: object
          properties:
            id:
              type: integer
            email:
              type: string
              format: email
            tier:
              type: string
              enum: [free, basic, pro, enterprise]
              default: free

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type
          example: "Invalid parameter"
        message:
          type: string
          description: Detailed error message
          example: "The barcode_type must be one of: code128, code39, ean13"
        provided:
          type: string
          description: Invalid value provided (for validation errors)
          example: "invalid_type"

  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_text:
              summary: Missing required parameter
              value:
                error: "Missing required parameter: text"
                message: "text parameter is required"
            invalid_barcode_type:
              summary: Invalid barcode type
              value:
                error: "Invalid barcode_type"
                message: "barcode_type must be one of: code128, gs1, gs1_128, ean14, nve18, sscc18, hibc_128, dpd, ean, ean2, ean5, ean8, ean13, upc, upca, upce, isbn, isbn10, isbn13, sbn, jan, code39, excode39, code32, hibc_39, vin, logmars, code93, code11, codabar, c25standard, c25iata, c25ind, c25inter, itf, c25logic, itf14, dpleit, dpident, plessey, msi, msi_plessey, telepen, telepen_num, pharma, pharmacode, pzn, dbar_omn, dbar_ltd, dbar_exp, databar_omn, databar_ltd, databar_exp, gs1_databar_omn, gs1_databar_ltd, gs1_databar_exp, koreapost, channel, gtin"
                provided: "invalid_type"

    Unauthorized:
      description: Unauthorized - API key required or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_key:
              summary: Missing API key
              value:
                error: "API key required"
                message: "v2 endpoints require a valid API key. Get one at /register"
            invalid_key:
              summary: Invalid API key
              value:
                error: "Invalid API key"
                message: "The provided API key is invalid or inactive"

    RateLimit:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Rate limit exceeded"
              message:
                type: string
                example: "Monthly limit of 1000 requests exceeded"
              usage_info:
                type: object
                properties:
                  current_usage:
                    type: integer
                    example: 1001
                  monthly_limit:
                    type: integer
                    example: 1000
                  reset_date:
                    type: string
                    format: date-time

    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            general_error:
              summary: Server error
              value:
                error: "Internal server error"
                message: "An unexpected error occurred while processing your request"