Record lifecycle events

A lifecycle event records that something happened to a battery: it was put into service, inspected, repaired, a component was replaced. Events are records: they change none of the unit's data. Measured values go through updateCondition. Background: Condition data and lifecycle.

Event typesCopy Anchor Link

The contract's ReportedEventType also lists condition_update, but createLifecycleEvent refuses it with 400 validation_error on type: those events are written by updateCondition. The second-life types (repurposed, reused, remanufactured) appear in the lifecycle when a member creates a second-life unit in the portal; they cannot be recorded through the API.

Record an eventCopy Anchor Link

curl -sS -X POST "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/lifecycle-events" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inspection",
    "occurred_on": "2026-10-22",
    "description": "Annual inspection: housing, connectors and BMS log checked, no findings.",
    "evidence_ids": ["0192f7aa-1c2d-7e3f-8a4b-5c6d7e8f9a0b"]
  }'

{
  "id": "0192f8c2-4d5e-7f60-8a71-b2c3d4e5f6a7",
  "battery_id": "0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f",
  "type": "inspection",
  "occurred_on": "2026-10-22",
  "description": "Annual inspection: housing, connectors and BMS log checked, no findings.",
  "source": "api",
  "api_key": { "id": "0192e4c7-8b9a-7c6d-8e5f-4a3b2c1d0e9f", "name": "Service system North" },
  "field_keys": [],
  "evidence": [
    {
      "id": "0192f7aa-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
      "kind": "diagnostic_report",
      "title": "Inspection report 2026",
      "filename": "inspection-2026-10-22.pdf",
      "access_tier": "internal",
      "revision": 1,
      "superseded": false
    }
  ],
  "created_at": "2026-10-24T08:15:02Z"
}

No automatic de-duplicationCopy Anchor Link

BatteryPass does not recognise the same event sent twice: every successful request adds an event, and createLifecycleEvent takes no idempotency key. That matters when a request times out and you do not know whether it arrived:

• Do not resend a POST automatically after a network error, a timeout or a 5xx.
• Before you send it again, look for your event (same type, occurred_on and description, source: api) in listLifecycleEvents. The list is ordered by occurred_on, newest first, so a backdated event is not necessarily on the first page: read on with next_cursor until the page holds events that occurred before yours (the retry sample does exactly that).
• Keep the returned id in your system, so you know which events are already recorded.

A 429 rate_limited is safe to resend after Retry-After: the request was refused before anything was stored. More in Retries and idempotency.

Read the lifecycleCopy Anchor Link

curl -sS "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/lifecycle-events?limit=50" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY"

The answer is a page {items, next_cursor}, newest occurred_on first; follow next_cursor for older events (Pagination). The list holds every event of the unit, whoever reported it: members, service partners through their links, condition updates (type: condition_update with the updated field_keys), keys and the system. For a second life, related_battery_id and related_serial_number name the other unit.

ErrorsCopy Anchor Link