Headless API Reference

If you prefer to build your own custom drag-and-drop UI, you can use the headless API Client provided by imgapi to securely interface with the edge servers.

The 3-Phase Protocol

To ensure security and prevent orphaned files, imgapi uses a strict 3-phase upload protocol:

Using the Client Library

In your main application, import the uploadToExtUtil function. You can copy the src/lib/client/media-client.ts file directly into your own project.

import { uploadToExtUtil, commitExtUtilAsset } from '$lib/client/imgapi';

async function handleImageDrop(file: File) {
  // Phase 1 & 2: Token Request and Edge Stream (handled internally by uploadToExtUtil)
  const result = await uploadToExtUtil({
    file: file,
    userId: 123,
    assetType: 'article_inline',
    projectId: 'my_project',
    apiBaseUrl: 'https://imgapi.avadhya.in'
  });

  if (result.error) {
    alert("Upload failed: " + result.error);
    return;
  }

  const { object_key, cdn_url } = result;
  console.log("Uploaded! URL:", cdn_url);

  // Phase 3: Commit the asset to prevent orphan cleanup
  await commitExtUtilAsset(object_key, 'articles', 'article_id_1', 123, 'https://imgapi.avadhya.in');
  
  // Proceed with saving the cdn_url to your database
}

REST API Details

The client library wraps these two core endpoints. Use this reference if you are building your own client from scratch in another language (like Python or Swift).

On-The-Fly Image Transformations

If you're retrieving images, you can apply native Cloudflare Edge resizing simply by passing query parameters to the URL. This allows you to dynamically resize, crop, and optimize images without storing multiple copies.

Webhook Integration

You can configure a Webhook URL in your Project Settings via the Dashboard. When an upload is successfully committed, imgapi will instantly fire an asynchronous POST request to your URL.

Payload Schema

// Webhook Payload Example
{
  "event": "upload.committed",
  "object_key": "uploads/123/my_blog_v1/image.png",
  "cdn_url": "https://cdn.example.com/uploads/123/my_blog_v1/image.png",
  "committed_at": "2023-10-01T12:00:00Z"
}