# 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](https://passport.kabin.sh/docs/en/versioning)).

## Basics

|                |                                                                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL       | `https://<your BatteryPass address>/api/v1` (see [Environments](https://passport.kabin.sh/docs/en/environments))                                  |
| Authentication | `Authorization: Bearer bp_live_…` with scope `read`, `condition` or `import` ([Authentication](https://passport.kabin.sh/docs/en/authentication)) |
| Format         | JSON, times in UTC, ids as UUIDs                                                                                                                    |
| Errors         | RFC 9457 Problem Details with a stable `code` ([Errors](https://passport.kabin.sh/docs/en/errors))                                                |
| Lists          | Keyset pagination with `limit` and `cursor` ([Pagination](https://passport.kabin.sh/docs/en/pagination))                                          |
| Limits         | `429 rate_limited` with `Retry-After` ([Rate limits](https://passport.kabin.sh/docs/en/rate-limits))                                              |

> [!TIP]
> **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.json`](https://passport.kabin.sh/docs/openapi.json) and [`openapi.yaml`](https://passport.kabin.sh/docs/openapi.yaml): the version these docs were
  built from.
- `/api/v1/openapi.json` and `/api/v1/openapi.yaml` on your BatteryPass address: the version your instance
  serves right now.

## All operations

### Catalog

[Units (individual batteries) of the active organisation](https://passport.kabin.sh/docs/en/api-reference/catalog/list-batteries.md): `GET /batteries` (read)

[The units as a spreadsheet with the import's columns](https://passport.kabin.sh/docs/en/api-reference/catalog/export-units.md): `GET /batteries/export` (read)

[A unit](https://passport.kabin.sh/docs/en/api-reference/catalog/get-battery.md): `GET /batteries/{batteryId}` (read)

[List the battery models of the active organisation](https://passport.kabin.sh/docs/en/api-reference/catalog/list-battery-models.md): `GET /battery-models` (read)

[A battery model](https://passport.kabin.sh/docs/en/api-reference/catalog/get-battery-model.md): `GET /battery-models/{modelId}` (read)

[Versions of a battery model, newest effective date first](https://passport.kabin.sh/docs/en/api-reference/catalog/list-model-versions.md): `GET /battery-models/{modelId}/versions` (read)

[A model version](https://passport.kabin.sh/docs/en/api-reference/catalog/get-model-version.md): `GET /model-versions/{versionId}` (read)

### Values

[Registry evaluation of the unit-level fields](https://passport.kabin.sh/docs/en/api-reference/values/get-battery-completeness.md): `GET /batteries/{batteryId}/completeness` (read)

[Current unit-level values of a unit](https://passport.kabin.sh/docs/en/api-reference/values/list-battery-values.md): `GET /batteries/{batteryId}/values` (read)

[All revisions of one unit-level value, newest first](https://passport.kabin.sh/docs/en/api-reference/values/list-battery-value-history.md): `GET /batteries/{batteryId}/values/{fieldKey}/history` (read)

[Registry evaluation of the model-level fields](https://passport.kabin.sh/docs/en/api-reference/values/get-model-version-completeness.md): `GET /model-versions/{versionId}/completeness` (read)

[Current model-level values of a version](https://passport.kabin.sh/docs/en/api-reference/values/list-model-version-values.md): `GET /model-versions/{versionId}/values` (read)

[All revisions of one model-level value, newest first](https://passport.kabin.sh/docs/en/api-reference/values/list-model-version-value-history.md): `GET /model-versions/{versionId}/values/{fieldKey}/history` (read)

### Evidence

[The evidence library, newest first](https://passport.kabin.sh/docs/en/api-reference/evidence/list-evidence.md): `GET /evidence` (read)

[One document with its revisions and where it is used](https://passport.kabin.sh/docs/en/api-reference/evidence/get-evidence.md): `GET /evidence/{evidenceId}` (read)

[Download the file](https://passport.kabin.sh/docs/en/api-reference/evidence/download-evidence.md): `GET /evidence/{evidenceId}/download` (read)

### Passports

[The passport of a unit](https://passport.kabin.sh/docs/en/api-reference/passports/get-passport.md): `GET /batteries/{batteryId}/passport` (read)

[The QR code of the unit's GS1 Digital Link](https://passport.kabin.sh/docs/en/api-reference/passports/get-passport-qr.md): `GET /batteries/{batteryId}/passport/qr` (read)

[The passport's registration with the EU registry](https://passport.kabin.sh/docs/en/api-reference/passports/get-registry-submission-status.md): `GET /batteries/{batteryId}/passport/registration` (read)

[The published versions of a unit's passport, newest first](https://passport.kabin.sh/docs/en/api-reference/passports/list-passport-versions.md): `GET /batteries/{batteryId}/passport/versions` (read)

[One published version with its signed snapshot and validation report](https://passport.kabin.sh/docs/en/api-reference/passports/get-passport-version.md): `GET /batteries/{batteryId}/passport/versions/{versionNo}` (read)

[The BatteryPass v2.0 export of a version (all tiers)](https://passport.kabin.sh/docs/en/api-reference/passports/export-passport-json.md): `GET /batteries/{batteryId}/passport/versions/{versionNo}/batterypass-v2` (read)

[What changed from an earlier version to this one](https://passport.kabin.sh/docs/en/api-reference/passports/get-passport-version-diff.md): `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](https://passport.kabin.sh/docs/en/api-reference/passports/export-passport-pdf.md): `GET /batteries/{batteryId}/passport/versions/{versionNo}/pdf` (read)

### Lifecycle

[The condition data of a unit (the registry's dynamic fields)](https://passport.kabin.sh/docs/en/api-reference/lifecycle/get-condition.md): `GET /batteries/{batteryId}/condition` (read)

[Report measured condition data (merge)](https://passport.kabin.sh/docs/en/api-reference/lifecycle/update-condition.md): `PATCH /batteries/{batteryId}/condition` (condition)

[The lifecycle of a unit, newest first](https://passport.kabin.sh/docs/en/api-reference/lifecycle/list-lifecycle-events.md): `GET /batteries/{batteryId}/lifecycle-events` (read)

[Record an event in the life of a unit](https://passport.kabin.sh/docs/en/api-reference/lifecycle/create-lifecycle-event.md): `POST /batteries/{batteryId}/lifecycle-events` (condition)

### Registry

[Version, content hash and status of the field registry in use](https://passport.kabin.sh/docs/en/api-reference/registry/get-registry-info.md): `GET /registry` (read)

[The editor schema of a battery category](https://passport.kabin.sh/docs/en/api-reference/registry/get-registry-schema.md): `GET /registry/schema` (read)

[The registry in use and how many of the organisation's passports need an update](https://passport.kabin.sh/docs/en/api-reference/registry/get-registry-status.md): `GET /registry/status` (read)

### Facilities

[Manufacturing facilities of the active organisation](https://passport.kabin.sh/docs/en/api-reference/facilities/list-facilities.md): `GET /facilities` (read)

### Public

[The public passport of a unit, looked up by GTIN and serial number](https://passport.kabin.sh/docs/en/api-reference/public/get-public-passport-by-product-id.md): `GET /public/dpps/by-product-id/{productId}` (public)

[The public passport (current version)](https://passport.kabin.sh/docs/en/api-reference/public/get-public-passport.md): `GET /public/passports/{passportId}` (public)

[A public document of a public passport](https://passport.kabin.sh/docs/en/api-reference/public/download-public-passport-document.md): `GET /public/passports/{passportId}/documents/{documentId}` (public)

[Check the signatures of a version on the server](https://passport.kabin.sh/docs/en/api-reference/public/verify-passport.md): `GET /public/passports/{passportId}/verify` (public)

[The public passport as it was at a point in time](https://passport.kabin.sh/docs/en/api-reference/public/get-public-passport-version.md): `GET /public/passports/{passportId}/version` (public)

### Changes

[The organisation's changes, oldest first, for polling](https://passport.kabin.sh/docs/en/api-reference/changes/list-changes.md): `GET /changes` (read)

### Imports

[Imports of the active organisation, newest first](https://passport.kabin.sh/docs/en/api-reference/imports/list-imports.md): `GET /imports` (import)

[Upload a spreadsheet of units](https://passport.kabin.sh/docs/en/api-reference/imports/create-import.md): `POST /imports` (import)

[One import with its mapping and summary](https://passport.kabin.sh/docs/en/api-reference/imports/get-import.md): `GET /imports/{importId}` (import)

[Map the columns of an import](https://passport.kabin.sh/docs/en/api-reference/imports/update-import-mapping.md): `PUT /imports/{importId}/mapping` (import)

[Start validating every row of an import](https://passport.kabin.sh/docs/en/api-reference/imports/validate-import.md): `POST /imports/{importId}/validate` (import)