Developer documentation

BatteryComply API

A small, deliberately boring HTTP API for two things: auditing battery-product PDFs against EU Regulation (EU) 2023/1542, and issuing Digital Battery Passports under Article 77 / Annex XIII. Designed to be called by humans, AI agents, and ERP / customs-broker platforms with equal ease.

Quick links

OpenAPI 3.1 spec

Quick start

Submit a single PDF, get back a structured compliance verdict. No account or API key required during the Stage 6a preview.

curl -X POST https://batterycomply-api.onrender.com/api/v1/check \
  -F "file=@my-doc.pdf" \
  -F "lang=en"

The response is the same gated shape returned by the website — verdict, counts, and a localized teaser. Full checks[] and recommended_actions[] arrive once Stage 6b API keys + per-call metering ship.

Base URL: https://batterycomply-api.onrender.com
Content type: multipart/form-data for uploads, application/json for everything else.
Languages: lang accepts en, da, no, sv, de (also nl, fr for error messages). Defaults to en.

Endpoints

POST /api/v1/check

Run the ten-check compliance audit. Pass a single PDF (DoC, technical file, spec sheet, or test report). Returns the gated shape with verdict, issue counts, and localized teaser. Methodology and Article citations: /how-we-audit.

POST /api/v1/passport/build

Extract Annex XIII data from a battery technical file and return a passport ID, completeness ratio, and a QR-encoded resolver URL (ISO/IEC 18004) suitable for printing on the battery label. Categories covered: LMT, industrial > 2 kWh, EV. Out-of-scope categories return out_of_scope: true with a localized reason.

GET /api/v1/passport/{id}

Fetch a stored Battery Passport. Returns the gated shape (counts + teaser, no Annex XIII values) until unlocked. Once unlocked, returns full JSON-LD plus the raw extraction envelope with per-field confidence and provenance.

GET /api/v1/passport/{id}/resolve

Public passport resolver — this is what battery QR codes point at. Always returns the public-tier projection (Part B legitimate-interest + Part C authorities-only fields stripped) regardless of unlock state, so QR scanners always resolve to a valid passport. Send Accept: application/ld+json for the JSON-LD; default returns a small JSON envelope pointing browsers at the localized viewer.

Response shapes

Audit verdict (gated)

{
  "report_id": "f7b1...",
  "filename": "my-doc.pdf",
  "lang": "en",
  "verdict": "CONDITIONAL",
  "summary": "Six checks pass; UN 38.3 summary missing.",
  "issue_count": 3,
  "critical_count": 1,
  "important_count": 2,
  "info_count": 0,
  "teaser": "1 critical issue would likely cause customs rejection.",
  "is_unlocked": false
}

Passport (gated, on build)

{
  "passport_id": "9d2e...",
  "filename": "battery-tech-file.pdf",
  "lang": "en",
  "category": "INDUSTRIAL_GT_2KWH",
  "out_of_scope": false,
  "completeness_ratio": 0.92,
  "completeness_filled": 23,
  "completeness_total": 25,
  "teaser": "23 of 25 Annex XIII fields populated. 2 fields need attention.",
  "is_unlocked": false
}

Authentication

None during the Stage 6a preview. Please be polite — at most a few requests per minute per IP. Stage 6b will introduce Authorization: Bearer bcsk_… API keys, per-call metering, and free-tier quotas. Email info@batterycomply.com if you need higher early-access limits or want to reserve an API key for an integration you're shipping.

Pricing

Free during preview. The website self-serve pricing — €149 for an audit unlock, €289 for a Battery Passport unlock — applies when fetching a stored result via the website's pretty URLs (/r/{id}, /p/{id}). API-call pricing for v1 will be metered per call and announced before Stage 6b ships.

Errors

Status	When	Body shape
`400`	Non-PDF upload, oversized file (> 20 MB), corrupt or password-protected PDF	`{"detail": "…"}` (localized via `?lang=`)
`404`	Unknown `report_id` / `passport_id`	`{"detail": "Report not found"}`
`422`	Missing required form fields (`file`)	FastAPI validation envelope
`500`	Upstream extractor failure or DB write error	`{"detail": "Analysis error…"}`

Integration notes

GPT Actions / Claude tool use

Point your action manifest at /openapi.json. We don't ship a /.well-known/ai-plugin.json — the ChatGPT Plugins format was sunset in April 2024 and modern action runtimes consume OpenAPI directly.

MCP

No MCP server is hosted yet. Once SEP-1649 / SEP-1960 stabilise, the public passport resolver will be exposed as an MCP tool so any MCP-aware agent can scan a QR-derived ID and pull the JSON-LD.

llms.txt

Our llms.txt follows the llmstxt.org convention. Crawlers can pick up the API surface from there without scraping the marketing pages.