Reference

Twin API

Read the normalized twin and everything derived from it — pack health, rider projections, and station forecasts. All endpoints are read-only and tenant-scoped.

Overview

The Twin API is how your apps consume Rootd. It never mutates batteries or runs operations — it returns the twin and the intelligence on top of it, for your systems to act on.

Base URL: https://api.rootd.io/v1. All responses are JSON. All reads are audited.

Auth & tenancy

Authenticate with a bearer token and pass your tenant on every request. The tenant header scopes the entire query — there is no cross-tenant read path.

authenticated request

01curl https://api.rootd.io/v1/twins/PK-0421 \
02  -H "Authorization: Bearer $ROOTD_TOKEN" \
03  -H "X-Rootd-Tenant: northwind"

Scoped by construction. A token bound to one tenant cannot read another's twins, even with a valid pack_id.

Get a twin

GET/v1/twins/{pack_id}

Field	Type	Description
connectivity	enum	Modeled state: `online` · `stale` · `offline`.
state_of_health	number	SoH percentage, derived from charge/discharge history.
est_state_of_charge	number	Estimated SoC, computed on read from SoH + latest reading. Not a stored field.
cycle_count	number	Reported cycle count from the BMS.
last_reading	string	Timestamp of the latest ingested reading (UTC).

SoC is derived. Treat est_state_of_charge as guidance that moves with the latest reading — never as a peer of state_of_health.

List packs

GET/v1/twins?status=online&sort=sohpaginated

Field	Type	Description
status	enum	Filter by connectivity state.
sort	string	`soh`, `last_reading`, or `pack_id`.
cursor	string	Opaque pagination cursor from the previous page.

Rider projection

GET/v1/riders/{id}/projection

Returns a suggested swap window that minimizes travel plus wait. This is a recommendation — your app decides whether and how to surface it.

Field	Type	Description
suggested_window	object	`start` / `end` times for the recommended swap.
station	string	Recommended station for the window.
est_wait_min	number	Estimated queue wait at the suggested window.
friction_saved_min	number	Modeled minutes saved vs. an unplanned swap.

Station forecast

GET/v1/stations/{id}/forecast?horizon=24h

Projects charged-pack supply against demand per station, and counts forecast dry-station events under the current plan.

forecast response

01GET /v1/stations/kawangware_hub/forecast?horizon=24h
02{
03  "station": "kawangware_hub",
04  "series": [
05    { "t": "+0h", "supply": 82, "demand": 22 },
06    { "t": "+17h", "supply": 94, "demand": 82 }
07  ],
08  "dry_risk_events": 0
09}