Formatly API

Credits & deposits

• 1 credit = 1 API call = 1 formatted document. Deducted only when a job reaches formatted — failed requests cost nothing.
• Flat rate $1 = 5 credits, minimum deposit $10, any amount ≥ $10 works. Credits never expire.
• Deposit in Account Settings → API Keys → Add Credits (PayPal). Credits land within seconds, automatically.
• Testing the API is free: upload through the web dashboard (Free plan) before depositing — the Playground.

Authentication

Authenticate every request with an API key:

Authorization: Bearer fml_<your_api_key>

Create and revoke keys from Account Settings — keys are shown in full exactly once at creation time. Only the hash is stored server-side, so treat them like passwords.

Quickstart

Three steps: create a job, poll for status, download the formatted document. The full walkthrough is in the API docs.

curl -X POST https://formatly-production.up.railway.app/api/v1/documents \
  -H "Authorization: Bearer fml_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "thesis.docx",
    "content": "UEsDBBQ... (base64)",
    "style": "apa"
  }'

curl https://formatly-production.up.railway.app/api/v1/documents/<job_id> \
  -H "Authorization: Bearer fml_..."

curl -o formatted.docx \
  https://formatly-production.up.railway.app/api/v1/documents/<job_id>/download \
  -H "Authorization: Bearer fml_..."

Endpoints

All paths are relative to https://formatly-production.up.railway.app/api/v1.

Webhooks

Skip polling entirely: register an endpoint and Formatly will POST to it when a job finishes. Events: document.completed and document.failed. Manage webhooks in Account Settings — each webhook gets a signing secret shown once at creation.

{
  "event": "document.completed",
  "job_id": "0e6d4a1b-...",
  "status": "formatted",
  "filename": "thesis.docx",
  "style": "apa",
  "download_url": "https://formatly-production.up.railway.app/api/v1/documents/0e6d4a1b-.../download",
  "report_url": "https://formatly-production.up.railway.app/api/v1/documents/0e6d4a1b-.../report?format=json"
}

Verify every delivery with the X-Formatly-Signature header: an HMAC-SHA256 of the raw request body signed with your webhook's secret, prefixed with sha256=. Failed deliveries retry up to 3 times with exponential backoff. Make your handler idempotent — deliveries can arrive more than once.

Credits & rate limits

• Credits are deducted only on success. Validation errors, webhook test deliveries, /styles and /usage cost nothing. A zero balance makes job submission return 402 until you deposit again.
• Rate limits apply per API key: 10 job creations/minute, 60 status checks/minute, 20 downloads/minute, 10 reports/minute, 30 webhook operations/minute.

Need help?

The full reference is in the API docs. Questions? Reach out through the contact page.