Please log in to access this page.

ToolNized Document Conversion API Documentation

Welcome to the official documentation for the ToolNized Document Conversion API. This API provides a suite of tools to convert documents between various formats asynchronously.

Asynchronous Workflow: This API operates asynchronously. The process is:
  1. You upload a file to the /api/v1/convert endpoint to start a job.
  2. You receive a unique task_id in response.
  3. You poll the /api/v1/status/{task_id} endpoint periodically until the status changes to complete.
  4. Once complete, you use the provided URL to download the result from /api/v1/download/{task_id}.

Base URL

All API endpoints are relative to your application's root. For your planned deployment, the full base URL will be: 

http://toolnized.com/document-converter/v1/api/v1

Example: https://toolnized.com/document-converter/v1/api/v1

Authentication & Rate Limiting

API Key Required

All requests to the /api/v1/ endpoints must be authenticated using an API Key.

  1. Sign up for a free developer account.
  2. Visit your Developer Dashboard to get your API key.
  3. Pass the key in the Authorization header with the Bearer prefix. 
Authorization: Bearer YOUR_API_KEY_HERE

Rate Limiting

Authenticated requests are rate-limited based on your account tier.

  • Free Tier: Limited to 10 conversions per API key.
  • Pro Tier (Coming Soon): Unlimited conversions.

If you exceed your limit, the API will respond with a 429 Too Many Requests error.

Endpoints

POST /api/v1/convert

Upload a document and start a new conversion task.

Request Body (multipart/form-data)

Parameter Type Description
document File Required. The document file you want to convert.
conversionType String Required. The target format for the conversion. (e.g., pdf-to-word, word-to-pdf, etc.)

Success Response (202 Accepted)

{
    "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "message": "Conversion task started successfully."
}

GET /api/v1/status/{task_id}

Check the status of a previously started conversion task.

URL Parameters

task_id String Required. The unique ID returned by the /convert endpoint.

Success Response (200 OK)

If processing:

{
    "status": "processing",
    "error": null,
    "download_url": null
}

If complete:

{
    "status": "complete",
    "error": null,
    "download_url": "https://[your-domain]/api/v1/download/a1b2..."
}

GET /api/v1/download/{task_id}

Download the final converted file.

Integration Example (Python)

Here is a complete Python script demonstrating how to use the API.


import requests
import time
import os

# --- THIS IS THE URL YOU MUST CONFIGURE ---
# --- It depends on your final server setup ---
API_BASE_URL = "https://toolnized.com/document-converter/v1/api/v1"

FILE_PATH = "path/to/your/document.docx"
CONVERSION_TYPE = "word-to-pdf"
API_KEY = "YOUR_API_KEY_HERE"

def convert_document(file_path, conversion_type, api_key):
    """Handles the full API workflow: upload, poll status, and download."""
    
    headers = { "Authorization": f"Bearer {api_key}" }

    print(f"1. Uploading '{os.path.basename(file_path)}'...")

    with open(file_path, 'rb') as f:
        files = {'document': (os.path.basename(file_path), f)}
        data = {'conversionType': conversion_type}
        response = requests.post(
            f"{API_BASE_URL}/convert", 
            files=files, 
            data=data,
            headers=headers
        )

    if response.status_code != 202:
        print(f"Error during upload: {response.status_code} - {response.text}")
        return

    task_id = response.json()['task_id']
    print(f"    => Success! Task ID: {task_id}")

    print("\n2. Polling for status...")
    while True:
        status_response = requests.get(
            f"{API_BASE_URL}/status/{task_id}",
            headers=headers
        )
        
        if status_response.status_code != 200:
            print(f"    => Error checking status: {status_response.text}")
            return
        
        status_data = status_response.json()
        current_status = status_data.get('status')
        print(f"    => Current status: {current_status}")

        if current_status == 'complete':
            download_url = status_data.get('download_url')
            break
        elif current_status == 'failed':
            print(f"    => Conversion failed: {status_data.get('error')}")
            return
        
        time.sleep(5) 

    if not 'download_url' in locals():
      print("Conversion finished without a download URL.")
      return

    print(f"\n3. Downloading result from {download_url}")
    download_response = requests.get(
        download_url,
        headers=headers
    )

    if download_response.status_code == 200:
        disposition = download_response.headers.get('content-disposition')
        filename = "downloaded_file"
        if disposition:
            try:
                filename = disposition.split('filename=')[1].strip('"')
            except:
                pass 
        
        with open(filename, 'wb') as f:
            f.write(download_response.content)
        print(f"    => File saved successfully as '{filename}'")
    else:
        print(f"    => Error downloading file: {download_response.status_code} - {download_response.text}")

if __name__ == "__main__":
    if API_KEY == "YOUR_API_KEY_HERE":
        print("Error: Please update API_KEY in the script.")
    elif not os.path.exists(FILE_PATH):
        print(f"Error: Please update FILE_PATH. File not found at '{FILE_PATH}'")
    else:
        convert_document(FILE_PATH, CONVERSION_TYPE, API_KEY)