API reference
Every operation of the published contract, with a playground and code samples.
The reference is generated from the published contract of the integration API (OpenAPI 3.0) when these pages are built. It shows exactly the operations an API key or a public call can use; the portal's own operations are not part of it (see Stability and versioning).
Basics
| Base URL | https://<your BatteryPass address>/api/v1 (see Environments) |
| Authentication | Authorization: Bearer bp_live_… with scope read, condition or import (Authentication) |
| Format | JSON, times in UTC, ids as UUIDs |
| Errors | RFC 9457 Problem Details with a stable code (Errors) |
| Lists | Keyset pagination with limit and cursor (Pagination) |
| Limits | 429 rate_limited with Retry-After (Rate limits) |
Playground
Every operation page has a playground ("Try in Playground"). It sends the request from your browser to the
BatteryPass instance these docs run on. Your key stays in this tab only (sessionStorage) and is sent without
cookies; use a key with scope read for it.
Download the contract
openapi.jsonandopenapi.yaml: the version these docs were built from./api/v1/openapi.jsonand/api/v1/openapi.yamlon your BatteryPass address: the version your instance serves right now.
All operations
Catalog
| Operation | Request | Scope |
|---|---|---|
| Units (individual batteries) of the active organisation | GET /batteries | read |
| The units as a spreadsheet with the import's columns | GET /batteries/export | read |
| A unit | GET /batteries/{batteryId} | read |
| List the battery models of the active organisation | GET /battery-models | read |
| A battery model | GET /battery-models/{modelId} | read |
| Versions of a battery model, newest effective date first | GET /battery-models/{modelId}/versions | read |
| A model version | GET /model-versions/{versionId} | read |
Values
| Operation | Request | Scope |
|---|---|---|
| Registry evaluation of the unit-level fields | GET /batteries/{batteryId}/completeness | read |
| Current unit-level values of a unit | GET /batteries/{batteryId}/values | read |
| All revisions of one unit-level value, newest first | GET /batteries/{batteryId}/values/{fieldKey}/history | read |
| Registry evaluation of the model-level fields | GET /model-versions/{versionId}/completeness | read |
| Current model-level values of a version | GET /model-versions/{versionId}/values | read |
| All revisions of one model-level value, newest first | GET /model-versions/{versionId}/values/{fieldKey}/history | read |
Evidence
| Operation | Request | Scope |
|---|---|---|
| The evidence library, newest first | GET /evidence | read |
| One document with its revisions and where it is used | GET /evidence/{evidenceId} | read |
| Download the file | GET /evidence/{evidenceId}/download | read |
Passports
| Operation | Request | Scope |
|---|---|---|
| The passport of a unit | GET /batteries/{batteryId}/passport | read |
| The QR code of the unit's GS1 Digital Link | GET /batteries/{batteryId}/passport/qr | read |
| The passport's registration with the EU registry | GET /batteries/{batteryId}/passport/registration | read |
| The published versions of a unit's passport, newest first | GET /batteries/{batteryId}/passport/versions | read |
| One published version with its signed snapshot and validation report | GET /batteries/{batteryId}/passport/versions/{versionNo} | read |
| The BatteryPass v2.0 export of a version (all tiers) | GET /batteries/{batteryId}/passport/versions/{versionNo}/batterypass-v2 | read |
| What changed from an earlier version to this one | GET /batteries/{batteryId}/passport/versions/{versionNo}/diff | read |
| A PDF of a version with every tier, restricted rows tagged, the signature and the QR code | GET /batteries/{batteryId}/passport/versions/{versionNo}/pdf | read |
Lifecycle
| Operation | Request | Scope |
|---|---|---|
| The condition data of a unit (the registry's dynamic fields) | GET /batteries/{batteryId}/condition | read |
| Report measured condition data (merge) | PATCH /batteries/{batteryId}/condition | condition |
| The lifecycle of a unit, newest first | GET /batteries/{batteryId}/lifecycle-events | read |
| Record an event in the life of a unit | POST /batteries/{batteryId}/lifecycle-events | condition |
Registry
| Operation | Request | Scope |
|---|---|---|
| Version, content hash and status of the field registry in use | GET /registry | read |
| The editor schema of a battery category | GET /registry/schema | read |
| The registry in use and how many of the organisation's passports need an update | GET /registry/status | read |
Facilities
| Operation | Request | Scope |
|---|---|---|
| Manufacturing facilities of the active organisation | GET /facilities | read |
Public
| Operation | Request | Scope |
|---|---|---|
| The public passport of a unit, looked up by GTIN and serial number | GET /public/dpps/by-product-id/{productId} | public |
| The public passport (current version) | GET /public/passports/{passportId} | public |
| A public document of a public passport | GET /public/passports/{passportId}/documents/{documentId} | public |
| Check the signatures of a version on the server | GET /public/passports/{passportId}/verify | public |
| The public passport as it was at a point in time | GET /public/passports/{passportId}/version | public |
Changes
| Operation | Request | Scope |
|---|---|---|
| The organisation's changes, oldest first, for polling | GET /changes | read |
Imports
| Operation | Request | Scope |
|---|---|---|
| Imports of the active organisation, newest first | GET /imports | import |
| Upload a spreadsheet of units | POST /imports | import |
| One import with its mapping and summary | GET /imports/{importId} | import |
| Map the columns of an import | PUT /imports/{importId}/mapping | import |
| Start validating every row of an import | POST /imports/{importId}/validate | import |