← Getting Started
Connect to the Maddie's Lab API
Every tool on Maddie's Lab is an API call. If you're a developer, you can call the same endpoints directly from your own product: send a file, get structured data back in seconds.
1. Get an API key
API keys aren't open yet — we're finishing the signup flow. Report a problem and choose "API access" to request early access, or check back soon.
2. Send your first request
All requests go to the API base URL (provided with your key) with your key in the X-API-Key header. Files upload as multipart form data (max 10 MB per file).
curl -X POST https://<api-base-url>/convert \
-H "X-API-Key: YOUR_KEY" \
-F "file=@invoice.jpg" \
-F "document_type=invoice" \
-F "format=json"You'll get back the extracted fields (supplier, invoice number, dates, totals) plus every line item.
3. Endpoints
| Endpoint | What it does |
|---|---|
POST /convert | Extract receipts, invoices, business cards, W-2s and W-9s to CSV, Excel or JSON (params: document_type, format) |
POST /export/csv | Turn extracted JSON into a flat, bookkeeping-ready CSV (one row per line item) |
POST /export/xlsx | Turn extracted JSON into a formatted .xlsx workbook (one row per line item) |
POST /compress | Shrink images with quality and resize controls (params: quality, max_width, max_height, format) |
POST /convert-image | Convert between JPEG, PNG, WebP and GIF; HEIC input supported (param: format) |
POST /handwriting | Transcribe handwritten notes and pages to text (param: format=json|txt) |
POST /pdf/merge | Combine 2–20 PDFs into one document (multipart files[], order preserved) |
POST /pdf/split | Split a PDF by page ranges, returned as a ZIP (param: ranges, e.g. 1-3,5) |
POST /pdf/rotate | Rotate pages 90/180/270° (params: angle, pages = all or ranges) |
POST /images/to-pdf | Combine images into a single PDF (multipart files[], order preserved) |
POST /pdf/to-images | Render each PDF page to an image in a ZIP (params: format=png|jpg, dpi) |
POST /metadata | Inspect EXIF, GPS and document metadata as JSON |
POST /metadata/clean | Strip metadata and return the cleaned file |
POST /watermark | Stamp text watermarks on PDFs and images (params: text, opacity, position, font_size) |
POST /qr/generate | Generate a QR code PNG (params: text, size) |
POST /qr/read | Decode a QR code from an uploaded image |
POST /barcode/generate | Generate Code 128, Code 39, EAN-13, EAN-8 or UPC-A barcodes (params: text, format) |
POST /pdf/to-word | Convert a PDF to an editable .docx |
POST /pdf/to-excel | Extract PDF tables to a real .xlsx workbook |
POST /pdf/redact | Permanently black-bar phrases in a PDF (repeatable param: phrases; count in X-Redactions-Count header) |
POST /pdf/sign | Place a signature image or typed name on a PDF page (params: signature or name, page, x, y, width) |
POST /compare | Diff two documents (TXT, DOCX, PDF) with added/removed counts (params: file_a, file_b) |
POST /pdf/ocr | Add a searchable text layer to scanned PDFs |
POST /corrections | Submit user-corrected fields as training data (consent-gated) |
GET /health | Service status |
4. Limits and errors
- 401 — your
X-API-Keyheader is missing or wrong. - 402 — you've used your plan's document allowance for the month.
- 429 — you're sending requests too fast; slow down and retry.
- 405 on a browser preflight — the API accepts cross-origin calls from our web app; call it from your server, not from browser JavaScript on another site.
Tip: The web tools at portal.maddieslab.com run on this same API — try a document there first to see exactly what the API returns.
Last updated: October 4, 2026
Was this helpful?
Still stuck? If you worked through every step above and it still won't connect, report a problem and tell us which step failed.