convertor/API.md

ConvertX OpenAPI Documentation

ConvertX now includes a fully-featured REST API for programmatic file conversions.

API Overview

• Base URL: http://localhost:3110/api/v1
• Authentication: JWT Bearer tokens or API keys
• Format: JSON
• Rate Limiting: 100 requests per 15 minutes (configurable)

Quick Start

1. Get Authentication Token

# Register a new account
curl -X POST http://localhost:3110/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "securepassword"}'

# Or login to existing account
curl -X POST http://localhost:3110/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "securepassword"}'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "email": "user@example.com"
    },
    "expiresIn": "7d"
  }
}

2. List Available Converters

curl http://localhost:3110/api/v1/converters \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Check Supported Formats

# Check which converters support PDF input
curl http://localhost:3110/api/v1/converters/formats/pdf \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Start a Conversion (Coming Soon)

Full file upload support is coming. Current implementation requires files to be pre-uploaded.

curl -X POST http://localhost:3110/api/v1/conversions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{"name": "document.pdf"}],
    "converter": "libreoffice",
    "outputFormat": "docx"
  }'

5. Check Job Status

curl http://localhost:3110/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

6. Download Converted Files

curl http://localhost:3110/api/v1/files/JOB_ID/document.docx \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o document.docx

API Endpoints

Authentication

• POST /api/v1/auth/login - Login with email/password
• POST /api/v1/auth/register - Register new account
• GET /api/v1/auth/me - Get current user info
• POST /api/v1/auth/logout - Clear auth cookie

Converters

• GET /api/v1/converters - List all converters
• GET /api/v1/converters/:name - Get converter details
• GET /api/v1/converters/formats/:format - Find converters for format

Conversions

• POST /api/v1/conversions - Start conversion job

Jobs

• GET /api/v1/jobs - List user's jobs
• GET /api/v1/jobs/:id - Get job details
• DELETE /api/v1/jobs/:id - Delete job

Files

• GET /api/v1/files/:jobId - List files in job
• GET /api/v1/files/:jobId/:fileName - Download file

Health

• GET /api/v1/health - API health check

Swagger Documentation

Interactive API documentation is available at:

http://localhost:3110/api/v1/swagger

Environment Variables

# API Configuration
API_ENABLED=true              # Enable API endpoints
API_PREFIX=/api/v1           # API URL prefix
API_RATE_LIMIT=100           # Requests per window
API_RATE_WINDOW=15m          # Rate limit window
API_KEY_ENABLED=false        # Enable API key auth (coming soon)

# Authentication
JWT_SECRET=your-secret-key   # JWT signing secret
ALLOW_UNAUTHENTICATED=false  # Allow anonymous access
ACCOUNT_REGISTRATION=true    # Allow new registrations

Client Examples

JavaScript/TypeScript

class ConvertXClient {
  constructor(private baseUrl: string, private token: string) {}

  async listConverters() {
    const response = await fetch(`${this.baseUrl}/converters`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return response.json();
  }

  async startConversion(files: File[], converter: string, outputFormat: string) {
    // Implementation coming soon with multipart upload support
  }
}

Python

import requests

class ConvertXClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def list_converters(self):
        return requests.get(f'{self.base_url}/converters', headers=self.headers).json()
    
    def get_job_status(self, job_id):
        return requests.get(f'{self.base_url}/jobs/{job_id}', headers=self.headers).json()

cURL

# Set your token
TOKEN="your-jwt-token"
BASE_URL="http://localhost:3110/api/v1"

# List converters
curl -H "Authorization: Bearer $TOKEN" $BASE_URL/converters

# Check health
curl $BASE_URL/health

Error Handling

All errors follow a consistent format:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Additional information (if available)"
}

Common error codes:

• UNAUTHORIZED - Missing or invalid authentication
• NOT_FOUND - Resource not found
• BAD_REQUEST - Invalid request parameters
• VALIDATION_ERROR - Input validation failed
• INTERNAL_ERROR - Server error

Rate Limiting

Rate limit information is included in response headers:

• X-RateLimit-Limit - Maximum requests allowed
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - Time when limit resets (Unix timestamp)

Coming Soon

1. Multipart file upload - Direct file upload in conversion endpoint
2. API key authentication - Alternative to JWT for automation
3. Webhooks - Get notified when conversions complete
4. Batch operations - Convert multiple files in parallel
5. Advanced options - Pass converter-specific options
6. S3/Cloud storage - Direct upload/download from cloud storage

Security Notes

1. Always use HTTPS in production
2. Keep your JWT tokens secure
3. Set strong JWT_SECRET in production
4. Enable rate limiting to prevent abuse
5. Use CORS settings appropriate for your use case

Support

For API issues or feature requests, please open an issue on GitHub.