API documentation

Authentication

Anonymous requests get 25 calls per day. With an API key (issued instantly when you subscribe), requests are unlimited and the large-file flow unlocks. Pass the key in the X-Api-Key header.

Convert a file (up to 4 MB)

Send the file as the raw request body. The converted file comes straight back, with the correct Content-Type and a filename in Content-Disposition:

curl -X POST https://formatably.com/api/v1/tools/heic-to-jpg \
  -H "X-Api-Key: fa_live_..." \
  --data-binary @photo.heic \
  -o photo.jpg

Swap heic-to-jpg for any endpoint in the table below. Requests over 4 MB are rejected with a 413; use the large-file flow instead.

Convert a large file (up to 100 MB)

For files over 4 MB, upload directly to storage with a presigned URL, then trigger the conversion. Three steps, requires an API key.

1. Create a job. The response contains a one-time uploadUrl (valid 15 minutes) and a convertUrl:

curl -X POST https://formatably.com/api/v1/jobs \
  -H "X-Api-Key: fa_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tool": "heic-to-jpg"}'

2. PUT the file bytes to the uploadUrl (this goes straight to object storage, not our servers):

curl -X PUT "<uploadUrl>" --data-binary @photo.heic

3. POST the convertUrl. The response is JSON with a downloadUrl for the converted file (valid 1 hour):

curl -X POST "https://formatably.com<convertUrl>" \
  -H "X-Api-Key: fa_live_..."

{
  "downloadUrl": "https://...",
  "contentType": "image/jpeg",
  "bytes": 1830412,
  "expiresIn": 3600
}

Use it in a no-code automation

Because every converter is a plain HTTP endpoint, you can call it from Zapier, Make, n8n, or any workflow tool that has an HTTP request step, no code required. Configure the step like this:

• Method: POST
• URL: https://formatably.com/api/v1/tools/<tool-slug> (for example heic-to-jpg; every slug is in the table below)
• Header: X-Api-Key: your_key
• Body: the file itself, mapped from a previous step (an attachment, an uploaded file, a downloaded URL), sent as binary

The response body is the converted file, ready to map straight into the next step of your workflow: save it to Drive or Dropbox, attach it to a record, or upload it to your CMS.

Responses

• 200: converted file with the correct MIME type (direct), or JSON with a download URL (large-file flow).
• 422: the file could not be decoded; JSON body explains why.
• 429: anonymous daily limit reached.
• 401: invalid or deactivated API key.
• 413: body over 4 MB on a direct request (use the large-file flow), or over 100 MB on the large-file flow.
• 501: this converter is browser-only (currently the two PDF-to-image tools).

Endpoints