Docs

Rootd is a multi-tenant battery-intelligence layer. Send it BMS telemetry from any vendor; read back a normalized digital twin, forecasts, and recommendations. This is the place to start.

What Rootd is

Rootd sits on top of the swap networks other people run. It ingests raw Battery Management System (BMS) telemetry, normalizes it into a vendor-neutral digital twin, and turns that into operational decisions for three readers: operators, riders, and financiers.

Rootd owns no hardware, operates no fleets, and does not replace your BMS or swap app. Everything below is read APIs and projections your own systems consume.

Core concepts

The digital twin

A twin is intelligence derived from telemetry — not a second device and nothing you install. It exists because the data does, and carries state-of-health, connectivity, cycles, and a derived estimate of charge.

Tenancy

Every object belongs to a tenant. Every query is tenant-scoped at the boundary — there is no supported path that reads across tenants. You pass your tenant context on every call.

Connectivity states

Connectivity is modeled as online, stale, or offline — never an error. When a feed drops, the twin holds last-known state and surfaces its freshness.

Estimated state-of-charge

SoC is computed on read from state-of-health and the latest reading. It is always labeled est_state_of_charge and is never stored as an independent peer of SoH.

Quickstart

Two calls get you from raw frames to a usable twin.

1. Send a reading. Point any BMS feed at the ingest endpoint — Rootd normalizes units and timing for you.

01POST /v1/ingest/readings
02{
03  "tenant": "northwind",
04  "pack_id": "PK-0421",
05  "vendor": "vendor_a",
06  "ts": "2026-06-03T08:14:02Z",
07  "metrics": { "voltage_mv": 53120, "temp_c": 31 }
08}

2. Read the twin. Once normalized, the pack is available as a twin you can query.

01GET /v1/twins/PK-0421
02{
03  "pack_id": "PK-0421",
04  "connectivity": "online",        // modeled state
05  "state_of_health": 90.4,
06  "est_state_of_charge": 64,    // derived from SoH + latest reading
07  "last_reading": "2026-06-03T08:14:02Z"
08}

Where to next

• Ingest reference — transports, payload schema, and freshness rules.
• Twin API — read twins, list packs, forecasts, and rider projections.
• Security — how tenant isolation and audited reads work.
• Glossary — canonical definitions of every domain term.