API Reference v1
Full endpoint list for both CrateAPI products: curl examples, responses, authentication, limits.
Prefer raw OpenAPI? The machine-readable spec and Swagger UI live at api.crateapi.com/docs →
Getting started
Three steps to your first API call.
Get your free key
A free API key is available instantly, right here on the site — no card required. Paid plans open at launch: join the list for 20% off.
Send your key
One header on every request: X-Api-Key. No OAuth dance, no SDK required.
Ship documents
Plain HTTP + JSON/XML in, results out. The docs show a working curl for every endpoint.
or let your AI agent call it — MCP server →
Authentication
E-invoicing base URL: https://api.crateapi.com/v1. Document tools base URL: https://api.crateapi.com (paths /pdf, /screenshot, /email, /extract).
Send your key as X-API-Key: <your key>. Need a free key? Get one instantly at crateapi.com/account/ - no signup form, just your email.
Endpoints marked free need no key at all - that's deliberate, not a trial: validation stays free forever.
curl -X POST https://api.crateapi.com/v1/validate/ubl \ -H "Content-Type: application/xml" \ --data-binary @invoice.xml {"profile":"peppol","valid":true,"counts":{"fatal":0,"warning":0},"findings":[],"duration_ms":12}
curl -X POST https://api.crateapi.com/v1/generate/ubl?profile=peppol \ -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \ -d @invoice.json -o invoice.xml
E-Invoicing API
EN 16931: UBL/Peppol BIS, CII, Factur-X, FatturaPA (Italy: TD01/TD04/TD05 invoices and credit/debit notes, Natura codes incl. forfettario), Facturae (Spain: public-sector invoices), FA_VAT/KSeF (Poland) and Order-X (purchase orders). Full OpenAPI spec: /openapi.json · interactive docs: /docs (Swagger UI).
| Endpoint | Auth | Notes |
|---|---|---|
POST /v1/validate/ubl | free | Validate a UBL invoice. `profile` defaults to `peppol`; pass `profile=auto` to auto-detect from the document's CustomizationID (falls back to en16931), or choose explicitly: en16931, peppol, xrechnung, ro, fr, fr-extended, ehf, nlcius, pint. |
POST /v1/validate/cii | free | Validate a CII invoice. `profile` defaults to `en16931`; pass `profile=auto` to auto-detect from the document's CustomizationID (falls back to en16931), or choose explicitly: en16931, xrechnung, fr, fr-extended. |
POST /v1/validate/facturapa | free | FatturaPA XSD-structural validation only (no official schematron ruleset exists to vendor). |
POST /v1/validate/orderx | free | Order-X Basic - full XSD + official schematron validation. |
POST /v1/pdfa/validate | free | PDF/A validation (veraPDF). `flavour`: auto|1a|1b|2a|2b|2u|3a|3b|3u|4|4e|4f. |
GET /validator | free | In-browser drag-and-drop validator, same engine, no signup. |
POST /v1/generate/ubl | needs X-API-Key | JSON invoice model → UBL XML. `profile`: en16931, peppol, xrechnung, ro, ehf, nlcius, pint. |
POST /v1/generate/cii | needs X-API-Key | JSON invoice model → CII XML. `profile`: en16931, xrechnung. |
POST /v1/generate/facturx | needs X-API-Key | Our minimal visual PDF + embedded CII XML (EN16931). |
POST /v1/generate/facturx/embed | needs X-API-Key | Your branded PDF + invoice JSON → PDF/A-3 with embedded CII (multipart). |
POST /v1/generate/facturapa | needs X-API-Key | Italy FatturaPA XML: TD01 invoices, TD04/TD05 credit/debit notes, Natura VAT-exemption codes (incl. forfettario N2.2), optional ritenuta/bollo/cassa. |
POST /v1/generate/orderx | needs X-API-Key | Order-X Basic purchase order XML (not an invoice). |
POST /v1/convert/ubl-to-cii | needs X-API-Key | Lossless-or-rejected: 422 with details rather than a silent degrade. |
POST /v1/convert/cii-to-ubl | needs X-API-Key | Same guarantee, other direction. |
POST /v1/render/html | needs X-API-Key | Invoice XML → human-readable HTML (official KoSIT visualization). |
POST /v1/render/pdf | needs X-API-Key | Invoice XML → PDF. `style`: compact (default, 1-page) or kosit (audit form). |
POST /v1/pdfa/convert | needs X-API-Key | Any PDF → PDF/A-3b, with optional embedded files. |
POST /v1/pdfa/consistency | needs X-API-Key | Factur-X: does the embedded XML agree with the PDF's visible text? |
POST /v1/repair/ubl | needs X-API-Key | Best-effort auto-repair: non-ISO dates, totals arithmetic drift. |
POST /v1/repair/cii | needs X-API-Key | Same, CII syntax. |
Document Tools API
PDF, screenshot, email validation, content extraction. Auth: the free key from crateapi.com/account/ covers the E-Invoicing API — Document Tools plans open at launch, join the launch list. Per-API specs: /pdf/openapi.json, /screenshot/openapi.json, /email/openapi.json, /extract/openapi.json.
| API | Endpoint | Notes |
|---|---|---|
POST /pdf/merge | Combine 2+ PDFs, in upload order. | |
POST /pdf/split | Extract pages, e.g. `pages=1-3,5`. | |
POST /pdf/watermark | Diagonal text overlay - `text`, `opacity`, `color`, `font_size`. | |
POST /pdf/protect | AES-256 password encryption. | |
POST /pdf/compress | Ghostscript recompression - `level`: low|medium|high; never returns a bigger file than the input. | |
POST /pdf/from-html | Raw HTML → PDF (headless Chromium). | |
POST /pdf/from-url | Public URL → PDF, same anti-SSRF guard as /screenshot. | |
POST /pdf/to-images | Pages → PNG/JPEG, returned as a ZIP. | |
POST /pdf/extract-text | Layout-aware text extraction (poppler, pypdf fallback). | |
POST /pdf/metadata | Page count, encryption flag, document info fields. | |
| screenshot | GET /screenshot/take | URL → PNG/JPEG. `block_ads`, `block_trackers`, `block_cookie_banners`, `cache_ttl`, `full_page`, `delay_ms`. |
GET /email/validate | Syntax + MX + disposable + role-account + free-provider signals, with a score. | |
POST /email/validate-batch | Up to 100 addresses, JSON body. | |
POST /email/validate-bulk | CSV upload, up to 5,000 addresses; `format=json` or `format=csv` (results appended). | |
| extract | GET /extract/article | URL → clean article text + metadata, boilerplate removed. |
| extract | POST /extract-html | Raw HTML → clean text (no fetch). |
Limits
E-invoicing: XML body capped at 2 MB, PDF uploads at 10 MB. Monthly quota per key (calibrated per plan, generous default - see pricing) applies to every endpoint except /validate/* and /pdfa/validate, which stay unmetered.
Document tools: these figures describe the plans opening at launch (100 requests/month on the free plan, up to 50,000/month on Ultra - see pricing). No Document Tools API key exists yet - try every tool live in your browser at /products/ today, and join the list to get a key when it opens. Bulk email validation caps at 5,000 addresses / 2 MB per upload.
MCP server (AI agents)
Hosted at https://api.crateapi.com/mcp (streamable HTTP) - add the URL straight to your MCP client's config, nothing to run:
{"mcpServers": {"crateapi-einvoicing": { "type": "http", "url": "https://api.crateapi.com/mcp", "headers": {"X-API-Key": "your-key-here"}}}}
validate_invoice needs no key; the other three read the X-API-Key header. Validating without a key is fair-use rate-limited per IP, same as the free validator on this site.
Prefer to self-host - for privacy, air-gapped environments, or local dev? Same tools, run as your own process:
{"mcpServers": {"crateapi-einvoicing": { "command": "python", "args": ["-m", "einvoicing.mcp_server"], "env": {"EINVOICE_API_KEY": "your-key-here"}}}}
Tools: validate_invoice (free), repair_invoice, generate_invoice, convert_invoice. Full write-up: /mcp/. Machine-readable summary of this whole page: /llms.txt · /ai (JSON).
Endpoint paths, curl examples, parameter and profile names, and JSON payloads stay in English throughout - copy-pasteable code shouldn't need translating.