API Documentation

The Optimagio API provides powerful image optimization capabilities. Upload images via URL or file upload, or send a full folder as an upload-first batch, and receive optimized versions with significant size reductions while maintaining visual quality.

Key Features

• Input support for JPEG/JPG, PNG, WebP, GIF, AVIF, TIFF, and BMP; output support for JPEG, PNG, WebP, GIF, AVIF, or auto
• URL-based and file upload optimization
• Upload-first batch optimization with automatic batch creation, progress events, and ZIP download
• Configurable compression levels and output formats
• Image resizing with dimension constraints (up to 8000px)
• EXIF metadata is stripped by default; set keep_exif=true to opt in
• Storage Library persistence is explicit; set storage_commit=true when an API request should save optimized results
• Automatic format selection with auto option
• Caching of optimized results
• Dashboard and admin analytics for API-key traffic and batch activity
• Multi-tier access controls with different quotas

All API requests require authentication using an API key. Include your API key in the request headers.

X-API-Key: your_api_key_here

Authorization: Bearer your_api_key_here

For external API clients, POST /api/v1/optimize/batch is the primary batch API. Send files first; the server creates or extends the batch, generates job IDs, and returns the tracking links. For 5000 files, send 50 chunks of up to 100 files with one stable client_batch_id and a unique Idempotency-Key per chunk.

Simple upload

curl -X POST https://api.optimagio.dev/api/v1/optimize/batch \
  -H "X-API-Key:${OPTIMAGIO_API_KEY}" \
  -H "Idempotency-Key: catalog-may-2026-part-1" \
  -F "output_format=webp" \
  -F "compression=auto" \
  -F "storage_commit=true" \
  -F "resize_width=2000" \
  -F "files[]=@products/shoes/nike-001.jpg" \
  -F "files[]=@products/shoes/nike-002.png"

When no manifest is supplied, file names come from the multipart parts and the batch is finalized automatically. Use this mode for small batches and quick integrations.

Advanced manifest

Send a JSON manifest field when you need stable client IDs, folder paths in the ZIP, checksums, chunking, or an expected total.

{
  "client_batch_id": "catalog-2026-05",
  "name": "May product catalog",
  "total_files": 1842,
  "finalize": false,
  "options": {
    "output_format": "webp",
    "compression": "auto",
    "resize_width": 2000,
    "keep_exif": false,
    "storage_commit": true,
    "keep_original": false
  },
  "files": [
    {
      "field": "file_0",
      "client_file_id": "products/shoes/nike-001.jpg",
      "relative_path": "products/shoes/nike-001.jpg",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

curl -X POST https://api.optimagio.dev/api/v1/optimize/batch \
  -H "X-API-Key:${OPTIMAGIO_API_KEY}" \
  -H "Idempotency-Key: catalog-2026-part-0001" \
  -F 'manifest={"client_batch_id":"catalog-2026-05","total_files":1842,"finalize":false,"options":{"output_format":"webp","compression":"auto"},"files":[{"field":"file_0","client_file_id":"products/shoes/nike-001.jpg","relative_path":"products/shoes/nike-001.jpg"}]}' \
  -F "file_0=@products/shoes/nike-001.jpg"

Chunked upload

Idempotency

client_batch_id is scoped to the authenticated user and helps find the same batch after a retry or process restart. It is not a substitute for per-chunk idempotency.

Polling and retrieval

• Use GET /api/v1/batches/:id?files_limit=1000&files_offset=0 as the primary integration path for status and result visibility.
• Advance files_offset through large batches; the response reports whether more file rows are available.
• SSE at /api/v1/batches/:id/events remains available for live UI progress, but polling is the recommended external API baseline.
• Use download_zip for completed batch retrieval. Completed file rows can include download_url, but those per-file links can expire; the batch ZIP returns 409 partial_batch_results_unavailable if any completed output is missing.

Limits, paths, and accounting

• Each upload-first request accepts up to 100 files and uses the bundle upload protection bucket, not the 10 MB sync optimize bucket.
• A batch can contain up to 50,000 files; 5000 files should be split into 50 requests with 100 files each.
• Per-file size limits are tier-aware. Oversized files are rejected before queueing, recorded as failed batch rows, and consume zero optimization credits.
• Batch semantics are per_item: invalid relative_path, invalid sha256, checksum mismatches, and oversized files go to rejected_files while accepted files continue processing.
• Monthly image quota is enforced by workers. A chunk can queue more files than the remaining quota; extra jobs become quota_paused and can resume after upgrade or reset.
• Cache hits are free for monthly image credits but still appear in analytics. Result bandwidth is counted separately where bandwidth limits apply.
• Batch ZIP download preserves validated relative_path folder structure. Without a safe path, files use the flat optimized filename behavior.

Advanced/internal-compatible flow

Most integrations should use POST /api/v1/optimize/batch. The explicit batch and bundle routes remain available for dashboard internals, older preflight flows, pause/resume/cancel before upload, and custom enterprise automation.

POST /api/v1/batches
POST /api/v1/optimize/async/upload-bundle
GET  /api/v1/batches/{batch_id}
GET  /api/v1/batches/{batch_id}/events
GET  /api/v1/batches/{batch_id}/download

Throughput is protected by four layered systems. Each runs independently; whichever rejects first wins.

Layer 1 — Edge / per-IP protection

Each route family has a per-IP cap with sustained-violation IP blocking. Anonymous/global rate-limit hits return 429 with Retry-After when a retry delay is available.

Layer 2 — Per-account result window

A strict fixed-minute window per user. Successful cloud optimizations consume rate_limit_per_minute slots and monthly image credits. Cache hits are recorded in analytics but are free for monthly image credits. When the window is full, authenticated work waits or moves to the queue instead of returning a user-facing rate error.

Batch uploads follow partial drain quota policy: accepted chunks may queue more files than the remaining monthly image quota, but workers do not process or bill beyond the limit. Extra jobs stay quota_paused until quota resets or the account receives more capacity.

Layer 3 — Per-API-key bucket

In addition to the per-user window, each API key has its own cap at ~50% of the user-level rate by default. One bombing key won't starve the user's other keys.

Layer 4 — Worker pool / readiness

When the worker pool's queue load goes over 90%, the /api/healthz/ready probe returns 503 so upstream load balancers route around the node. Free-tier jobs may also have their compression auto-bumped under load (adaptive quality).

Rate-limit headers

Responses from rate-limited routes include current counters:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1761696000
Retry-After: 24            (only on 429)

For URL-based optimization that may take seconds (large remote fetches, heavy AVIF encodes, queue contention), submit the job asynchronously and poll for status. Frees up the HTTP connection immediately and the same tier limits and quotas apply.

For file batches, prefer Upload-First Batch Optimization. The older explicit batch + upload-bundle flow remains available as an advanced/internal-compatible path for clients that need preflight control.

Submit a job

POST /api/v1/optimize/async
X-API-Key: your_key
Content-Type: application/json

{
  "url": "https://example.com/photo.jpg",
  "compression": "auto",
  "format": "webp",
  "width": 1200
}

Returns 202 Accepted with the job id:

{
  "job_id": "8f3c6d2e-1b4a-4d3e-9c8f-a4b3e2d1c0e1",
  "status": "queued",
  "status_url": "/api/v1/jobs/8f3c6d2e-1b4a-4d3e-9c8f-a4b3e2d1c0e1"
}

Poll for status

GET /api/v1/jobs/{'{'}job_id{'}'}
X-API-Key: your_key

Status progression: queued → processing → completed | failed. Batch file rows can also report quota_paused when monthly image quota is exhausted before the worker starts that file.

{
  "id": "8f3c6d2e-...",
  "status": "completed",
  "progress": 100,
  "result_image_id": "abc123...",
  "result_url": "/api/images/abc123...",
  "created_at": 1761696000,
  "updated_at": 1761696012
}

POST /api/v1/batches
POST /api/v1/optimize/async/upload-bundle

Report and Site Audit APIs use dashboard JWT sessions. Shared report reads are public only for callers holding the generated token. Optimization reports store metadata, not optimized image bytes.

POST /api/v1/reports
Authorization: Bearer dashboard_jwt
Content-Type: application/json

{
  "title": "Homepage batch",
  "processing_mode": "browser_only",
  "report_sync_mode": "sync",
  "files": [
    {
      "name": "hero.jpg",
      "original_size": 1048576,
      "optimized_size": 421888,
      "status": "completed",
      "processed_by": "local_wasm"
    }
  ]
}

{
  "status": "generated",
  "reused": false,
  "report": {
    "id": "6d1f2c6a-4d2c-4216-8c99-c3f9ef119a10",
    "title": "Homepage batch",
    "verification_status": "browser_reported",
    "processing_mode": "browser_only",
    "file_count": 1,
    "saved_bytes": 626688,
    "cloud_credits_used": 0,
    "cloud_credits_saved": 1
  }
}

POST /api/v1/reports/{report_id}/share
Authorization: Bearer dashboard_jwt

{
  "id": "72b0c734-c1af-4be8-a44c-3e3cd64f28b7",
  "report_id": "6d1f2c6a-4d2c-4216-8c99-c3f9ef119a10",
  "token": "show-once-share-token",
  "url": "/reports/shared/show-once-share-token",
  "created_at": "2026-05-07T10:30:00Z"
}

POST /api/v1/site-audits
Authorization: Bearer dashboard_jwt
Content-Type: application/json

{
  "url": "https://example.com",
  "max_pages": 10
}

{
  "id": "9b4e6762-334b-4977-87fb-6d5e77db13f1",
  "status": "queued",
  "status_url": "/api/v1/site-audits/9b4e6762-334b-4977-87fb-6d5e77db13f1",
  "max_pages": 10,
  "pages_limit": 25
}

GET /api/v1/site-audits/{audit_id}
Authorization: Bearer dashboard_jwt

{
  "id": "9b4e6762-334b-4977-87fb-6d5e77db13f1",
  "root_url": "https://example.com",
  "status": "completed",
  "stage": "finalizing",
  "score": 74,
  "pages_scanned": 5,
  "images_found": 42,
  "fixable_images": 18,
  "potential_savings_bytes": 8388608,
  "can_optimize": true,
  "images": [],
  "recommendations": [],
  "top_issues": []
}

Your access tier determines monthly image quota, monthly bandwidth, stored-result cap, max file size, and rate limits. The canonical internal identifier returned by GET /api/limits is subscription_tier; it is an access and quota field, not billing consent or proof of a paid subscription. Values are: free, starter, pro, business, scale. Monthly bandwidth means accepted optimized result bytes handled by Optimagio. Included delivery is EU/NA Standard or approved Volume; high-cost global Standard delivery requires explicit Global Delivery opt-in; metered quota billing is not available. MB, GB, and TB quota labels use decimal SI bytes; JSON byte fields stay raw bytes.