Skip to content
smallPict
Start Free

REST API Overview & Architecture

Base URLs, endpoints, and request conventions of the SmallPict REST API (OpenAPI 3.1).

The SmallPict REST API (OpenAPI 3.1) gives you direct access to image optimization, conversion, and CDN cache control.

Base URLs

EnvironmentEndpoint URLDescription
Productionhttps://api.smallpict.app/v1Production API, routed over anycast
Local Mock Serverhttp://localhost:8080/v1Local development and unit tests

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: Purge cached files from the CDN.

Request and response conventions

  • 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) accept an Idempotency-Key header so that retried requests are never charged twice.