Skip to content

API documentation

Every Toolbeam tool is an HTTP endpoint first and a web page second. One API key, plain REST, JSON or multipart in, files or JSON out — everything below is runnable curl.

Getting started

  1. 1. Get a keyCreate a free account and generate a key from the dashboard. It is shown once in full — only its hash is stored, so copy it then.
  2. 2. AuthenticateSend X-API-Key: pk_… on every request (or a session JWT as Authorization: Bearer). One key works across all services, under https://toolbeam.app/api.
  3. 3. Mind the quotaPlans carry monthly per-tool allowances. Over one, you get 429 with a JSON detail; batch endpoints meter per item and refund anything undelivered. Errors are always {"detail": "…"} with conventional status codes.

QR codes

Static codes (PNG or SVG, optional logo), bulk generation from CSV, and dynamic codes whose destination you can edit after printing — with scan stats.

POST/api/qr/generate

Generate one static QR code.

curl -X POST https://toolbeam.app/api/qr/generate \
  -H "X-API-Key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"data": "https://example.com", "format": "png", "scale": 8}' \
  --output code.png
  • Works without a key at a small per-IP daily cap — the only endpoint that does.
  • format: png or svg. Optional dark/light colours and a centre logo (multipart).

POST/api/qr/generate/bulk

CSV in, a zip of PNGs out — up to 500 rows.

curl -X POST https://toolbeam.app/api/qr/generate/bulk \
  -H "X-API-Key: pk_your_key" \
  -F "file=@links.csv" --output codes.zip
  • Metered per code, not per request. A rejected batch is fully refunded.

POST/api/qr/codes

Create a dynamic code: a stable short URL you can repoint anytime.

curl -X POST https://toolbeam.app/api/qr/codes \
  -H "X-API-Key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/menu"}'

GET/api/qr/codes/{code}/stats

Scan counts, timestamps, devices and referrers for a dynamic code.

curl https://toolbeam.app/api/qr/codes/abc123/stats -H "X-API-Key: pk_your_key"

Documents (PDF)

Chromium-rendered PDFs from HTML or a URL, plus the PDF toolbox: merge, split, compress, password-protect, unlock, images-to-PDF — and website screenshots from the same browser.

POST/api/html-pdf/render

HTML (or a URL) in, a pixel-perfect PDF out.

curl -X POST https://toolbeam.app/api/html-pdf/render \
  -H "X-API-Key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Invoice #42</h1>", "format": "A4"}' \
  --output invoice.pdf
  • Send html or url, never both. URL mode validates every redirect hop — private addresses are refused.
  • Large documents: POST /html-pdf/render/async returns 202 + a job id; poll /html-pdf/jobs/{id}, download at /jobs/{id}/download.

POST/api/html-pdf/pdf/merge

Combine up to 20 PDFs, in the order the files are sent.

curl -X POST https://toolbeam.app/api/html-pdf/pdf/merge \
  -H "X-API-Key: pk_your_key" \
  -F "files=@a.pdf" -F "files=@b.pdf" --output merged.pdf
  • Author/title metadata from the sources is stripped from the result.

POST/api/html-pdf/pdf/split

Extract pages ("1-3,7,12-") as one PDF, or split into fixed chunks.

curl -X POST https://toolbeam.app/api/html-pdf/pdf/split \
  -H "X-API-Key: pk_your_key" \
  -F "file=@doc.pdf" -F "ranges=1-3,7" --output pages.pdf
  • One output arrives as a bare PDF; several arrive as a zip.
  • Or mode=every with every=5 to break the document into fixed 5-page chunks.

POST/api/html-pdf/pdf/compress

Shrink a PDF by re-encoding its images — never returns a larger file.

curl -X POST https://toolbeam.app/api/html-pdf/pdf/compress \
  -H "X-API-Key: pk_your_key" \
  -F "file=@scan.pdf" -F "level=medium" --output smaller.pdf
  • X-Original-Bytes / X-Compressed-Bytes / X-Images-Reencoded report the honest result.

POST/api/html-pdf/pdf/protect

Encrypt a PDF with AES-256. The password is used once, never stored.

curl -X POST https://toolbeam.app/api/html-pdf/pdf/protect \
  -H "X-API-Key: pk_your_key" \
  -F "file=@doc.pdf" -F "password=correct-horse-battery" --output locked.pdf

POST/api/html-pdf/pdf/unlock

Remove a password you know. The correct password is required — by design.

curl -X POST https://toolbeam.app/api/html-pdf/pdf/unlock \
  -H "X-API-Key: pk_your_key" \
  -F "file=@locked.pdf" -F "password=correct-horse-battery" --output open.pdf

POST/api/html-pdf/images/pdf

Images in (up to 30), one PDF out — one page per image, order preserved.

curl -X POST https://toolbeam.app/api/html-pdf/images/pdf \
  -H "X-API-Key: pk_your_key" \
  -F "files=@page1.jpg" -F "files=@page2.png" --output album.pdf

POST/api/html-pdf/screenshot

A PNG or JPEG of a live URL, rendered in real Chromium.

curl -X POST https://toolbeam.app/api/html-pdf/screenshot \
  -H "X-API-Key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "width": 1280, "full_page": true}' \
  --output page.png
  • Width 320-1920. Private and internal addresses are blocked on every hop.

Images

Format conversion (HEIC, JPG, PNG, WebP, AVIF and more) and compression to a quality or an exact byte target. EXIF — including GPS — is stripped by default.

POST/api/image/convert

Convert one image between formats.

curl -X POST https://toolbeam.app/api/image/convert \
  -H "X-API-Key: pk_your_key" \
  -F "file=@photo.heic" -F "target=jpg" --output photo.jpg

POST/api/image/compress

Shrink an image to a quality, or to an exact size like 100 KB.

curl -X POST https://toolbeam.app/api/image/compress \
  -H "X-API-Key: pk_your_key" \
  -F "file=@photo.jpg" -F "target_kb=100" --output small.jpg
  • Send quality (1-95) or target_kb, not both.
  • X-Fits-Target: false means the target was impossible — you still get the smallest achievable.

POST/api/image/batch

Convert up to 20 images in one request; a zip comes back.

curl -X POST https://toolbeam.app/api/image/batch \
  -H "X-API-Key: pk_your_key" \
  -F "files=@a.heic" -F "files=@b.heic" -F "target=jpg" --output converted.zip
  • Metered per image; undelivered items are refunded.

GET/api/image/formats

The formats this server can actually read and write, probed at startup.

curl https://toolbeam.app/api/image/formats

Photo tools

AI background removal and the tools built on the same mask: product photos, stickers, avatars and passport-style print sheets.

POST/api/bg-remove/remove

Photo in, transparent PNG out.

curl -X POST https://toolbeam.app/api/bg-remove/remove \
  -H "X-API-Key: pk_your_key" \
  -F "file=@portrait.jpg" --output cutout.png
  • Free plan output caps at 1024px on the longest side; paid plans keep full resolution.
  • Batches: POST /bg-remove/remove/async returns a job id, same polling flow as PDF rendering.

POST/api/bg-remove/product-photo

Marketplace-ready cutout on a clean background at a preset size.

curl -X POST https://toolbeam.app/api/bg-remove/product-photo \
  -H "X-API-Key: pk_your_key" \
  -F "file=@item.jpg" -F "preset=amazon" --output listing.jpg
  • GET /bg-remove/presets lists every preset these tools accept.

POST/api/bg-remove/print-sheet

Passport-style photos tiled at true physical size, DPI embedded.

curl -X POST https://toolbeam.app/api/bg-remove/print-sheet \
  -H "X-API-Key: pk_your_key" \
  -F "file=@portrait.jpg" -F "size_key=uk_eu" -F "paper=4x6" --output sheet.jpg

Developer tools

Compare two API responses structurally, or pull one page's metadata — title, description, canonical, OG tags, favicons — with review notes.

POST/api/devtools/compare

Fetch two URLs and diff status, headers, timing and JSON structure.

curl -X POST https://toolbeam.app/api/devtools/compare \
  -H "X-API-Key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"left": {"url": "https://api.example.com/v1/users"},
       "right": {"url": "https://staging.example.com/v1/users"}}'
  • Your Authorization/Cookie headers are dropped the moment a redirect leaves the original origin.

POST/api/devtools/metadata

One URL in, its <head> parsed out, plus SEO review notes.

curl -X POST https://toolbeam.app/api/devtools/metadata \
  -H "X-API-Key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Mock APIs

Create a URL that serves canned JSON — for frontends ahead of their backend, webhooks, and demos. Serving is free and unmetered; a per-mock rate limit bounds it.

POST/api/mock/mocks

Create a mock endpoint; the response names its serving URL.

curl -X POST https://toolbeam.app/api/mock/mocks \
  -H "X-API-Key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "users", "status_code": 200, "body": "{\"users\": []}"}'
  • Mocks serve from mock.toolbeam.app/{token} — a separate origin on purpose, so a mock body can never run beside app sessions.
  • body is a JSON *string* (escaped, as above) and must itself parse as JSON — 64 KB max, no redirects, no Set-Cookie.

GET/api/mock/mocks

List your mocks, with their serving URLs and hit counts.

curl https://toolbeam.app/api/mock/mocks -H "X-API-Key: pk_your_key"

API FAQ

How do I get an API key?
Create a free account, then generate a key from the dashboard. The key is shown once in full — store it then; only its hash is kept.
How do I authenticate requests?
Send the key in an X-API-Key header, or a signed-in session's JWT as Authorization: Bearer. One key works across every service.
What are the rate limits?
Each plan carries monthly per-tool allowances — the dashboard shows what remains. Exceeding one returns 429 with a JSON detail naming the metric; batch endpoints meter per item and refund anything undelivered.
What does an error look like?
JSON, always: {"detail": "a sentence a human can act on"} with a conventional status — 400 for a bad input, 401 unauthenticated, 404 for someone else's resource, 422 for validation, 429 over quota.
Is there an SDK?
Not yet — the APIs are plain HTTP with multipart or JSON bodies, so every language's standard client works. The curl examples translate line for line.

Each endpoint is documented in more depth on its tool's page — try the full tool list, or see pricing for the allowances each plan carries.