CellIQ
Docs
Base API: http://localhost:8000/api

CellIQ API & Platform Documentation

Everything you need to integrate with CellIQ: authentication, vehicles, reports, dealer workflows, and public verification links.

Overview

CellIQ generates Annex XIII–aligned Battery Condition Reports (BCR) from EV telemetry data. Owners and dealers can connect vehicles, sync readings, and generate reports. Buyers and insurers can verify a report via a public link.

Roles
  • Owner: connect personal vehicles, generate reports.
  • Dealer: manage fleets, credits, exports, seller invites.
Environments

For local dev the API defaults to http://localhost:8000/api. Configure via NEXT_PUBLIC_API_URL.

Authentication

CellIQ uses JWT access tokens (short-lived) and refresh tokens (long-lived). Most API endpoints require an Authorization: Bearer <access_token> header.

Email/password login
POST /api/auth/login

{ "email": "user@example.com", "password": "••••••••" }
Refresh tokens
POST /api/auth/refresh

{ "refresh_token": "<refresh_token>" }
Google OAuth

Google OAuth supports both login and first-time registration. You can pass role intent:

GET /api/auth/google?role=owner
GET /api/auth/google?role=dealer

Callback:
GET /api/auth/google/callback?code=...&state=...

Vehicles API

Connect vehicles via Smartcar, list connected vehicles, trigger manual sync, or disconnect.

GET /api/vehicles/connect
→ { "auth_url": "https://connect.smartcar.com/..." }
GET /api/vehicles
POST /api/vehicles/{vehicle_id}/sync
DELETE /api/vehicles/{vehicle_id}

Reports API

Validate whether a vehicle has enough data, then generate a report (owner or dealer).

GET /api/reports/validate?vehicle_id={vehicle_id}
POST /api/reports/generate

{ "vehicle_id": "<vehicle_id>", "report_type": "owner" }
{ "vehicle_id": "<vehicle_id>", "report_type": "dealer" }

If a payment is required, the API can respond with 402 and a checkout URL.

Dealer API

Dealer endpoints provide fleet workflows: vehicles listing, reports listing/export, settings, and seller invites.

GET /api/dealer/vehicles?page=1&page_size=50&search=tesla&status=active
→ { items: [...], total, page, page_size }
GET /api/dealer/reports?...
GET /api/dealer/reports/export?...
POST /api/dealer/vehicles/invite

{ "vin": "WVW...", "seller_email": "seller@example.com" }

Payments & webhooks

CellIQ uses Stripe Checkout for subscriptions/credits and webhooks to keep state in sync.

POST /api/payments/create-checkout
POST /api/payments/webhook
GET /api/payments/subscription
GET /api/payments/portal

Public verification

Public verification is intended for buyers and insurers. It does not require authentication.

GET /api/reports/public/{token}
Web: https://celliq.eu/verify/{token}

Errors & status codes

Errors follow standard HTTP semantics.

401 Unauthorized — missing/invalid token
403 Forbidden — role does not have access
404 Not Found — resource missing
422 Unprocessable Entity — validation/insufficient data
402 Payment Required — checkout_url may be provided
500 Internal Server Error — unexpected

Examples

Quick examples using curl. Replace tokens and IDs with your own.

List vehicles
curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "http://localhost:8000/api/vehicles"
Validate report
curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "http://localhost:8000/api/reports/validate?vehicle_id=$VEHICLE_ID"
Generate dealer report
curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\"vehicle_id\":\"'$VEHICLE_ID'\",\"report_type\":\"dealer\"}' \
  "http://localhost:8000/api/reports/generate"