REST API Reference

Start the server:

tesla serve                 # http://localhost:8000
tesla serve --port 9000     # custom port
tesla serve --host 0.0.0.0  # bind to all interfaces
tesla serve --reload        # dev mode (auto-reload on file changes)

Requires the serve extra: uv tool install -e ".[serve]"

Authentication

tesla config set server.api_key MY_SECRET_KEY

Once set, all /api/ requests require X-Api-Key: MY_SECRET_KEY header.

Also supports: ?api_key= query param, TESLA_API_KEY env var.

Multi-Vehicle

All /api/vehicle/ and /api/charge/ routes accept ?vin= to target a specific vehicle:

GET /api/vehicle/data?vin=5YJ3E1EA...
GET /api/charge/state?vin=modely           # aliases work too

Endpoints

System

Method	Endpoint	Description
GET	`/api/health`	Liveness probe (Docker HEALTHCHECK, Kubernetes)
GET	`/api/status`	Version, backend, default VIN
GET	`/api/vehicles`	All configured vehicles (aliases + default)
GET	`/api/config`	Full config summary
GET	`/api/config/validate`	Config health check (same logic as `tesla config validate`)
GET	`/api/providers`	Provider registry status
GET	`/api/providers/capabilities`	Capability map per provider
GET	`/api/metrics`	Prometheus text-format metrics (27 gauges)
GET	`/api/docs`	Swagger UI (auto-generated by FastAPI)

Vehicle

Method	Endpoint	Description
GET	`/api/vehicle/data`	Full vehicle state snapshot
GET	`/api/vehicle/summary`	Compact snapshot (battery, climate, location, state)
GET	`/api/vehicle/ready`	Morning check: ready to drive? (issues list)
GET	`/api/vehicle/status-line`	Ultra-compact for widgets (battery, lock, sentry, temp)
GET	`/api/vehicle/last-seen`	Online/asleep state + last contact time
GET	`/api/vehicle/alerts`	Recent fault codes and warnings
GET	`/api/vehicle/stream`	Server-Sent Events live stream
POST	`/api/vehicle/wake`	Wake vehicle
POST	`/api/vehicle/command/{cmd}`	Send arbitrary vehicle command

Charge

Method	Endpoint	Description
GET	`/api/charge/state`	Charge state
GET	`/api/charge/history`	Charging history (Fleet API) — total kWh, per-session data, breakdown
GET	`/api/charge/sessions`	Unified sessions (TeslaMate > Fleet API) with cost tracking
GET	`/api/charge/last`	Most recent charging session with cost
GET	`/api/charge/weekly`	Weekly charging summary (kWh, cost, sessions per week)
POST	`/api/charge/start`	Start charging
POST	`/api/charge/stop`	Stop charging
POST	`/api/charge/set-limit`	Set charge limit (%)
POST	`/api/charge/set-amps`	Set charge current (A)

Climate

Method	Endpoint	Description
GET	`/api/climate/state`	Climate state
POST	`/api/climate/on`	Turn on climate
POST	`/api/climate/off`	Turn off climate

Security

Method	Endpoint	Description
POST	`/api/security/lock`	Lock doors
POST	`/api/security/unlock`	Unlock doors
GET	`/api/security/sentry`	Sentry mode status
POST	`/api/security/sentry/on`	Enable sentry mode
POST	`/api/security/sentry/off`	Disable sentry mode
POST	`/api/security/trunk/front`	Open frunk
POST	`/api/security/trunk/rear`	Toggle trunk
POST	`/api/security/horn`	Honk horn
POST	`/api/security/flash`	Flash lights

Notifications

Method	Endpoint	Description
GET	`/api/notify/list`	List configured channels
POST	`/api/notify/test`	Send test notification
POST	`/api/notify/add`	Add channel (`{"url": "tgram://..."}`)
POST	`/api/notify/remove`	Remove channel by index (`{"index": 0}`)

Vehicle (Sub-State)

These endpoints return individual state objects without waking the vehicle when already awake:

Method	Endpoint	Description
GET	`/api/vehicle/state`	Full vehicle data (all states combined)
GET	`/api/vehicle/location`	Drive state including GPS coordinates
GET	`/api/vehicle/charge`	Charge state sub-object
GET	`/api/vehicle/climate`	Climate state sub-object
GET	`/api/vehicle/vehicle-state`	Vehicle state (locks, doors, software, etc.)
GET	`/api/vehicle/list`	List all vehicles on the account
GET	`/api/vehicle/odometer`	Current odometer + software version (`{vin, odometer_miles, car_version, queried_at}`)

Order

Method	Endpoint	Description
GET	`/api/order/status`	Order status

Dossier

Method	Endpoint	Description
GET	`/api/dossier`	Cached dossier (fast, from disk)
GET	`/api/dossier/refresh`	Rebuild dossier from all sources (slow, 30-60s)
GET	`/api/dossier/sources`	List all 15 data sources with cache status
GET	`/api/dossier/runt`	Live RUNT query (Colombia vehicle registry)
GET	`/api/dossier/simit`	Live SIMIT query (Colombia traffic fines)

TeslaMate

Method	Endpoint	Description
GET	`/api/teslaMate/status`	Lifetime stats
GET	`/api/teslaMate/trips`	Recent trips
GET	`/api/teslaMate/charging`	Recent charging sessions
GET	`/api/teslaMate/timeline`	Unified event timeline (`?days=N`)
GET	`/api/teslaMate/cost-report`	Monthly cost breakdown (`?month=YYYY-MM`, `?limit=N`)
GET	`/api/teslaMate/trip-stats`	Trip summary + top routes (`?days=N`)
GET	`/api/teslaMate/charging-locations`	Top charging locations
GET	`/api/teslaMate/stats`	Lifetime driving + charging stats
GET	`/api/teslaMate/efficiency`	Per-trip energy efficiency
GET	`/api/teslaMate/heatmap`	Drive days calendar
GET	`/api/teslaMate/vampire`	Vampire drain analysis
GET	`/api/teslaMate/daily-energy`	Daily kWh chart
GET	`/api/teslaMate/report/{month}`	Monthly summary report
GET	`/api/teslaMate/battery-degradation`	Battery degradation trend from high-SoC charges (`?months=N`)

TeslaMate Stack (Managed)

Method	Endpoint	Description
GET	`/api/stack/status`	Container status
POST	`/api/stack/start`	Start TeslaMate stack
POST	`/api/stack/stop`	Stop TeslaMate stack
POST	`/api/stack/restart`	Restart stack
POST	`/api/stack/update`	Update containers
GET	`/api/stack/logs`	Container logs

Geofences

Method	Endpoint	Description
GET	`/api/geofences`	List all zones with vehicle distance + inside flag
GET	`/api/geofences/{name}`	Check if vehicle is inside a specific zone
POST	`/api/geofences/{name}`	Add/update a zone (`{"lat", "lon", "radius_km"}`)
DELETE	`/api/geofences/{name}`	Remove a zone

Sources

Data source cache management — mirrors tesla data data-sources and related commands:

Method	Endpoint	Description
GET	`/api/sources`	List all 15 data sources with cache status
GET	`/api/sources/missing-auth`	List sources that lack required credentials
GET	`/api/sources/config`	Current source configuration
POST	`/api/sources/config`	Update source configuration
POST	`/api/sources/refresh-stale`	Refresh all stale cached sources
GET	`/api/sources/{source_id}`	Single source detail + cached value
POST	`/api/sources/{source_id}/refresh`	Force refresh a specific source
GET	`/api/sources/{source_id}/history`	Cache history for a source
GET	`/api/sources/{source_id}/diffs`	Structured diff log for a source
GET	`/api/sources/{source_id}/queries`	Query audit trail: consulted source/mode plus normalized response/error
GET	`/api/sources/{source_id}/audits`	Audit log entries for a source
GET	`/api/sources/{source_id}/audit/{filename}`	Single audit file content

Domains

Derived semantic views computed from cached sources:

Method	Endpoint	Description
GET	`/api/domains`	List all computed domain projections
GET	`/api/domains/{domain_id}`	Single domain projection
POST	`/api/domains/{domain_id}/recompute`	Recompute and persist a domain

Mission Control

Derived executive read model built from sources + domains:

Method	Endpoint	Description
GET	`/api/mission-control`	Executive Mission Control payload with domains, sources, critical diffs, and timeline
GET	`/api/mission-control/dashboard-summary`	Compact Mission Control executive summary

Events

Persistent source/domain event stream:

Method	Endpoint	Description
GET	`/api/events`	List recent source/domain events

Alerts

Persistent alert stream derived from source/domain events:

Method	Endpoint	Description
GET	`/api/alerts`	List recent alerts (`active_only=true` by default)
POST	`/api/alerts/{alert_id}/ack`	Acknowledge an alert without resolving it

Auth

OAuth2 / Fleet API authentication flow (used by the PWA dashboard):

Method	Endpoint	Description
GET	`/api/auth/login`	Generate Tesla OAuth URL (`{auth_url, state}`) — open in popup
POST	`/api/auth/callback`	Exchange authorization code for tokens (`{code, state}`)
POST	`/api/auth/tessie`	Configure Tessie API token (`{token}`)
POST	`/api/auth/browser-login`	Initiate browser-based login flow
POST	`/api/auth/portal-scrape`	Scrape Tesla portal session cookies
GET	`/api/auth/status`	Auth status for all configured backends

Colombia (Public Data)

Method	Endpoint	Description
GET	`/api/co/pico-y-placa`	Driving restrictions by plate
GET	`/api/co/estaciones-ev`	EV charging stations
GET	`/api/co/fasecolda`	Vehicle commercial value
GET	`/api/co/recalls-sic`	SIC recalls
GET	`/api/co/peajes`	Toll rates

SSE Stream

# All data
curl -N http://localhost:8000/api/vehicle/stream

# Fine-grained topics (comma-separated)
curl -N "http://localhost:8000/api/vehicle/stream?topics=battery,location,geofence"

# Fan-out to push providers (ABRP + HA + MQTT)
curl -N "http://localhost:8000/api/vehicle/stream?fanout=true"

Topic events: vehicle (always), battery, climate, drive, location, geofence.

Geofence events are typed: enter/exit with zone name, computed via haversine distance.

The browser dashboard connects via EventSource with automatic exponential backoff reconnect (1s -> 2s -> 4s ... max 30s).

Prometheus Metrics

GET /api/metrics

Returns text/plain; version=0.0.4 with 11 gauges labeled by VIN:

tesla_battery_level, tesla_battery_range, tesla_charge_limit
tesla_charger_power, tesla_energy_added
tesla_odometer, tesla_speed
tesla_latitude, tesla_longitude
tesla_locked, tesla_sentry_mode

Web Dashboard

Navigate to http://localhost:8000 for a mobile-friendly dashboard:

Real-time battery ring gauge with charging animation
Climate, drive, location cards
Geofence zone overlay on location
VIN switcher for multi-vehicle households
Dark/light theme toggle (persisted in localStorage)
Config health badge in footer
PWA-ready (installable via manifest + service worker)
SSE reconnect with exponential backoff

Development

make ui          # start Vite dev server (proxies to FastAPI)
make api         # start FastAPI with --reload
make dev         # run both together (:8080 API + :5173 UI)
make serve       # build UI + run production server

During local UI development:

Open http://localhost:5173
API requests to /api/* are proxied automatically to http://localhost:8080
No localStorage API URL override is needed in dev

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

REST API Reference

Authentication

Multi-Vehicle

Endpoints

System

Vehicle

Charge

Climate

Security

Notifications

Vehicle (Sub-State)

Order

Dossier

TeslaMate

TeslaMate Stack (Managed)

Geofences

Sources

Domains

Mission Control

Events

Alerts

Auth

Colombia (Public Data)

SSE Stream

Prometheus Metrics

Web Dashboard

Development

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

REST API Reference

Authentication

Multi-Vehicle

Endpoints

System

Vehicle

Charge

Climate

Security

Notifications

Vehicle (Sub-State)

Order

Dossier

TeslaMate

TeslaMate Stack (Managed)

Geofences

Sources

Domains

Mission Control

Events

Alerts

Auth

Colombia (Public Data)

SSE Stream

Prometheus Metrics

Web Dashboard

Development