API Documentation

Tellus BFF Mock v0.21.0 — 50 endpoints · 29 implemented · 0 stubs · 21 not yet built

Response Envelope: All API responses use { "code": 0, "message": "success", "data": {...} } (↗ envelope spec). Auth endpoints require a Bearer token (24h, no refresh).
Implemented 29
Needs Implementation 0
All 50
Charger Side
/v1/device/* — Traffic from the Twin simulation engine
POST /v1/device/register ↗ spec IMPLEMENTED Register a new charger

Request Body

{
  "sn": "ACME-COV-001",
  "model": "TP-AC22",
  "manufacturer": "Tellus Power",
  "firmware_version": "1.5.0"
}

Response

{
  "code": 0, "message": "success",
  "data": { "device_id": "uuid", "device_secret": "hex64", "expires_in": 86400 }
}
POST /v1/device/token ↗ spec IMPLEMENTED Exchange credentials for bearer token

Request Body

{
  "device_id": "uuid",
  "device_secret": "hex64",
  "grant_type": "client_credentials"
}

Response

{ "access_token": "hex64", "token_type": "Bearer", "expires_in": 86400 }
POST /v1/device/heartbeat IMPLEMENTED Bearer 30s heartbeat

Request Body

{ "timestamp": "2026-05-10T14:00:00Z", "status": "online" }

Response

{ "code": 0, "data": { "commands": [] } }
POST /v1/device/telemetry ↗ spec IMPLEMENTED Bearer Real-time telemetry (5s during sessions)

Request Body

{
  "timestamp": "...", "connector_id": 1, "state": "charging",
  "voltage": 400, "current": 450, "power": 180, "energy_delivered": 1.5, "soc": 42
}

Response

{ "code": 0, "data": null }
POST /v1/device/events IMPLEMENTED Bearer Lifecycle events (plug-in, plug-out, start, stop)

Request Body

{ "timestamp": "...", "event_type": "plug_in", "connector_id": 1, "data": {} }

Response

{ "code": 0, "data": null }
POST /v1/device/charging-records IMPLEMENTED Bearer CDR upload after session

Request Body

{
  "record_id": "uuid", "connector_id": 1, "start_time": "...", "end_time": "...",
  "energy": 12.5, "max_power": 180, "cost": 4.38, "currency": "GBP",
  "stop_reason": "soc_target_reached"
}

Response

{ "code": 0, "data": null }
GET /v1/device/commands IMPLEMENTED Bearer Long-poll for pending commands

Response

{ "code": 0, "data": { "command_id": "uuid", "command": "start_charging", ... } }
POST /v1/device/command-status IMPLEMENTED Bearer Report command execution result

Request Body

{ "command_id": "uuid", "status": "completed", "timestamp": "..." }

Response

{ "code": 0, "data": null }
POST /v1/device/site IMPLEMENTED Register site with associated devices (Acme extension)

Request Body

{
  "site_id": "uuid", "name": "...", "address": "...", "postcode": "...",
  "lat": 52.42, "lng": -1.50, "power_capacity": 176, "device_ids": ["uuid1", ...]
}

Response

{ "code": 0, "data": { "site_id": "uuid" } }
POST /v1/device/firmware/status ↗ spec IMPLEMENTED Bearer Firmware upgrade progress (fields: firmware_version, status, optional progress, message)

Request Body

{ "firmware_version": "2.2.0", "status": "downloading", "progress": 45, "message": "Downloading..." }

Response

{ "code": 0, "message": "success", "data": null }
Tellus Console Surface
Flat /v1/* paths — Traffic from the Tellus Console and operator-side consumers

Core Endpoints

GET /v1/health IMPLEMENTED Health check + version

Response

{ "status": "ok", "timestamp": "...", "version": "0.8.0" }
GET /v1/operators IMPLEMENTED List operators visible to authenticated user

Response

{ "code": 0, "data": [{ "id": "acme-charging-uk", "name": "Acme Charging Network UK", "country": "GB", "status": "active" }] }
GET /v1/operators/:id IMPLEMENTED Get operator by ID

Response

{ "code": 0, "data": { "id": "acme-charging-uk", "name": "Acme Charging Network UK", "country": "GB", "status": "active" } }
GET /v1/sites IMPLEMENTED List sites with live status

Response

{
  "code": 0, "data": {
    "items": [{ "site_id": "uuid", "name": "...", "location": { "lat": 52.42, "lng": -1.50 },
      "total_connectors": 4, "status_summary": { "idle": 3, "charging": 1, "fault": 0 },
      "power_capacity": 176, "created_at": "..." }],
    "total": 3
  }
}
GET /v1/sites/:id IMPLEMENTED Single site detail
GET /v1/devices IMPLEMENTED List devices with connectors

Response

{
  "code": 0, "data": {
    "items": [{ "device_id": "uuid", "sn": "ACME-COV-001", "model": "TP-AC22",
      "status": "online", "connectors": [...], "site_id": "uuid" }],
    "total": 11
  }
}
GET /v1/devices/:id IMPLEMENTED Single device detail
GET /v1/devices/:id/connectors IMPLEMENTED Device connector states

Response

{
  "code": 0, "data": {
    "items": [{ "connector_id": 1, "status": "charging", "power": 180, "soc": 42 }],
    "total": 2
  }
}
GET /v1/charging-records IMPLEMENTED Query charging records (paginated)

Response

{ "code": 0, "data": { "items": [...], "total": 15, "page": 1, "size": 20 } }
GET /v1/charging-records/:id IMPLEMENTED Individual CDR lookup
GET /v1/aggregated/energy IMPLEMENTED Energy time-series aggregation

Response

{
  "code": 0, "data": {
    "granularity": "hour", "series": [...],
    "total": { "charge_energy": 45.2, "discharge_energy": 9.1, "max_power": 360 }
  }
}
GET /v1/commands/:id IMPLEMENTED Command execution status
POST /v1/devices/:id/connectors/:cid/start IMPLEMENTED Remote start charging

Request Body

{ "charge_power": 180, "target_soc": 80 }

Response

{ "code": 0, "data": { "command_id": "uuid", "status": "queued" } }
POST /v1/devices/:id/connectors/:cid/stop IMPLEMENTED Remote stop charging

Request Body

{ "reason": "user_request" }

Response

{ "code": 0, "data": { "command_id": "uuid", "status": "queued" } }
POST /v1/devices/:id/connectors/:cid/discharge IMPLEMENTED Remote V2G discharge

Request Body

{ "discharge_power": 180, "duration": 300, "min_soc": 20 }

Response

{ "code": 0, "data": { "command_id": "uuid", "status": "queued" } }
POST /v1/devices/:id/connectors/:cid/schedule NOT IMPL Set charging schedule
POST /v1/oauth/token NOT IMPL Operator OAuth token
POST /v1/control/flexibility NOT IMPL Site-scope load/flex control
WS /stream ↗ spec IMPLEMENTED Real-time telemetry WebSocket (see /websockets for probe info)

Response

{ "device_id": "uuid", "timestamp": "...", "connectors": [{ "connector_id": 1, "state": "charging", "power": 180, "soc": 42 }] }
GET /v1/firmware/versions IMPLEMENTED Firmware adoption catalogue (operator-side, Acme extension; envelope shape: data.items + data.summary)

Response

{
  "code": 0, "message": "success",
  "data": {
    "items": [{ "model": "TP-AC22", "manufacturer": "Tellus Power",
      "latest_version": "260122.1606", "total_devices": 5, "on_latest": 5,
      "adoption_percentage": 100, "versions": [{ "version": "260122.1606", "count": 5 }] }],
    "total": 3, "page": 1, "size": 3,
    "summary": { "total_devices": 15, "on_latest": 15, "adoption_percentage": 100 }
  }
}
GET /v1/configuration/profiles NOT IMPL Device configuration profiles
GET /v1/models NOT IMPL Charger model catalogue

Intelligence (501 — Not Available)

GET /v1/intelligence/health-scores NOT IMPL Device health scores
GET /v1/intelligence/anomalies NOT IMPL Anomaly detection
GET /v1/intelligence/forecasts/energy NOT IMPL Energy forecasts
GET /v1/intelligence/forecasts/utilization NOT IMPL Utilization forecasts
GET /v1/intelligence/daily-briefing NOT IMPL Daily briefing
GET /v1/intelligence/agents NOT IMPL AI agent list
POST /v1/intelligence/ask NOT IMPL AI co-pilot query
Other
Legacy and internal endpoints

Legacy Operator-to-Operator (OpenAPI only)

PUT /customer/query_station_info NOT IMPL Query charger list
PUT /customer/notification_stationStatus NOT IMPL Notify status change
PUT /cp/query_station_status NOT IMPL Batch status query
POST /cp/start_charging NOT IMPL Start charging (legacy)
POST /cp/stop_charging NOT IMPL Stop charging (legacy)
POST /cp/start_discharging NOT IMPL Start V2G (legacy)
POST /cp/stop_discharging NOT IMPL Stop V2G (legacy)
POST /customer/notify_work_status NOT IMPL Push work status

Internal / Debug (Acme-only)

GET /v1/internal/activity IMPLEMENTED Live traffic feed (JSON)
GET /v1/debug/requests IMPLEMENTED Request log ring buffer (200 entries)
POST /admin/queue-command NOT IMPL Manual command injection
Powered by Simtricity