Documentation

Everything you need to integrate Tonta into your application. Get started in minutes with our simple API and powerful features.

Quick Start

Get up and running with Tonta in less than 5 minutes. This guide will walk you through creating your first uploader and integrating it into your application.

1. Create an Account

Sign up for a free account at dash.tonta.io. You'll get instant access to create uploaders and manage your files.

2. Create Your First Uploader

From your dashboard, click "Create Uploader" and configure your settings:

JSON 
{
  "name": "My First Uploader",
  "allowed_types": ["image/jpeg", "image/png", "image/webp"],
  "max_file_size": 10485760,  // 10MB
  "processing": {
    "resize": {
      "width": 1920,
      "height": 1080,
      "mode": "fit"
    },
    "optimize": true,
    "convert_to_webp": true
  }
}

3. Add to Your Website

Add the uploader script to your HTML page:

HTML 
<!-- Target element -->
<div class="my-uploader"></div>

<!-- Tonta script -->
<script src="https://tonta.io/uploader/uploader.js"
        data-backend="https://api.tonta.io/upload"
        data-target=".my-uploader"
        data-api-key="YOUR_API_KEY"
        data-callback="handleUpload"></script>

<!-- Handle uploads -->
<script>
window.handleUpload = {
    onUploadComplete(file, result) {
        console.log('Uploaded:', result.files[0].link);
        // Use the uploaded image URL
        document.getElementById('preview').src = result.files[0].link;
    }
};
</script>

Authentication

Tonta uses API keys to authenticate requests. You can find your API keys in the dashboard under Settings → API Keys.

Using API Keys

Include your API key in the X-API-Key header for all API requests:

BASH 
curl -X POST https://api.tonta.io/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@image.jpg"

Domain Restrictions

For added security, you can restrict API keys to specific domains. This prevents unauthorized use if your key is exposed in client-side code.

Security Best Practices

  • Use domain restrictions for client-side keys
  • Keep server-side keys secret
  • Rotate keys regularly
  • Use environment variables for key storage

Upload API

The Upload API is the core of Tonta. Use it to upload files programmatically from any application or platform.

Endpoint

Method Endpoint Description
POST /upload Upload one or more files

Request Parameters

Parameter Type Required Description
file File Yes The file to upload (can be multiple)
uploader_id String No Specific uploader configuration to use
metadata JSON No Custom metadata to attach to the file

Example Request

JAVASCRIPT 
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('metadata', JSON.stringify({
    title: 'Product Image',
    category: 'electronics'
}));

const response = await fetch('https://api.tonta.io/upload', {
    method: 'POST',
    headers: {
        'X-API-Key': 'YOUR_API_KEY'
    },
    body: formData
});

const result = await response.json();
console.log('Uploaded:', result.files[0].link);

Response Format

JSON 
{
  "success": true,
  "files": [
    {
      "id": "abc123def456",
      "smallid": "Ax7Bz9",
      "link": "https://cdn.tonta.io/abc123def456.jpg",
      "thumbnail": "https://cdn.tonta.io/abc123def456_thumb.jpg",
      "size": 245632,
      "type": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "metadata": {
        "title": "Product Image",
        "category": "electronics"
      },
      "created_at": "2025-01-02T10:30:00Z"
    }
  ]
}

File Management

Manage your uploaded files programmatically with our file management endpoints.

List Files

Method Endpoint Description
GET /files List all files with pagination
BASH 
curl -X GET "https://api.tonta.io/files?page=1&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Get File Details

Method Endpoint Description
GET /files/{id} Get details for a specific file

Delete File

Method Endpoint Description
DELETE /files/{id} Delete a file permanently

Important

Deleting a file is permanent and cannot be undone. The file will be removed from all CDN locations within 60 seconds.

Webhooks

Receive real-time notifications when events occur in your Tonta account. Perfect for building automated workflows.

Configuring Webhooks

Add webhook endpoints in your dashboard under Settings → Webhooks. You can configure different endpoints for different events.

Available Events

Event Description
upload.complete Fired when a file upload is successfully completed
upload.failed Fired when a file upload fails
file.deleted Fired when a file is deleted
processing.complete Fired when image processing is complete

Webhook Payload

JSON 
{
  "event": "upload.complete",
  "timestamp": "2025-01-02T10:30:00Z",
  "data": {
    "file": {
      "id": "abc123def456",
      "link": "https://cdn.tonta.io/abc123def456.jpg",
      "size": 245632,
      "type": "image/jpeg"
    },
    "uploader": {
      "id": "uploader_xyz789",
      "name": "Product Images"
    }
  }
}

Verifying Webhooks

All webhook requests include a signature in the X-Tonta-Signature header. Verify this signature to ensure the request is from Tonta:

JAVASCRIPT 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
    const hash = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    
    return hash === signature;
}

Error Handling

Tonta uses standard HTTP response codes to indicate success or failure. All error responses include a detailed message to help you debug.

Error Response Format

JSON 
{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds the maximum allowed size of 10MB",
    "details": {
      "file_size": 15728640,
      "max_size": 10485760
    }
  }
}

Common Error Codes

Code HTTP Status Description
INVALID_API_KEY 401 The provided API key is invalid or missing
FILE_TOO_LARGE 413 File exceeds the maximum allowed size
INVALID_FILE_TYPE 415 File type is not allowed by the uploader
QUOTA_EXCEEDED 429 Upload quota has been exceeded
SERVER_ERROR 500 An unexpected error occurred

Image Processing

Tonta automatically processes images based on your uploader configuration. You can resize, optimize, add watermarks, and more.

Processing Options

JSON 
{
  "processing": {
    "resize": {
      "width": 1920,
      "height": 1080,
      "mode": "fit",  // "fit", "fill", "crop", "stretch"
      "gravity": "center"  // "center", "north", "south", etc.
    },
    "optimize": true,
    "quality": 85,  // 1-100
    "convert_to_webp": true,
    "watermark": {
      "image": "https://example.com/watermark.png",
      "position": "bottom-right",
      "opacity": 0.5,
      "scale": 0.2
    },
    "variants": [
      {
        "name": "thumbnail",
        "width": 200,
        "height": 200,
        "mode": "crop"
      },
      {
        "name": "mobile",
        "width": 768,
        "quality": 90
      }
    ]
  }
}

On-Demand Processing

You can also process images on-demand using URL parameters:

HTML 
<!-- Resize to 400x300 -->
<img src="https://cdn.tonta.io/image.jpg?w=400&h=300">

<!-- Convert to WebP with 80% quality -->
<img src="https://cdn.tonta.io/image.jpg?format=webp&q=80">

<!-- Crop to square -->
<img src="https://cdn.tonta.io/image.jpg?w=500&h=500&mode=crop">