A developer friend messaged me last month. He’s building a SaaS for accountants — small product, growing nicely. One feature his customers kept asking for: “Can your app just compress these PDFs before I email them?”
Simple feature on paper. Until he tried to build it.
He spent a weekend on Ghostscript flags trying to get the compression right. Then another evening fighting Docker images because Ghostscript wouldn’t install on his Railway deployment. Then he discovered his compressed PDFs sometimes corrupted the text layer, which broke his customers’ workflow. Then he realized he’d need OCR for scanned PDFs, which meant Tesseract, which meant another binary, more system dependencies, more Docker pain.
“This is supposed to be a one-line feature,” he said. “I’ve spent four days on it.”
This is the conversation that made us build the ConvertKr API. If you’ve ever needed to do something to a PDF inside your own application — compress, merge, split, rotate, convert, extract text — and discovered that the open-source path is a deep rabbit hole, this is for you.
What the API actually does
The same PDF and image tools we’ve been running for free on convertkr.com, exposed as a JSON HTTP API at api.convertkr.com. You send a file in, you get a processed file back. No file storage. No queue infrastructure. No system dependencies to install.
Currently live:
- PDF — compress, merge, split, rotate, crop, organize (reorder pages), add page numbers, insert pages, extract text
- Images — convert (any format to any format), resize, watermark, HEIC to JPG
- More on the way — OCR, HTML to PDF, PDF to image, PDF to Word (Office-grade via our Windows VPS), background removal
Each endpoint takes a multipart file upload, processes in memory, returns the result. No webhooks for small files. No polling. Request goes in, response comes back, done.
The simplest possible example
Compress a PDF with curl:
curl -X POST https://api.convertkr.com/v1/compress-pdf \
-H "Authorization: Bearer ckr_live_YOUR_API_KEY" \
-F "file=@invoice.pdf" \
-F "quality=medium" \
-o invoice-compressed.pdf
That’s it. One HTTP call. The compressed PDF lands in your working directory as invoice-compressed.pdf.
From Node:
import { readFile, writeFile } from 'node:fs/promises';
const file = await readFile('invoice.pdf');
const form = new FormData();
form.append('file', new Blob([file]), 'invoice.pdf');
form.append('quality', 'medium');
const res = await fetch('https://api.convertkr.com/v1/compress-pdf', {
method: 'POST',
headers: { Authorization: 'Bearer ckr_live_YOUR_API_KEY' },
body: form,
});
const buf = Buffer.from(await res.arrayBuffer());
await writeFile('invoice-compressed.pdf', buf);
Same in Python, Go, PHP, Ruby — anything that can make an HTTP request with a multipart form body. We don’t ship official SDKs yet because the API is small enough that a raw HTTP call is shorter than importing a wrapper.
Why credits, not a subscription
This is the part we thought about the most.
Most file-conversion APIs charge a flat monthly subscription — say $49/month for up to 1,000 conversions. Sounds simple. But it punishes anyone whose usage isn’t perfectly steady. If you do 100 conversions in January and 2,000 in February, you either overpay in January or get throttled in February. If your business is seasonal (tax software peaks in April, e-commerce peaks in November), subscription pricing doesn’t fit.
So we went with credits. You buy a pack of credits up front. Each API call deducts a small number of credits based on the operation. Cheap operations (rotate a PDF, convert an image format) cost less. Expensive operations (OCR a scanned document, complex multi-page processing) cost more. Your balance never expires.
| Operation | Approximate credits per call |
|---|---|
| Rotate PDF | 1 |
| Merge / Split PDF | 1-2 |
| Compress PDF | 2 |
| Image convert / resize | 1 |
| HEIC to JPG | 1 |
| PDF to text | 2-3 |
| OCR PDF (when live) | 5-10 per page |
Credits don’t expire. If you buy a 10,000-credit pack and use it over 18 months, no problem. If you burn through it in a week because something on Hacker News linked to your product, also no problem — just buy another pack.
50 credits are granted free on signup so you can test every endpoint before paying anything.
How auth works
Two modes, one user account:
- JWT cookies for the dashboard on
convertkr.com(sign up, view balance, generate API keys, view ledger). - Bearer API keys for the API itself. Keys are formatted as
ckr_live_<32 hex chars>. You generate them in the dashboard, and they show in full exactly once at creation time. After that, only the first 12 characters are stored for display — we hash the rest.
This is the same pattern Stripe uses. We copied it because it’s good and there’s no point reinventing it.
Keys can be revoked instantly from the dashboard. If you suspect a key is compromised, revoke it and generate a new one — no support email required.
What happens to my file?
This is the question we get most.
Nothing. Files are never written to disk. Your PDF arrives in the request body, gets processed in worker memory, the response goes back, and the buffer is garbage-collected. There is no “uploads” folder. There is no S3 bucket. There is no temp directory. If our database vanished tomorrow, your files would not be in it because they never were.
This is the same privacy story as the free tools on convertkr.com. The reason the WordPress side does everything client-side in your browser is that we don’t want to be responsible for your data. The API side does everything in memory for the same reason. The architecture is built around not storing your stuff.
This matters more than people realize. If you’re processing invoices, legal documents, medical PDFs, tax forms — anything sensitive — you don’t want a vendor that keeps copies “for 30 days” or “for billing purposes” or whatever the standard excuse is. We don’t keep copies at all.
The kind of stuff people are building with it
Talking to the developers who’ve signed up so far, here’s what they’re using it for:
SaaS apps adding a “compress before email” feature. Same as my friend’s accountant app. Existing product, customers ask for one PDF feature, the dev doesn’t want to install Ghostscript on their server. One API call solves it.
Invoice processing systems. Merge a customer invoice + statement + receipt into one PDF before sending. Rotate scanned receipts that came in sideways. Compress to under 5MB so they don’t bounce on email.
Real estate apps. Contracts arrive as scanned PDFs, sometimes 30+ pages. Apps split them into per-section PDFs (offer letter, disclosure, addendum) and reorganize for storage. Sometimes add page numbers because the original scan didn’t have them.
Photo / image apps. The iPhone HEIC problem. Users upload HEIC photos, your app needs JPG. Instead of bundling a HEIC decoder, one API call converts it. Same for resizing user uploads to consistent dimensions.
Internal tooling. Operations teams who need to batch-process documents for compliance, archiving, or migration. Scripts that loop through a folder, call the API per file, and write results to a different folder.
WordPress and CMS plugins. Plugins that need to convert or process uploaded files. WordPress hosting is restrictive — you usually can’t install system binaries. An HTTP API sidesteps that whole problem.
Why we didn’t just open-source the conversion code
We get asked this. The conversion code itself is mostly built on open-source libraries (pdf-lib, sharp, and similar). We’re not gatekeeping anything novel.
What we’re selling isn’t the conversion logic. It’s:
- The fact that you don’t have to install Ghostscript / Tesseract / LibreOffice / a Word license on your server
- The fact that scaling is our problem, not yours
- The fact that when a new PDF parser bug or HEIC decoder issue comes out, we patch it, not you
- The fact that you don’t have to deal with file storage, queueing, or memory management for occasional spikes
- One HTTP call that just works
For a developer building product features, this is usually worth more than the credit cost. For an enterprise running 10 million conversions a month, it might not be — and at that scale, you should probably self-host. We’re not trying to win that customer.
The Windows VPS sidequest (Office formats)
One thing that’s NOT in the Node API: Word to PDF, Excel to PDF, PowerPoint to PDF. Anything that converts Microsoft Office files.
The honest reason is that open-source conversion libraries for Office formats (LibreOffice headless, Pandoc) are okay for simple documents but break on real-world files with custom fonts, complex tables, embedded charts, or proprietary Microsoft features. The output looks almost right, which is worse than looking obviously wrong — your customers send it to recruiters or clients and the formatting is subtly broken.
So Office conversion runs on a separate Windows VPS with actual Microsoft Office installed. Real Word renders real Word files. Same outputs you’d get if you opened the file in Office on your laptop and clicked “Save as PDF.” When those endpoints come online in the API, you’ll be able to call them the same way — but they’re routed to that Windows worker behind the scenes.
Just being honest about why it’s two different backends. Anyone who tells you their pure-Node service produces “identical” output to real Word is selling you something.
Pricing and how to start
The cheapest pack is $5 for a starter chunk of credits — enough to test thoroughly. Larger packs have better per-credit rates. No subscription. No auto-charges. You pay when you’re running low.
To start:
- Sign up on convertkr.com with an email and password. You get 50 free credits immediately.
- Go to API Keys in the dashboard. Generate a key. Copy it (you’ll only see the full key once).
- Try a curl command against any endpoint. Watch your balance tick down in real time on the dashboard.
- When you’re ready, buy a credit pack via Lemon Squeezy. Credits land in your account within seconds of payment via webhook.
If you’re integrating into a production app and want to verify the API handles your specific file types before committing, just email us. We’ll grant test credits.
Things we deliberately don’t do
This is the part we never see in API docs but always wish we could see:
We don’t store your files. Already covered above. Worth repeating.
We don’t have webhooks for synchronous operations. Compress a PDF, get the result back in the same HTTP response. No “we’ll send a webhook when it’s ready” for jobs that take 2 seconds.
We don’t bill you for failures. If a conversion fails on our side, no credits are deducted. The deduction happens inside the same database transaction as the successful processing, so a failed request is a free request.
We don’t auto-renew credits. You buy a pack manually. We don’t store your card and surprise you.
We don’t have rate limits as a sales tactic. There are technical rate limits (so one customer can’t accidentally DOS the service) but they’re high enough that legitimate use never hits them. We’re not trying to upsell you to a “Pro” tier by throttling your free tier.
We don’t lock you in. If you stop using us, your credits stay in your account. No “30 days or you forfeit.” If you want a refund on unused credits, we’ll process it.
FAQ
How is this different from CloudConvert / Convertio / PDF.co?
Two things. First, credit pricing instead of monthly subscription — better if your usage is uneven. Second, we don’t store files at any point. Most competitors keep your files on their servers for some retention period (sometimes 24 hours, sometimes 30 days). We never write them to disk at all.
Is there a free tier?
50 credits on signup. Enough to test every endpoint multiple times. No card required. After that, the smallest paid pack is $5.
What’s the file size limit?
Currently 100MB per file for synchronous endpoints. Larger jobs are coming as async endpoints (you submit, get a job ID, poll or webhook for completion).
Do you have SDKs?
Not yet. The HTTP API is small enough that a wrapper would add more friction than value. If you’d like an official SDK in a specific language, tell us — we’ll prioritize it if there’s demand.
Can I self-host this?
Not at the moment. The endpoints are tightly coupled to the credit ledger and Lemon Squeezy billing. We may release the conversion engine as a separate open-source library at some point.
Are you GDPR compliant?
Yes. We don’t store files, we don’t have an analytics tracking layer that records PII, and the only personal data we keep is your email (for the account) and your usage ledger (for billing). You can delete your account from the dashboard and everything goes with it.
What if I need a feature you don’t have yet?
Email us. If it’s something we can build with our existing toolchain, the lead time is usually under two weeks. If it requires a new backend (like the Windows VPS for Office), longer.
Where is the API hosted?
Railway, currently in their US region. Office-conversion workers run on a Windows VPS in Europe. We may add EU/Asia regions if latency becomes a real issue for customers in those regions.
What language is the API written in?
TypeScript on Node.js, using Hono for the HTTP layer, Drizzle ORM with PostgreSQL for the database. We list this because developers always ask — but it doesn’t affect what you can do with the API as a customer.
Need PDF or image processing inside your app and don’t want to install Ghostscript on your server? Sign up — 50 free credits, no card required. Or browse api.convertkr.com for the full endpoint reference.