Ingest reference

Send BMS and GPS telemetry from any vendor to one endpoint. This page is the contract: how you authenticate, the vendor-neutral generic_json payload, batching, limits, and every response code. For a device already speaking a binary dialect, see the protocol catalog.

Overview

Ingest is the one-way door for raw readings. Every reading enters through a single endpoint, POST /v1/ingest/{protocol}, where the {protocol} path segment selects the codec that decodes your wire format. The simplest path is generic_json, a vendor-neutral JSON shape any backend can produce, and it is what this page documents in full. Devices that already speak a binary dialect (JT/T 808, GT06, Modbus, OCPP, …) post their native bytes to the same endpoint; the protocol catalog lists all eleven.

Writes are idempotent on (tenant, device, timestamp): a replayed frame is a no-op, so a device can retry freely after a connectivity gap without double-counting.

Authentication

Ingest requires a bearer token that carries the ingest role. You mint one from a normal operator session: two calls, then you're sending data. You can also create one in the dashboard under Settings → API tokens.

1. Log in to obtain a session token (skip this if you already have a dashboard session):

01# 1: Log in once to get a session token (or copy your dashboard session).
02curl -X POST https://api.rootd.cc/v1/auth/login \
03  -H "Content-Type: application/json" \
04  -d '{"email":"you@operator.com","password":"••••••••"}'
05# → { "token": "<SESSION_TOKEN>", "user": { "tenant": "...", "roles": [...] } }

2. Mint an ingest token. Machine-to-machine tokens always carry the ingest role on top of your account's roles, scoped to your tenant. Hand this token to the device or gateway that pushes telemetry, not your login password.

01# 2: Mint a long-lived ingest token. It carries the `ingest` role and is
02# bound to your tenant. Treat it as a device secret. (Dashboard: Settings →
03# API tokens does the same thing.)
04curl -X POST https://api.rootd.cc/v1/settings/tokens \
05  -H "Authorization: Bearer $SESSION_TOKEN" \
06  -H "Content-Type: application/json" \
07  -d '{"scopes":[],"ttlHours":720}'
08# → { "token": "<INGEST_TOKEN>" }

The endpoint

Base URL: https://api.rootd.cc. Send the native payload as the raw request body: a JSON document for generic_json and ocpp, or raw protocol bytes for the binary codecs.

generic_json schema

A generic_json payload is one object, or a JSON array of objects. Each object describes one device at one instant. Optional numeric fields are omitted when absent: a GPS-only ping carries no voltage; a battery-only ping carries no coordinates.

01# 3: Push a reading. Tenant comes from the token, never the body.
02curl -X POST https://api.rootd.cc/v1/ingest/generic_json \
03  -H "Authorization: Bearer $INGEST_TOKEN" \
04  -H "Content-Type: application/json" \
05  -d '{"device":"BIKE-001","timestamp":"2026-06-24T09:00:00Z",
06       "v":63.2,"i":-4.5,"temp":29,"soc":0.71}'
07# → 202 { "acceptedReadings": 1, "acceptedLocations": 0 }

Batches & limits

To send many readings in one request, post a JSON array instead of a single object:

01# Send many at once: post a JSON array. Each element is one message.
02curl -X POST https://api.rootd.cc/v1/ingest/generic_json \
03  -H "Authorization: Bearer $INGEST_TOKEN" \
04  -H "Content-Type: application/json" \
05  -d '[{"device":"BIKE-001","timestamp":"2026-06-24T09:00:00Z","v":63.2,"i":-4.5,"temp":29,"soc":0.71},
06       {"device":"BIKE-002","timestamp":"2026-06-24T09:00:05Z","v":61.8,"i":2.0,"temp":33,"soc":0.40,
07        "lat":-1.286,"lon":36.817,"speed":18}]'
08# → 202 { "acceptedReadings": 2, "acceptedLocations": 1 }

Responses & errors

A successful POST returns 202 Accepted with the counts decoded from the payload. The whole request is atomic per message: the first invalid reading rejects the request and dead-letters the offending payload for inspection, so nothing is silently dropped.

01{ "acceptedReadings": 2, "acceptedLocations": 1 }

Errors return a JSON body naming the reason, the protocol, and the offending field:

01{
02  "error": "reading_out_of_bounds",
03  "protocol": "generic_json",
04  "field": "temperature"
05}

Connectivity & freshness

Rootd models connectivity from the gap between now and a battery's latest reading. A dropped feed is a state, never an error or a deleted twin:

Where to next

• Protocols: the eleven codecs (telematics, BMS/bus, charging) and a curl example for each binary dialect.
• Twin API: read the twin back to confirm your readings landed, then consume health, forecasts, and rider projections.
• Security: how tenant isolation and audited reads work.
• Talk to us: to provision a tenant or add a protocol.