Stellantis Data Treatment System API

openapi: 3.0.0
servers:
  - url: 'https://server/api/connectedcar/v1'
info:
  version: '1.0'
  title: Stellantis Connected Car API
  description: >
    *Connected Car API*
    
   
    # Introduction

    This is the description of the *Stellantis Connected Car V2 API*. The
    speccification is  is based on **OpenAPI Specification version 3** and can be displayed using [ReDoc](https://github.com/Rebilly/ReDoc)a or
    [Swagger](http://swagger.io).
    
    
      This API allows applications to fetch data from the Connected Vehicles Data Platform. It is designed to be **a declarative data and function specification**, so they are understood and consumed by stakeholders without knowledge of manufacturer onboard vehicle specification
    
    ---
    
    # API features
    
    
     ## Vehicles:
      <i>Access to static vehicle resources such as brand, description and images as well as the IoT data.</i>
    ##  Trips:
      <i>Access to the trips traveled by the vehicle and their data such as telemetry, alerts and waypoints, etc.</i>
     ## Channel:
     <i> Definition of an output channel that can be used as a return channel for the Monitor and Remote functions or as an output for the datastream.</i>
     ## Monitor:
      <i>Creating a monitor with several flags that define a logical expression that is the exact functional condition for triggering the monitor. It is also possible to define the actions (remote action or monitor changes) to invoke when receiving a particular monitor event. Thus, it can be possible to automate scenarios.</i>
     ## Remote:
      <i>Send the remote command to the vehicle. It is also possible to define the actions (remote action or monitor changes) to invoke when receiving a particular remote event callback status. Thus, it can be possible to automate scenarios.</i>
    ##  Datastream:
      <i>Create output data streams on a defined channel. Data sent on this stream are the same as that exposed by the APIs.</i>
      
      ---
      
    
    # API Authentication
    
      Stellantis Connected Car APIs uses the [OAuth  2.0](https://tools.ietf.org/html/rfc6749) protocol for authentication and
      authorization. Any application require a valid [Access Token](https://tools.ietf.org/html/rfc6749#section-1.4) to access to data.
     
      
            
      ## Hierarchical Scopes

    
      Since api resources are hierarchical, API uses also hierarchical scopes. 
        _Colon characters_ are used to navigate to subresource scopes.
    
    
      ## Filtering Scopes
    
      - When the API caller requests a set of scopes. The owner may not grant access to all of the requested scopes, so the application will have to adapt to the restricted access or request for a larger set of scopes again.
      - API backend will deliver the data related to the granted scopes only. 
      - If no scope has been granted with the caller token then an unauthorized error will be returned.
          
        _If for example the API caller requests for "aggregated telemetry" or "trip" without having the "location" scope, then the resource data returned will not have the vehicle's position but only other data that will satisfy the scopes present in the token._
          
      **The scopes used to request access to resources for the OAuth2 security scheme fall into four categories:**

      #### _1. <u>IoT data scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|
      |vehicle| read Vehicle attributes (details) data|
      |telemetry| read full telemetry data|
      |telemetry:environment|read telemetry environment data|
      |telemetry:privacy|read telemetry privacy data|
      |telemetry:vehicle|read full telemetry vehicle data|
      |telemetry:vehicle:ignition|read telemetry vehicle ignition data|
      |telemetry:vehicle:preconditioning|read telemetry vehicle preconditioning system data|
      |telemetry:vehicle:energies|read telemetry vehicle all energies data:<i> level, autonomy, consumptions, eletric residual, eletric battery state, eletric charging state</i>|
      |telemetry:vehicle:engines|read telemetry vehicle all engines data:<i> speed, gmp, extensions (thermal: oil, src...)</i>|
      |telemetry:vehicle:doorsState|read telemetry vehicle doors state data|
      |telemetry:vehicle:battery|read telemetry vehicle status battery data|
      |telemetry:vehicle:safety|read telemetry vehicle safety (Seat belt, ecall ..) data|
      |telemetry:vehicle:odometer|read telemetry vehicle odometer data|
      |telemetry:vehicle:kinetic|read telemetry vehicle kinetic data|
      |telemetry:vehicle:propulsion|read telemetry vehicle propulsion mode|
      |telemetry:vehicle:brakingSystem|read telemetry vehicle braking system data|
      |telemetry:vehicle:transmission|read telemetry vehicle transmission data|
      |telemetry:vehicle:adas|read telemetry vehicle ADAS data|
      |telemetry:vehicle:lighting|read telemetry vehicle lighting system data|
      |telemetry:vehicle:maintenance |read telemetry vehicle maintenance data|
      |telemetry:vehicle:drivingBehavior|read telemetry driver behavior data|
      |location| read vehicle  Location (position) data|
      |trip| read Trip related data|
      |alert| read alert related data|
      |collision| read Collision related data|
      #### _2. <u>Notification channel scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|       
      |channel| read calback related data|
      |channel:<b>write</b>| create, modify or delete channels|
      #### _3. <u>Vehicle monitor scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|       
      |monitor| read monitors|
      |monitor:<b>write</b>| create, modify or delete Monitors|
      #### _4. <u>Datastream scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|       
      |datastream| read exisiting datastream (subscribed, status...) setting|
      |datastream:<b>write</b>| create, modify or delete datastreams|
      #### _5. <u>Vehicle remotes scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|            
      |remote| read full remote state(pending & history)|
      |remote:door:lock| read door Lock remote (pending & history)|      
      |remote:door:lock:<b>write</b>| send a door Lock remote to vehicle|
      |remote:door:unlock| read door Lock remote (pending & history)| 
      |remote:door:unlock:<b>write</b>| send a door Unlocked remote to vehicle|
      |remote:preconditioning| read door Lock remote (pending & history)| 
      |remote:preconditioning:<b>write</b>| send a precondioning remote to vehicle|
      |remote:horn| read horn remote  (pending & history)| 
      |remote:horn:<b>write</b>| send a horn remote to vehicle|
      |remote:immo| read immobilization remote (pending & history)| 
      |remote:immo:<b>write</b>| send an immobilization remote to vehicle|
      |remote:charging| read charging remote (pending & history)| 
      |remote:charging:<b>write</b>| send charging remote to vehicle|
      |remote:stolen| read stolen-set remote (pending & history)| 
      |remote:stolen:<b>write</b>| send remote to set vehicle as stolen|
      |remote:lights| read lights remote (pending & history)| 
      |remote:lights:<b>write</b>| send remote to switch on/off vehicle lights|
      |remote:weakup| read weackup remote (pending & history)| 
      |remote:weakup:<b>write</b>| send remote to weackup vehicle|
      |remote:navigation| read navigation remote (pending & history)| 
      |remote:navigation:<b>write</b>| send navigation remote to vehicle|    
    
    ---
    
    # API Navigability:
      These APIs use [HATEOAS]([https://en.wikipedia.org/wiki/HATEOAS#Implementations) as standard convention for defining resources discovery and navifability (thanks to related hyperlinks).
      Adopting HAL simplifies the use of open source libraries and make it possible to interact with the API using JSON.
    ---          
    
    # API Paging:
    
    To make this necessary feature easy to use when retrieving a collection of results, this API uses a token (computed and interpreted by the backend only) as a context that contains all necessary information allowing the navigation through pages. 
      Token acts as an ```HTTP COOKIE``` on the client-side, so the server does not keep any cache or session settings to continue paging and keep all request stateless. These tokens are used to build HAL (Hypertext Application Language) hyperlinks also.
          
    ---
    
    # API Errors:
      Error codes returned by all APIs comply with the standard. Nevertheless, PSA Services (callers) need to have more detailed data structures (even when the answer is not Http-OK) to better categorize the type of error by providing application code, message and debugging code(for investigation purposes). The HTTP code of the response is managed by the protocol itself (in the header).
        
      ### These APIS are likely to report the following HTTP code:
      
      |<b>Code</b>  |<b>Description</b>  | <b>Case</b> | 
      |---|---|---|
      |200  |<i>The request has succeeded and the resource data has been sent.</i>|GET APIs.  |
      |202  |<i>The request has been accepted for processing, but not yet acted upon. An id of processing is returned.</i>|POST/PUT requests:<br>-Create monitor<br>-Create a callbak.| 
      |204  |<i>The request has been accepted and there is no additional content</i>|DELTE APIs:<br>-Delete monitor.<br>-Delete a channel.|
      |400|<i>Request cannot be processed due to invalid query parameter value of body content (for POST/PUT verbs)</i>|ALL APIs.|
      |401|<i>Unauthorized request due to lack of valid authentication credentials.</i>|All APIs.|
      |403|<i>Unauthorized request due to insufficient credentials to grant access.</i>|All APIs.|
      |404|<i>Target resource not found.|All APIs. Even POST, PUT or DELETE if the resource id is uncknown.</i>|
      |500|<i>Unexpected condition that prevented from fulfilling the reques.</i>|All APIs.|


      
      **Errors are  returned as a generic error response:**
       * See ```ErrorCodeDefaultResponse``` model.
       
    ---
    
    # API output:
     
      ## Data format
      
      **All APIs return data in JSON format. The application who uses them must take into account the evolving character of them and more precisely regarding the schemas of the exposed data. Indeed:**
      
      *  The missing of known data fields should not cause an error. 
      *  It should (correctly)  deal with JSON content with unknown properties also. Indeed, data schema extensions should be supported without errors even if they are not used. 
        
      
      **for example:**
      
      Assuming a given exposed resource with this data schema:
        
          
           data:
            type: object
            description: Data model
            properties:
              field1:
                type: string
              field2:
                type: number
             
      The application should be able to deal with those possible valid JSON contents:
        
      > All fields:
        ```{
          "field1":"value1",
          "field2": 1
        }```
        
      > Missing field2:
        ```{
          "field1":"value1"
        }```        

      > Unknow  field3:
        ```{
          "field1":"value1",
          "field3": 2.5
        }```
      
     
    ---     
    
    
    
  license:
    name: Stellantis Licence
    url: 'https://www.psa-peugeot-citroen.com/'
  
tags:
  - name: Vehicles
    description: Access to attributes and IoT data associated with the vehicle.
  - name: Trips
    description: Describe Trips of a vehicle.
  - name: Channels
    description: Describe a subscription to an output channel for remote or monitor notification events or data-stream features.
  - name: Grouping
    description: Allows to organize the vehicles (of the owner) by group(s) according to functional criteria. Groups allow collective action on a set of vehicles, such as subscription to a monitor or a data stream (*remote remains applicable to the vehicle individually*)
  - name: Monitors
    description: Describe the vehicle monitor features.
  - name: Remotes
    description: Describe the vehicle remote features.


# --- truncated at 32 KB (208 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stellantis/refs/heads/main/openapi/_original/stellantis-data-treatment-system-openapi.yml