openapi: 3.0.0
info:
  title: Image Conversion API
  description: Professional image conversion API supporting all common formats with batch processing capabilities.
  version: 1.0.0
  contact:
    name: API Support
    url: https://imageconvert.cloud/contact
    email: support@imageconvert.cloud
servers:
  - url: https://imageconvert.cloud/api
    description: Production API Server
tags:
  - name: Authentication
    description: Endpoints for user authentication
  - name: Conversion
    description: Endpoints for image conversion
  - name: Profile
    description: Endpoints for user profile and usage statistics
paths:
  /login:
    post:
      tags: [Authentication]
      summary: Authenticate user and retrieve API token
      description: Authenticates a user and returns an access token for API usage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                password:
                  type: string
                  format: password
                  example: your_password
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Authentication successful
                  token:
                    type: string
                    example: 1|abc123def456...
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid credentials
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /convert:
    post:
      tags: [Conversion]
      summary: Convert images to another format
      description: Convert single images or batches up to 10 files. Supports all major image formats including WEBP, AVIF, and HEIC.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Single image file to convert
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Batch image files (up to 10)
                target_format:
                  type: string
                  description: Target image format (e.g., webp, png, jpg, etc.)
                  example: webp
      responses:
        '200':
          description: Image(s) converted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Image converted successfully
                  data:
                    type: string
                    description: Base64-encoded image data (single file)
                  content_type:
                    type: string
                    example: image/webp
                  filename:
                    type: string
                    example: converted.webp
                  conversion_info:
                    $ref: '#/components/schemas/ConversionInfo'
        '400':
          description: Invalid request or failed to load image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported target format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Monthly conversion limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X POST https://imageconvert.cloud/api/convert \
              -H "Authorization: Bearer YOUR_TOKEN_HERE" \
              -F "file=@image.jpg" \
              -F "target_format=webp"
        - lang: cURL
          source: |
            curl -X POST https://imageconvert.cloud/api/convert \
              -H "Authorization: Bearer YOUR_TOKEN_HERE" \
              -F "files[]=@image1.jpg" \
              -F "files[]=@image2.png" \
              -F "files[]=@image3.gif" \
              -F "target_format=webp"
  /profile:
    get:
      tags: [Profile]
      summary: Get user profile and usage statistics
      description: Retrieve user profile information, account details, and usage statistics.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Profile information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  account_info:
                    $ref: '#/components/schemas/AccountInfo'
                  usage:
                    $ref: '#/components/schemas/UsageInfo'
                  statistics:
                    $ref: '#/components/schemas/Statistics'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          format: email
          example: user@example.com
        account_level:
          type: string
          example: free
        email_verified_at:
          type: string
          format: date-time
          example: 2024-01-01T00:00:00.000000Z
        created_at:
          type: string
          format: date-time
          example: 2024-01-01T00:00:00.000000Z
    ConversionInfo:
      type: object
      properties:
        limit:
          type: integer
          example: 20
        count:
          type: integer
          example: 1
        remaining:
          type: integer
          example: 19
    AccountInfo:
      type: object
      properties:
        name:
          type: string
          example: Free
        conversions_per_month:
          type: integer
          example: 20
        max_file_size:
          type: string
          example: 10MB
        batch_support:
          type: boolean
          example: true
        max_batch_size:
          type: integer
          example: 10
    UsageInfo:
      type: object
      properties:
        conversions_this_month:
          type: integer
          example: 5
        conversions_remaining:
          type: integer
          example: 15
        monthly_limit:
          type: integer
          example: 20
        usage_percentage:
          type: number
          format: float
          example: 25.0
    Statistics:
      type: object
      properties:
        last_12_months:
          type: array
          items:
            type: integer
          example: [25, 18, 32, 45, 28, 39, 22, 33, 41, 29, 35, 42]
        total_last_12_months:
          type: integer
          example: 389
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        status:
          type: integer
          example: 400
        data:
          type: object
          nullable: true
          description: Optional additional error data
  parameters:
    TargetFormat:
      name: target_format
      in: query
      description: Target image format (e.g., webp, png, jpg, etc.)
      required: true
      schema:
        type: string
        example: webp