Skip to main content
API docs by Redocly

Public API (1.0.0)

Download OpenAPI specification:Download

Platform Engineering: platform@example.com

The Public API is the user-facing interface for external client requests. It enforces OAuth2/JWT authentication with DPoP (Demonstrating Proof-of-Possession, RFC 9449) via the OAuth2Bearer security scheme, applies rate limiting, CORS policies, and standard security headers on all responses. Authenticated endpoints require both a DPoP-bound access token and a fresh DPoP proof JWT signed with the client's private key. The API provides access to the Metadata Catalog (public, no authentication required), Vehicle Data, Charger Data, and Diagnostics endpoints.

Authentication

OAuth2 authentication

Authorize

Initiate the OAuth2 authorization code flow. Redirects the user to the login page. Supports PKCE (code_challenge, code_challenge_method).

query Parameters
response_type
required
string
Value: "code"

Must be "code" for authorization code flow.

client_id
required
string

OAuth2 client identifier.

redirect_uri
required
string <uri>

URI to redirect to after authorization.

scope
string

Space-separated list of requested scopes.

state
string

Opaque state value for CSRF protection.

code_challenge
string

PKCE code challenge (S256 recommended).

code_challenge_method
string
Enum: "S256" "plain"

PKCE code challenge method.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_grant",
  • "error_description": "Invalid authorization code"
}

Request Token

Request an OAuth2 access token. Supports authorization_code, client_credentials, and refresh_token grant types. For DPoP-bound tokens, include a DPoP proof JWT in the DPoP header.

header Parameters
DPoP
string

DPoP proof JWT for binding the access token to the client's key pair.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Enum: "authorization_code" "client_credentials" "refresh_token"

OAuth2 grant type.

client_id
required
string

OAuth2 client identifier.

client_secret
string

Client secret (for confidential clients).

code
string

Authorization code (for authorization_code grant).

redirect_uri
string <uri>

Redirect URI (must match the authorization request).

refresh_token
string

Refresh token (for refresh_token grant).

scope
string

Space-separated list of requested scopes.

code_verifier
string

PKCE code verifier (for authorization_code with PKCE).

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "DPoP",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "scope": "string"
}

Health

Platform health monitoring

Health

Health check that returns the status of all backend services. This endpoint is publicly accessible and does not require authentication. Returns 200 if all services are healthy, 503 if one or more services are unhealthy.

Responses

Response samples

Content type
application/json
{
  • "status": "UP",
  • "services": {
    }
}

Metadata Catalog

Signal category and signal field discovery

List Categories

List all signal categories. This endpoint is publicly accessible and does not require authentication.

query Parameters
name
string

Filter categories by name (partial match).

vin
string = 17 characters

Filter categories to those available for a specific vehicle.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Category Signals

List signals for a specific category. This endpoint is publicly accessible and does not require authentication.

path Parameters
categoryId
required
string

Kebab-case category identifier.

query Parameters
page
integer >= 0
Default: 0
Examples: page=0

Zero-based page index for paginated results.

size
integer [ 1 .. 100 ]
Default: 20
Examples: size=20

Number of items per page.

sort
Array of strings
Examples: sort=createdAt,desc

Sort criteria in the format field,direction (e.g., createdAt,desc). Multiple sort criteria can be provided.

vin
string = 17 characters

Filter signals to those available for a specific vehicle.

streamable
boolean

Filter signals by streamable status.

dataType
string

Filter signals by data type.

name
string

Filter signals by name (partial match).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

List Signals

List all signals across all categories. This endpoint is publicly accessible and does not require authentication.

query Parameters
page
integer >= 0
Default: 0
Examples: page=0

Zero-based page index for paginated results.

size
integer [ 1 .. 100 ]
Default: 20
Examples: size=20

Number of items per page.

sort
Array of strings
Examples: sort=createdAt,desc

Sort criteria in the format field,direction (e.g., createdAt,desc). Multiple sort criteria can be provided.

vin
string = 17 characters

Filter signals to those available for a specific vehicle.

category
string

Filter signals by category identifier.

streamable
boolean

Filter signals by streamable status.

dataType
string

Filter signals by data type.

name
string

Filter signals by name (partial match).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Vehicle Data

Vehicle details, status, alerts, journeys, location, and EV data

Vehicle Details

Retrieve vehicle details and capabilities.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "Vehicle": {
    }
}

Vehicle Status

Retrieve real-time vehicle status.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "Vehicle": {
    },
  • "timestamp": "2024-06-15T14:30:00Z"
}

Vehicle Alerts

Retrieve vehicle alerts.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

query Parameters
page
integer >= 0
Default: 0
Examples: page=0

Zero-based page index for paginated results.

size
integer [ 1 .. 100 ]
Default: 20
Examples: size=20

Number of items per page.

sort
Array of strings
Examples: sort=createdAt,desc

Sort criteria in the format field,direction (e.g., createdAt,desc). Multiple sort criteria can be provided.

severity
string
Enum: "info" "warning" "critical"

Filter alerts by severity level.

active
boolean

Filter by active status.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Vehicle Journeys

Retrieve vehicle journey history.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

query Parameters
page
integer >= 0
Default: 0
Examples: page=0

Zero-based page index for paginated results.

size
integer [ 1 .. 100 ]
Default: 20
Examples: size=20

Number of items per page.

sort
Array of strings
Examples: sort=createdAt,desc

Sort criteria in the format field,direction (e.g., createdAt,desc). Multiple sort criteria can be provided.

from
string <date-time>

Filter journeys starting from this date-time (inclusive).

to
string <date-time>

Filter journeys up to this date-time (inclusive).

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Vehicle Location

Retrieve current vehicle location.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "Vehicle": {
    },
  • "timestamp": "2024-06-15T14:30:00Z"
}

Electric Vehicle Data

Retrieve electric vehicle data.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "Vehicle": {
    },
  • "timestamp": "2024-06-15T14:30:00Z"
}

High Voltage Battery

Retrieve high voltage battery telemetry.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "Vehicle": {
    },
  • "timestamp": "2024-06-15T14:30:00Z"
}

Charger Data

Wall charger details and status

Charger Details

Retrieve wall charger details and status.

Authorizations:
OAuth2Bearer
path Parameters
chargerId
required
string <uuid> <= 36 characters

Unique identifier of the wall charger.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "chargerId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
  • "serialNumber": "WC-2024-00142",
  • "model": "JLR Home Charger Pro",
  • "manufacturer": "JLR Energy",
  • "firmwareVersion": "2.4.1",
  • "status": "online",
  • "maxPower": {
    },
  • "currentPower": {
    },
  • "connectorType": "type-2",
  • "energyDelivered": {
    },
  • "connectedVehicleVin": "SALGA2BN6PH123456",
  • "networkStatus": "connected",
  • "lastUpdated": "2024-06-15T14:30:00Z"
}

Diagnostics

Vehicle diagnostic trouble codes and maintenance indicators

Vehicle Diagnostics

Retrieve vehicle diagnostic data including trouble codes, maintenance indicators, and overall health status.

Authorizations:
OAuth2Bearer
path Parameters
vin
required
string = 17 characters

Vehicle Identification Number.

header Parameters
DPoP
required
string
Examples: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiR0VUIiwiaHR1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvcGFja2FnZXMiLCJpYXQiOjE3MDUzMTI2MDB9.signature

DPoP proof JWT (RFC 9449).

Responses

Response samples

Content type
application/json
{
  • "vin": "SALGA2BN6PH123456",
  • "troubleCodes": [
    ],
  • "maintenanceIndicators": [
    ],
  • "overallHealth": "attention-required",
  • "lastUpdated": "2024-06-15T14:30:00Z"
}