API Playground

When to use: Verify the service is running and responsive.

• Kubernetes / Docker health probes (liveness & readiness)
• Uptime monitoring dashboards (e.g. UptimeRobot, Datadog)
• CI/CD pipelines to confirm a deployment succeeded

No authentication required — safe to expose to load balancers.

When to use: Upload a file directly from your backend server.

• Server-side uploads where your backend has the file (e.g. processing a form submission)
• Enable generateVariants to auto-create thumbnail, small, medium, large, and WebP versions on upload
• Use async=true for large images — returns immediately with a jobId you can poll
• Use async=false (default) for small images when you need variants ready instantly

Best for: backend-to-backend uploads. For browser-to-S3 uploads, use the presigned upload endpoint instead.

When to use: Let the client (browser/mobile) upload directly to S3 without routing the file through your server.

• Frontend file uploads — your backend calls this to get a signed URL, then the client PUTs the file directly to S3
• Reduces server bandwidth and latency for large files
• The signed URL expires, so it's safe to hand to the client

Typical flow: frontend requests presigned URL → uploads directly to S3 → notifies your backend with the objectKey.

When to use: Fetch a single media file with all its metadata and variants.

• Media detail pages or editors
• Loading full file info including variants after an upload

When to use: Browse and search media files for the authenticated organization.

• Media library / gallery views
• Search by filename or filter by MIME type prefix
• Paginated results with total count

When to use: Fetch multiple media files in a single request (max 100 IDs).

• Loading media for a page with multiple images
• Resolving media references from a CMS or content store

When to use: Update metadata fields on an existing media file.

• Edit alt text, captions, or descriptions after upload
• Toggle isPrivate visibility
• Only provided fields are updated — omitted fields remain unchanged

When to use: Fetch all generated variants (thumbnail, small, medium, etc.) for a media file.

• Building responsive image sets with <picture> / srcset
• Checking which variants have been generated

When to use: Crop, rotate, or reformat an already-uploaded image in place.

• User-driven image editing — e.g. a profile photo cropper in your UI sends the crop coordinates here
• The original file is replaced with the cropped version
• Enable regenerateVariants to rebuild all size variants from the new crop
• Supports rotation (0/90/180/270), scaling, quality, and format conversion (webp, jpeg, png)

Use async=true if you also regenerate variants, since that adds processing time.

When to use: Rebuild all image variants (thumbnail, small, medium, large, original_webp) from the current original file.

• After a presigned upload — the file is in S3 but no variants exist yet
• After changing variant size/quality definitions and you need to backfill existing images
• If variants were corrupted or accidentally deleted

Always runs asynchronously — returns a jobId to poll via the Job Status endpoint. Requires Redis.

When to use: List all generated variants (with URLs, sizes, and MIME types) for a given original file.

• Build responsive <picture> / srcset elements by fetching available sizes
• Admin panels — show which variants exist and their file sizes
• Verify that variant generation completed successfully

Scans the S3 folder for the given object and returns all files found alongside the original.

When to use: Get a redirect to the public CDN URL for a specific variant by name.

• Quick access when you know the variant name you want (thumbnail, small, medium, large, original_webp)
• Useful in server-side rendering — resolve the variant URL without storing it in your database
• Returns a 302 redirect to the CDN URL, so the client follows it automatically

Returns 404 if the requested variant doesn't exist for that file.

When to use: Generate a temporary, signed download URL for a file stored in S3.

• Private files that should not be publicly accessible via CDN
• Time-limited access — share a link that expires (1 second to 24 hours)
• The URL points directly to S3 (not CDN) since the signature is bound to the origin host

If your files are public and served via CDN, you don't need this — use the CDN URL from the upload response instead.

When to use: Stream a file directly through the media service (proxied from S3).

• When you need authenticated downloads — the request requires the API key
• Useful if S3 is not publicly accessible and you can't use presigned URLs
• Sets Cache-Control: public, max-age=31536000, immutable for browser caching

For public files, prefer serving via CDN directly instead of proxying through this endpoint.

When to use: Permanently delete a file and all of its generated variants from S3. Delete by media ID or by object key. Provide one or the other.

• User deletes a photo or attachment from your application
• Cleanup after content moderation flags inappropriate content
• Deletes the entire folder prefix — original + thumbnail + small + medium + large + original_webp

This action is irreversible. Ensure your application confirms with the user before calling this endpoint.

When to use: Check the progress of an async variant generation or crop job.

• Poll after receiving a jobId from upload (async), crop (async), or variant regeneration
• States: pending → active → completed or failed
• Use for progress bars or "processing..." indicators in your UI
• If failed, the failedReason field explains what went wrong

Requires Redis to be configured. Returns 503 if async processing is disabled.