API Documentation

Programmatic access to Convertastic file conversion services

Overview

The Convertastic API provides RESTful endpoints for converting files between various formats. All requests should include proper authentication headers and follow the documented request/response format.

Base URL
https://convertastic.replit.app/api/v1
Content Type
multipart/form-data

API Endpoints

GET Health Check

/api/v1/health

Check API status and availability

Example Response
{
  "success": true,
  "message": "API is healthy",
  "data": {
    "version": "1.0",
    "timestamp": "2025-07-21T16:00:00Z",
    "status": "operational"
  },
  "timestamp": "2025-07-21T16:00:00Z"
}

GET Supported Formats

/api/v1/formats

Get list of all supported file formats and conversion options

Example Response
{
  "success": true,
  "message": "Supported formats retrieved successfully",
  "data": {
    "formats": [
      {
        "format": "png",
        "category": "image",
        "description": "Image format",
        "can_convert_to": ["jpg", "webp", "pdf", "bmp"],
        "can_convert_from": ["png", "jpg", "jpeg", "webp"]
      }
    ]
  }
}

POST Convert File

/api/v1/convert

Convert a file from one format to another

Parameters
Parameter Type Required Description
file File Yes The file to convert (max 100MB)
target_format String Yes Target format (e.g., "jpg", "pdf", "mp3")
quality String No Quality setting: "low", "medium", "high" (default: "medium")
Example Request
curl -X POST https://convertastic.replit.app/api/v1/convert \
  -F "file=@image.png" \
  -F "target_format=jpg" \
  -F "quality=high"
Example Response
{
  "success": true,
  "message": "File converted successfully",
  "data": {
    "conversion_id": "abc123-def456-ghi789",
    "original_filename": "image.png",
    "original_format": "png",
    "target_format": "jpg",
    "file_size": 245760,
    "conversion_time": 1.23,
    "download_url": "/api/v1/download/abc123-def456-ghi789",
    "expires_at": "2025-07-21T16:30:00Z"
  }
}

GET Download Converted File

/api/v1/download/{conversion_id}

Download the converted file using the conversion ID

Example Request
curl -X GET https://convertastic.replit.app/api/v1/download/abc123-def456-ghi789 \
  -o converted_file.jpg
Note: Download links expire after 30 minutes. Files are automatically deleted after download.

GET Conversion Status

/api/v1/status/{conversion_id}

Check the status of a conversion

Example Response
{
  "success": true,
  "message": "Status retrieved successfully",
  "data": {
    "conversion_id": "abc123-def456-ghi789",
    "status": "ready",
    "expires_at": "2025-07-21T16:30:00Z",
    "download_url": "/api/v1/download/abc123-def456-ghi789"
  }
}
Status Values
  • processing - Conversion in progress
  • ready - File ready for download
  • expired - File has expired
  • not_found - Conversion not found

Error Handling

All API responses follow a consistent format. Errors include appropriate HTTP status codes and descriptive messages.

Error Response Format
{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message",
  "timestamp": "2025-07-21T16:00:00Z"
}
Common HTTP Status Codes
Code Description
200Success
400Bad Request - Invalid parameters
404Not Found - Resource not found
413Payload Too Large - File exceeds 100MB
500Internal Server Error

SDK Examples

Python 

import requests

# Convert a file
with open('image.png', 'rb') as f:
    response = requests.post('https://convertastic.replit.app/api/v1/convert', 
                           files={'file': f},
                           data={'target_format': 'jpg', 'quality': 'high'})

if response.status_code == 200:
    result = response.json()
    conversion_id = result['data']['conversion_id']
    
    # Download converted file
    download_response = requests.get(f'https://convertastic.replit.app/api/v1/download/{conversion_id}')
    with open('converted_image.jpg', 'wb') as f:
        f.write(download_response.content)

JavaScript 

// Convert a file
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('target_format', 'jpg');
formData.append('quality', 'high');

fetch('https://convertastic.replit.app/api/v1/convert', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        const downloadUrl = data.data.download_url;
        // Create download link
        const a = document.createElement('a');
        a.href = 'https://convertastic.replit.app/' + downloadUrl;
        a.download = 'converted_file';
        a.click();
    }
});