Public API overview

FileForge ships a public REST API for programmatic conversions. It mirrors the flow the web app uses — upload a file, kick off a conversion, poll for status, download the result — and is intended for scripts, CLIs, build tools, and 3rd-party integrations like Zapier.

Tier requirement

The API is a Forge Pro feature. Free accounts can browse this page and mint nothing — the POST /me/api-keys endpoint returns 403 unless the calling profile is subscription_tier IN ('pro', 'enterprise'). The api-key auth middleware re-checks the tier on every request, so a downgrade revokes effective access immediately.

Base URL

https://fileforge-api.aldrickb.app/v1

The matching App API (/api/v1/*, JWT-auth, used by the web app) lives under the same hostname but is gated by Supabase JWTs and not documented here.

High-level shape

The public API surface is intentionally small:

Method	Path	Purpose
GET	/v1/formats	Tier-filtered preset matrix.
POST	/v1/files/presign-upload	Get a presigned MinIO PUT URL.
POST	/v1/files/{id}/finalize	Verify upload, magic-byte + ClamAV scan.
DELETE	/v1/files/{id}	Wipe a file (object + DB row).
POST	/v1/conversions	Enqueue a conversion job.
POST	/v1/conversions/bulk	Enqueue up to tier.bulk_max jobs at once.
GET	/v1/conversions/{id}	Poll status + progress + signed download URL.
GET	/v1/conversions/{id}/output	302 → fresh presigned download URL.

There is no synchronous one-shot multipart POST /v1/convert in the v1.0.0 beta — all conversions go through the same async queue the web app uses. A multipart shorthand and webhook callbacks are planned for V2.

Two-step flow

1. Presign — POST /v1/files/presign-upload returns a short-lived URL you PUT the file bytes to directly. The API never sees the bytes.
2. Finalize — POST /v1/files/{id}/finalize triggers the magic-byte check and ClamAV scan. On success the file row is persisted.
3. Convert — POST /v1/conversions enqueues a worker job and returns { conversion_id, status: 'queued' }.
4. Poll — GET /v1/conversions/{id} every 1–2s until status is completed, failed, or cancelled.
5. Download — when complete, follow output.download_url (or curl -L /v1/conversions/{id}/output) to fetch the result.

CORS is disabled on /v1/*. This is intentional — the API is for non-browser clients, and disabling preflights makes it harder to accidentally embed an ff_live_… key in front-end JavaScript.