Image Upload API

An image upload endpoint sounds trivial until you actually build it: you need somewhere durable to put the bytes, a way to avoid streaming large files through your own server, a CDN in front so thumbnails load fast, and access control for anything that isn't public. files.link gives you all of that as a three-call REST flow, and the design deliberately keeps big image payloads off your application server.

Step one, POST /v1/files/{folderId} with the image's metadata, returns a presigned PUT URL plus a file id. Step two, your client (or backend) PUTs the raw image bytes straight to that URL — they never transit your API process, which matters when users upload 12-megapixel phone photos. Step three, POST /v1/files/confirm-upload with {ids:[id]} finalizes the upload, and the file becomes available as a permanent CDN URL. A browser-side example that uploads directly after your backend has minted the presigned URL:

// backend mints step 1 and returns { url, id } to the client
async function uploadImage(file, presignedUrl) {
  await fetch(presignedUrl, {
    method: 'PUT',
    headers: { 'Content-Type': file.type },
    body: file,
  });
}

The Authorization header on the metadata and confirm calls is your raw API key — keep those two calls on your backend so the key never reaches the browser; only the presigned PUT is safe to expose to the client. Every common image type works as-is: JPEG, PNG, WebP, AVIF, GIF, SVG. files.link stores and serves the exact bytes you upload — it does not resize, re-encode, or generate variants, so if you need responsive srcset sizes or format conversion, do that in your pipeline (sharp, a build step, or your framework's image component) before the PUT, or after fetching from the CDN.

What you get in return is dead-simple integration and edge delivery: the moment confirm-upload returns, the CDN URL is live worldwide, so an avatar uploaded in São Paulo renders instantly for a viewer in Oslo. Compared to dropping in Cloudinary or imgix — which bundle transformations you may not need and bill per-transformation — this is a leaner, transform-free path priced from prepaid credits.