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 ($0.20/credit). Minimum deposit $10. Credits never expire.
• Add credits in Account Settings → API Keys → Add Credits (PayPal). Credits land within seconds.
• Testing is free through the web dashboard (Free plan) — the Playground.

Authentication

Authenticate every request with an API key created in your account settings:

Authorization: Bearer fml_<your_api_key>

Keys are shown in full exactly once at creation; only a hash is stored server-side. Create and revoke keys from Account Settings.

Idempotency

POST /documents and POST /documents/upload accept an optional Idempotency-Key header. If you retry with the same key, the original job is returned instead of creating a duplicate — so a network retry never formats (or charges) the same document twice. Use a fresh UUID per distinct document and reuse it when retrying.

POST /api/v1/documents
Authorization: Bearer fml_...
Idempotency-Key: 8f3c1e2a-9b4d-4c7e-a1f0-0d2b3c4d5e6f
Content-Type: application/json

Quickstart

Three steps: create a job, poll for status, download the formatted document.

1. Create a job (document bytes base64-encoded)

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

2. Poll until the job is done

curl https://api.formatlyapp.com/api/v1/documents/<job_id> \
  -H "Authorization: Bearer fml_..."

3. Download the formatted .docx

curl -o formatted.docx \
  https://api.formatlyapp.com/api/v1/documents/<job_id>/download \
  -H "Authorization: Bearer fml_..."

Endpoints

All paths are relative to https://api.formatlyapp.com/api/v1.

Webhooks

Skip polling: register an endpoint and Formatly POSTs 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://api.formatlyapp.com/api/v1/documents/0e6d4a1b-.../download",
  "report_url": "https://api.formatlyapp.com/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.

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.
• Rate limits per API key: 10 job creations/min, 60 status checks/min, 20 downloads/min, 10 reports/min, 30 webhook operations/min.

Errors

Errors return structured JSON with an HTTP status code, a machine-readable error code, a human-readable message, and a resolution hint where applicable.