REST API Overview & Architecture

Authoritative OpenAPI 3.1 specification, base URLs, and core architectural principles of the SmallPict API.

REST API Overview & Architecture

The SmallPict REST API is an OpenAPI 3.1 compliant web service that gives developers direct access to our distributed image optimization, transformation, and edge CDN pipeline.

🌐 Base URLs

Environment	Endpoint URL	Description
Production	`https://api.smallpict.app/v1`	Primary production API gateway with global Anycast routing
High-Availability Fallback	`https://api.smolpict.com/v1`	Redundant secondary gateway for multi-region failover
Local Mock Server	`http://localhost:8080/v1`	Local development and unit test sandbox

🏛️ Core API Endpoints

All endpoints require HMAC-SHA256 authentication headers (see Authentication Guide).

1. Image Optimization & Transcoding

Endpoint: POST /v1/optimize (Alias: POST /v1/convert)
Description: Submit an image for compression and format transformation (AVIF, WebP, JPEG, PNG).

2. Asynchronous Job Polling

Endpoint: GET /v1/optimize/status?job_id={job_id}
Description: Query the status and download URL of an asynchronous conversion job.

3. Account Quota & Usage Metrics

Endpoint: GET /v1/quota
Description: Retrieve real-time bytes processed, monthly plan limits, and CDN bandwidth consumption.

4. Edge CDN Cache Purge

Endpoint: POST /v1/purge
Description: Invalidate and purge cached assets across 300+ global Cloudflare Edge Points of Presence.

📦 Request & Response Standard

All request payloads must be formatted as application/json (or multipart/form-data for direct binary upload).
All response bodies return standardized JSON with RFC3339 timestamps.
Mutating endpoints (POST, DELETE, PATCH) support automatic Idempotency-Key headers to guarantee zero duplicate charges during retries.