> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctechnology.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get vehicle profile
> Gets the given vehicle's profile. This consists of user-defined settings and profile information, as well as information about the hardware that is installed on the vehicle and its configuration.
## OpenAPI
````yaml api-reference/openapi.yml get /vehicle/{vehicle_id}
openapi: 3.0.3
info:
version: v2.2.0
title: c.technology vehicle REST API v2.2.0
description: >
## Introduction
The c.technology vehicle REST API provides the ability to programmatically
manage
and interact with the full range of c.technology products and services.
This documentation is auto-generated from our
[OpenAPI](https://www.openapis.org)
specification, which you can download
[by clicking here](https://docs.ctechnology.io/ctechnology-openapi.yml).
You can use this specification for example to automatically generate
libraries
in your favorite programming language.
In case you are using a JS / TS-compatible system, you can use our official
TypeScript
c.technology app builder SDK that essentially provides a reactive Redux
store out
of the box that features automatic loading from the c.technology backend as
well
as real-time updates on changes.
Concerning the latter, note that many endpoints are also available via the
c.technology
real-time (RT) API that can be found under docs.ctechnology.io/rt.
## Examples & inspirations
You can find many examples under
docs.ctechnology.io/code-examples or on the
[c.technology GitHub organization](https://github.com/c-technology).
## Versioning
The c.technology API is versioned, where the version identifier is part of
the URL:
`https://api.ctechnology.io/v2.2/...`. To make api requests, you do not have
to specify the
patch version (i.e., `v2.2` suffices, `v2.2.0` is not required), as the API
is backwards-compatible
between patch versions. Currently, the most up-do-date version is `v2.2.0`.
## Access and authentication
Most of our endpoints either require using a personal access token or a
programmatic / organizational
access token (that can be created from your admin panel and whose
permissions can
be managed from there). You can request a personal access token via the
login endpoint.
The access tokens must be sent as part of the HTTP `Authorization` header in
the
following form: `Authorization: Token {your_token}`, where you should
replace
`your_token` with the token you received after logging in or after creating
a
programmatic access.
Currently, we do not support OpenID, OAuth or similar login / access
schemes,
nor two-factor authentication.
## Requests
All requests must be made over HTTPS, if you use HTTP you will automatically
be
redirected to the respective HTTPS endpoint. We follow the general
convention
of HTTP RESTful endpoints:
| Method |
Usage
|
| -------------
|:---------------------------------------------------------------------------------------------------------|
| GET | Retrieve data about (collections of) resources.
Idempotent. |
| POST | Create new resources (on collection endpoints). Perform
operations/actions (on ops endpoints). |
| PUT | Modify existing
resources.
|
| DELETE | Delete existing resources. Depending on the endpoint, this
might also simply set a deleted flag to true. |
In general, there are several types of endpoints (we do not strictly enforce
this,
but it can serve you as a guideline in determining what an endpoint will
do):
- Endpoints ending in an ID of a resource return only this resource.
- Endpoints ending in a slash (irrespective if they contain an ID of a
resource
somewhere in the path) return a collection of resources. Often, leaving
away the resource ID at the end of a path will instead return all the
resources of this type that the user has access to (potentially filtered
and/or paginated, see below).
- GET endpoints should never lead to changes on the cloud system / database,
i.e.,
they are idempotent and can be called as many times as needed.
- If a path contains `/ops/`, it is an operation, i.e., calling this
endpoint
(usually with POST as it will lead to a change) will not result in a meaningful
response, but instead execute some operation in the c.technology cloud system.
By default, all communication is using `application/json` as a content type.
## Responses
The responses given by the c.technology cloud system follow standard HTTP
REST
conventions.
In particular, we return the following status codes:
| Status |
Description
|
| -------------------------
|:--------------------------------------------------------------------------------------------|
| 200 OK | Request successful, response contains
requested data. |
| 202 Accepted | Request successful, but processing is not
completed yet. |
| 204 No content | Request successful, but there is nothing to
return (e.g., often for `/ops`). |
| 400 Bad request | The request is invalid (bad formatting,
missing parameters, wrong content type, etc.). |
| 401 Unauthorized | You need to be authenticated to access this
resource. |
| 403 Forbidden | The user is not authorized to access this
resource. |
| 404 Not found | The resource was not
found. |
| 429 Too many requests | You hit a rate
limit.
|
| 500 Internal server error | You broke our system. Not nice. Please
[contact us](https://ctechnology.io/contact). |
All responses (that return something at all) are wrapped into the following
structure.
It is a deliberate choice to not use header fields for the metadata sent
along, as using
some fields on a JSON object is (in our experience) more straightforward to
use, allows seamless reuse of
data structures for RT (e.g., WebSocket) communication and easy extension
and configuration
for various types of returned data (paginated lists, single objects, errors,
etc.):
```json
{
"status": 12345,
"type": "SUCCESS",
"api_version": "v2.2",
"data": [ ... ],
...
}
```
Other notes:
- Datetime fields are always of the form `YYYY-MM-DDThh:mm:ss.sssZ`, meaning
that *all*
datetimes returned and accepted *must* be in UTC.
- An exception to this rule are settings (e.g., for vehicle services) where
a time
frame is specified, for example every Tuesday from 14:00 to 16:00. In this case,
the weekday is specified as `monday`, `tuesday`, `wednesday`, `thursday`, `friday`,
`saturday` or `sunday`, and the time simply as `14:00` resp. `16:00`. It is generally
assumed that this is local time, i.e., using the time zone at which a vehicle under
consideration is located (e.g., a user's timezone).
- Within the specification, IDs are specified as `string`, yet most IDs
you'll encounter
are actually numbers. This is simply to allow future changes towards string-based
IDs (such as UUIDs). As such, you should not rely on any ID being numeric.
## Errors
Responses indicating errors (all non-`20X` responses) always are of the
following form:
```json
{
"id": 98765,
"status": 12345,
"type": "NO_PERMISSION_USER_VIEW_MAP",
"api_version": "v2.2",
"severity": "LOW",
"message": "No permission to the given object.",
"message_i18n": "Keine Zugriffsrechte auf das angeforderte Objekt."
"data": null,
}
```
Here, `id` describes an internal error ID, the `type` is a textual
representation
of the ID (that might be more generic), the `severity` can be used to
determine
the course of action, and the `message` is a human-readable representation
of the
error (if available, it will be translated to the primary language of the
requesting
in the `message_i18n` field).
## Pagination
As mentioned above, resource lists are *always* paginated as described
below, where
`num_results` indicates the total number of resources available, `offset`
the
offset from starting at the beginning of the collection, and `limit` the
number
of resources returned. You can request different offsets and limits using
the
`offset=` and `limit=` query parameters on any of these endpoints.
The `next` and `previous` fields are optional, but might provide quick ways
to
retrieve more data from the c.technology system.
```json
{
"status": 12345,
"type": "SUCCESS",
"api_version": "v2.2",
"data": [ ... ],
"num_results": 1500,
"offset": 300,
"limit": 100,
"next": "https://ctechnology.io/api/v1.1/...?limit=50&after=XYZ",
"previous": "https://ctechnology.io/api/v1.1/...?limit=50&before=XYZ"
}
```
## Filtering, sorting and structuring
Several endpoints can be filtered, or subsets of data can be selected. If
not
indicated otherwise, you can filter by using the query parameter `filter=`,
followed by an HTML-encoded filter string, select subsets of data by
specifying
`fields=`, followed by a comma-separated list of fields, and sort by using
`orderby=` followed by a single field. By default, fields are sorted by
`timestamp`, if available.
## Rate limiting
You can make up to 80 requests per user per minute (limit to be increased
in the future and on demand), after which you will start receiving
`429 Too many requests` responses.
Note that for most purposes, you will want to use the c.technology real-time
(RT) API or our webhooks which are not limited in terms rates and can
provide
most information in a push-based manner.
## More information and resources
You can find more information on [ctechnology.io](https://ctechnology.io) or
on our
[company GitHub organization](https://github.com/c-technology).
Do not hesitate to contact us in case you have any questions or things
remain unclear.
servers:
- url: https://ctechnology.io/api/v2.2/
description: Primary server with auto-balancing.
security: []
tags:
- name: Authentication
description: |
Everything concerned with the authentication of users, organizations,
and apps.
- name: User
description: |
Everything concerned with user and organization accounts.
- name: Vehicle
description: |
Everything concerned with base vehicle properties.
- name: Trip
description: |
Everything concerned with trips and vehicle movements.
- name: Notification
description: |
Everything concerned with notifications and alerts.
- name: Geo
description: |
Everything concerned with geographic properties and functionalities.
- name: Insight
description: |
Everything concerned with advanced analytics and insights gained
from vehicle data.
- name: Note
description: |
Everything concerned with notetaking functionalities, such as the
calendar, notebook, document upload, etc.
- name: Maintenance
description: |
Everything concerned the predictive / preventive maintenance of vehicles.
- name: Vehicle Communication
description: |
Everything concerned with the communication with vehicles.
- name: Chore
description: |
Everything concerned with basic tasks such as image or document
uploading, system administration, etc.
- name: Security
description: |
Everything concerned with the authorizations, permissions, access
roles, etc.
- name: Payment
description: |
Everything concerned with the services, subscriptions, payments, etc.
- name: Developer
description: >
Everything concerned with the developer API, such as the SMTP settings,
etc.
- name: OEM Custom
description: |
Everything concerned with the OEM customizations, such as the
custom vehicle uploads etc.
paths:
/vehicle/{vehicle_id}:
get:
tags:
- Vehicle
summary: Get vehicle profile
description: >-
Gets the given vehicle's profile. This consists of user-defined settings
and profile information, as well as information about the hardware that
is installed on the vehicle and its configuration.
parameters:
- name: vehicle_id
in: path
schema:
type: string
required: true
description: ID of vehicle to retrieve.
responses:
'200':
description: Successful retrieval of vehicle profile.
content:
application/json:
schema:
type: object
title: VehicleProfileSingle
required:
- header
- data
properties:
header:
$ref: '#/components/schemas/APIHeaderSingle'
data:
$ref: '#/components/schemas/VehicleProfile'
'401':
$ref: '#/components/responses/APIResponseUnauthorized'
'403':
$ref: '#/components/responses/APIResponseForbidden'
'500':
$ref: '#/components/responses/APIResponseInternalServerError'
security:
- ApiKeyAuth: []
components:
schemas:
APIHeaderSingle:
type: object
title: API Header Single
description: |
Default header sent along with single-resource responses.
properties:
api_version:
type: string
description: >-
The API version that this response adheres to. Usually the same as
in the request URL.
readOnly: true
status:
type: string
description: A status code identifying this response. Usually "SUCCESS".
readOnly: true
message:
type: string
description: A descriptive English message about this response. Usually empty.
readOnly: true
permission_via:
type: array
description: A descriptive English message about this response. Usually empty.
items:
type: object
required:
- permission
- via
properties:
permission:
type: string
description: The permission that granted access to this API endpoint.
via:
type: string
description: >
Either `me` if a user permission granted access, or
`organization` if this is a
transitive permission.
enum:
- me
- organization
organization_id:
type: string
description: >-
The organization that gave access to this user for the given
resource.
readOnly: true
VehicleProfile:
type: object
title: Vehicle Profile
description: >
A vehicle's profile, containing all settings, installed sensors,
vehicle
information, etc.
required:
- id
- vehicle_type
- drivetrain_type
- device_id
- name
- type
- desc
- image_url
- ain_1_type
- ain_2_type
- ain_3_type
- ain_4_type
- din_1_type
- din_2_type
- din_3_type
- din_4_type
- din_5_type
- dout_1_type
- dout_2_type
- dout_3_type
- dout_4_type
- ble_temp_type
- temp_1_desc
- temp_2_desc
- temp_3_desc
- temp_4_desc
- battery_main_model
- battery_main_desc
- battery_ext_1_model
- battery_ext_1_desc
- device_angle_offset
- tank_size
- can_readout
- obd2_readout
- n2k_readout
- hibernation_mode
- maintenance_can_distance
- delivery_date
properties:
id:
type: string
description: A unique identifier for this vehicle.
readOnly: true
vehicle_type:
$ref: '#/components/schemas/VehicleType'
readOnly: true
drivetrain_type:
type: string
description: The drivetrain of this vehicle.
enum:
- GASOLINE
- DIESEL
- ELECTRIC
hardware_type:
type: string
description: The IoT hardware that is available in this device.
readOnly: true
protocol_type:
type: string
description: >-
The primary communication protocol used to communicate with the IoT
hardware.
readOnly: true
bluetooth:
type: boolean
description: If this device supports Bluetooth connections.
readOnly: true
bluetooth_address:
type: string
description: >
The Bluetooth address of this device. This can (usually) only be set
once, after which
it is read-only.
development_vehicle:
type: boolean
description: >
If this vehicle is a development vehicle. Development vehicles may
offer additional
options during usage.
readOnly: true
sim_type:
type: string
description: The SIM card type that is available for this device.
readOnly: true
processing_pipeline:
type: string
description: The processing pipeline used for processing this vehicle's data.
readOnly: true
processing_pipeline_module_options_overrides:
description: >
Individual module overrides.
**Note**: This is only for OEMs with special processing
requirements.
readOnly: true
device_id:
type: string
description: >
The short ID that is given to the vehicle owner to connect his / her
vehicle to his / her user account.
readOnly: true
name:
type: string
description: The owner-given name of this vehicle.
brand:
type: string
description: The brand of this vehicle.
type:
type: string
description: A type description of this vehicle.
desc:
type: string
description: >-
The owner-given description of his / her vehicle. -> Deprecated as
of v2.1 in favor of `description`.
description:
type: string
description: The owner-given description of his / her vehicle.
image_id:
type: string
description: >-
The ID of the "vehicle profile" image. You can retrieve a new image
identifier by POSTing a new image to `/image/`. Please refer to the
respective section of this documentation.
image_url:
type: string
description: >-
A prepared URL that describes how to access the "vehicle profile
image".
readOnly: true
group_id:
type: string
description: The ID of the group this vehicle belongs to.
readOnly: true
delivery_date:
type: string
format: date-time
description: >-
Date when the IoT device was sent to the customer / vehicle
manufacturer.
readOnly: true
primary_organization_id:
type: string
description: >
The ID of the primary organization, if any. The primary organization
is responsible for
the subscriptions and payments of the vehicle.
manufacturing_organization_id:
type: string
description: |
The ID of the manufacturing organization, if any.
professional_vehicle_id:
type: string
x-internal: true
description: |
An ID given by a professional organization, if any.
professional_vehicle_name:
type: string
x-internal: true
description: |
An vehicle name given by a professional organization, if any.
professional_location_main_lon:
type: number
x-internal: true
description: >
The location (longitude) of the vehicle, as specified by the
professional organization.
professional_location_main_lat:
type: number
x-internal: true
description: >
The location (latitude) of the vehicle, as specified by the
professional organization.
professional_location_main_desc:
type: string
x-internal: true
description: |
A description of the vehicle's location.
oem_vehicle_id:
type: string
description: >
An ID given by an OEM. -> Deprecated as of API v2.1 in favor of
`vehicle_identification_number` and
`organization_vehicles.organization_vehicle_id`.
oem_vehicle_type_id:
type: string
description: >
The vehicle type as specified by an OEM. -> Deprecated as of API
v2.1 in favor of
`organization_vehicles.organization_vehicle_type_id`.
vehicle_registration_id:
type: string
description: >
The vehicle's official registration ID. This is usually the license
plate number.
vehicle_identification_number:
type: string
description: |
The vehicle's official identification number, abbreviated as VIN.
ain_1_type:
$ref: '#/components/schemas/AINType'
type: string
description: Describes the type of sensor connected to the analog input 1.
ain_2_type:
$ref: '#/components/schemas/AINType'
type: string
description: Describes the type of sensor connected to the analog input 2.
ain_3_type:
$ref: '#/components/schemas/AINType'
type: string
description: Describes the type of sensor connected to the analog input 3.
ain_4_type:
$ref: '#/components/schemas/AINType'
type: string
description: Describes the type of sensor connected to the analog input 4.
ain_1_desc:
type: string
description: Description of what is plugged into analog input 1.
ain_2_desc:
type: string
description: Description of what is plugged into analog input 2.
ain_3_desc:
type: string
description: Description of what is plugged into analog input 3.
ain_4_desc:
type: string
description: Description of what is plugged into analog input 4.
din_1_type:
$ref: '#/components/schemas/DINType'
type: string
description: Describes the type of sensor connected to the digital input 1.
din_2_type:
$ref: '#/components/schemas/DINType'
type: string
description: Describes the type of sensor connected to the digital input 2.
din_3_type:
$ref: '#/components/schemas/DINType'
type: string
description: Describes the type of sensor connected to the digital input 3.
din_4_type:
$ref: '#/components/schemas/DINType'
type: string
description: Describes the type of sensor connected to the digital input 4.
din_5_type:
$ref: '#/components/schemas/DINType'
type: string
description: Describes the type of sensor connected to the digital input 5.
din_1_desc:
type: string
description: Description of what is plugged into digital input 1.
din_2_desc:
type: string
description: Description of what is plugged into digital input 2.
din_3_desc:
type: string
description: Description of what is plugged into digital input 3.
din_4_desc:
type: string
description: Description of what is plugged into digital input 4.
din_5_desc:
type: string
description: Description of what is plugged into digital input 5.
dout_1_type:
$ref: '#/components/schemas/DOUTType'
type: string
description: Describes the type of actuator connected to the digital output 1.
dout_2_type:
$ref: '#/components/schemas/DOUTType'
type: string
description: Describes the type of actuator connected to the digital output 2.
dout_3_type:
$ref: '#/components/schemas/DOUTType'
type: string
description: Describes the type of actuator connected to the digital output 3.
dout_4_type:
$ref: '#/components/schemas/DOUTType'
type: string
description: Describes the type of actuator connected to the digital output 4.
dout_1_desc:
type: string
description: Description of what is plugged into digital output 1.
dout_2_desc:
type: string
description: Description of what is plugged into digital output 2.
dout_3_desc:
type: string
description: Description of what is plugged into digital output 3.
dout_4_desc:
type: string
description: Description of what is plugged into digital output 4.
ble_temp_type:
type: string
description: >
Describes the number of Bluetooth temperature sensors connected.
This can either be `NONE`
or a string-encoded bit mask of the form `XXXX` (e.g., `1000` when
the first BLE temperature
sensor is connected).
temp_1_desc:
type: string
description: Descriptive text of Bluetooth temperature sensor 1.
temp_2_desc:
type: string
description: Descriptive text of Bluetooth temperature sensor 2.
temp_3_desc:
type: string
description: Descriptive text of Bluetooth temperature sensor 3.
temp_4_desc:
type: string
description: Descriptive text of Bluetooth temperature sensor 4.
battery_main_model:
$ref: '#/components/schemas/BatteryModelType'
type: string
description: Choice of main battery model.
battery_main_desc:
type: string
description: Description of main battery.
battery_ext_1_model:
$ref: '#/components/schemas/BatteryModelType'
type: string
description: Choice of first external battery model.
battery_ext_1_desc:
type: string
description: Description of first external battery.
battery_ext_2_model:
$ref: '#/components/schemas/BatteryModelType'
type: string
description: Choice of second external battery model.
battery_ext_2_desc:
type: string
description: Description of second external battery.
battery_ext_3_model:
$ref: '#/components/schemas/BatteryModelType'
type: string
description: Choice of third external battery model.
battery_ext_3_desc:
type: string
description: Description of third external battery.
battery_ext_4_model:
$ref: '#/components/schemas/BatteryModelType'
type: string
description: Choice of fourth external battery model.
battery_ext_4_desc:
type: string
description: Description of fourth external battery.
device_angle_offset:
type: number
description: >-
An offset in degrees that describes the positioning of the IoT
device within the vehicle.
readOnly: true
tank_size:
type: number
description: The size of the primary tank (in liters).
tank_prefer_analog:
type: boolean
description: >-
If an analog tank reading should be preferred over a CAN bus reading
(if available).
can_readout:
type: boolean
description: If the installed IoT device supports CAN bus readouts.
readOnly: true
obd2_readout:
type: boolean
description: If the installed IoT device supports OBD2 bus readouts.
readOnly: true
n2k_readout:
type: boolean
description: If the installed IoT device supports NMEA2000 bus readouts.
readOnly: true
hibernation_mode:
type: boolean
description: >
If the installed IoT device is in hibernation mode (where it sends
less data and thus
conserves energy).
transport_mode:
type: boolean
description: >
If the installed IoT device is in transport mode (where trips are
recorded, but not
saved to the logbook).
notrack_mode:
type: boolean
description: >
If the installed IoT device is in notrack mode (the sensor /
location data is not
processed).
notrack_mode_deact_time:
type: string
format: date-time
description: |
If the notrack mode is activated, when it will deactivate again.
readOnly: true
function_control_mode_deact_time:
type: string
format: date-time
description: >
If the function control mode is activated, when it will deactivate
again.
readOnly: true
subscription:
$ref: '#/components/schemas/ServiceSubscription'
organization_vehicles:
x-internal: true
type: array
description: >
The organizations that are allowed to access this vehicle. The
information passed
along here might differ depending on your own organizational access.
items:
$ref: '#/components/schemas/OrganizationVehicle'
initial_distance:
type: number
description: The configured initial distance before the IoT device was installed.
initial_operation_hours:
type: number
description: The configured operation hours before the IoT device was installed.
initial_date:
type: string
format: date
description: The data when the IoT device was installed.
maintenance_can_distance:
type: boolean
description: Measured CAN distance before installation.
readOnly: true
initialization_complete:
type: boolean
description: |
If the initialization of this vehicle is complete.
auto_discover_home:
type: boolean
description: |
If this vehicle automatically discovers new home locations.
trips_end_at_home:
type: boolean
description: >
If trips of this vehicle should always stop when it approaches a
home location.
remove_trip_points_on_land:
type: boolean
description: |
If trip points on land should be removed during trip processing.
boat_type:
type: string
description: The type of boat, if applicable.
enum:
- MOTORBOAT
- SAILBOAT
vehicle_length_m:
type: number
description: The length of the vehicle in meters.
vehicle_depth_m:
type: number
description: The depth of the vehicle in meters.
vehicle_height_m:
type: number
description: The height of the vehicle in meters.
vehicle_weight_kg:
type: number
description: The weight of the vehicle in kilograms.
main_battery_property_pct:
type: string
description: >-
The vehicle status field that is considered the main battery
property.
main_fuel_property_pct:
type: string
description: The vehicle status field that is considered the main fuel property.
display_settings:
$ref: '#/components/schemas/VehicleDisplaySettings'
VehicleType:
type: string
title: Vehicle Type
description: >
The vehicle types currently supported by the c.technology cloud
platform.
`BOAT` describes nautical vehicles, `MCYCLE` motorcycles, and `CLASSCAR`
classic
cars.
`MOTOR` is a bit a special case, but is used to describe (electric)
motors that
act as the primarily important part of a vehicle.
More vehicle types will be supported in the future.
enum:
- BOAT
- MCYCLE
- CLASSCAR
- MOTOR
AINType:
enum:
- NONE
- FUEL
- BATTERY
- BATTERY_2
- BATTERY_3
- BATTERY_4
- 220VLAND
- 220VLINV
- WATER
- WATERINV
DINType:
enum:
- NONE
- 220VLAND
- 220VLINV
- WATER
- WATERINV
- ARBTR
- ARBTRINV
DOUTType:
enum:
- NONE
- LOCK
- NO_REFL
- IN_OSZ
- IN_ISZ
- OSPD_SZ
- IN_FRBZ
- FUEL_CRT
- ARBTR
BatteryModelType:
enum:
- 12V-DEF
- 24V-DEF
- 24V-2x12
- 24V-SLB
ServiceSubscription:
type: object
title: Service Subscription
description: >
A subscription to a service within the c.technology cloud ecosystem.
This could
be for a single vehicle's functionality (most common use case), but also
for an
additional service such as the vehicle launch service.
Note that you cannot directly create service subscriptions, but have to
use another
endpoint to do so (Stripe for recurring payments, buy and use a voucher
for one-time
activations, etc.).
required:
- id
- timestamp_start
- timestamp_end
- service_type
- origin_type
properties:
id:
type: string
description: A unique ID identifying this subscription.
readOnly: true
user_id:
type: string
description: |
The user for which this subscription is used (might be undefined).
readOnly: true
vehicle_id:
type: string
description: >
The vehicle for which this subscription is used (might be
undefined).
readOnly: true
timestamp_start:
type: string
format: date-time
description: |
The timestamp when this subscription starts.
readOnly: true
timestamp_end:
type: string
format: date-time
description: |
The timestamp when this subscription ends.
readOnly: true
service_type:
type: string
description: |
The type of service this subscription is used for.
enum:
- BASE
readOnly: true
origin_type:
type: string
description: >
How this subscription originally came to be, i.e., who bought or
created it.
enum:
- SUBSCR_STRIPE
- SUBSCR_STRIPE_RE
- VOUCHER
- OEM
- MANUAL
- TRIAL
readOnly: true
stripe_subscription:
type: string
description: |
The corresponding Stripe subscription object, if it exists.
readOnly: true
voucher_id:
type: number
description: |
The corresponding voucher object, if it exists.
readOnly: true
OrganizationVehicle:
type: object
title: Organization Vehicle
x-internal: true
description: |
The relationship between an organization and a vehicle.
required:
- id
- organization_id
- vehicle_id
properties:
id:
type: string
description: A unique identifier for this Organization Vehicle object.
readOnly: true
organization_id:
type: string
description: The organization ID.
vehicle_id:
type: string
description: The vehicle Type ID.
vehicle_device_id:
type: string
description: The device ID for the vehicle.
role:
type: string
enum:
- VEHICLE_OWNER
- VEHICLE_MAINTAINER
- VEHICLE_MANUFACTURER
description: The role of the organization in relation to the vehicle.
primary_organization:
type: boolean
description: >-
Whether the organization is the primary organization for the
vehicle.
manufacturing_organization:
type: boolean
description: >-
Whether the organization is the manufacturing organization for the
vehicle.
vehicle_category_id:
type: string
description: The assigned category id for the vehicle.
vehicle_category_name:
type: string
description: The assigned category name for the vehicle.
vehicle_family_id:
type: string
description: The assigned family id for the vehicle.
vehicle_family_name:
type: string
description: The assigned family name for the vehicle.
vehicle_type_id:
type: string
description: The assigned type id for the vehicle.
vehicle_type_name:
type: string
description: The assigned type name for the vehicle.
vehicle_type_image_url:
type: string
description: The image URL for the vehicle type.
organization_vehicle_id:
type: string
description: An arbitrary id that the organization has assigned to the vehicle.
organization_vehicle_name:
type: string
description: The name of the vehicle as it is known within the organization.
organization_vehicle_desc:
type: string
description: A description of the vehicle as it is known within the organization.
vehicle_type_max_speed:
type: number
format: float
description: >-
The maximum speed of this type in km/h. This is used to adapt the
frontends to the vehicle type.
vehicle_type_battery_capacity_wh:
type: number
format: float
description: >-
Battery capacity in watt-hours (Wh) for electric vehicles. Used for
range calculations and energy consumption analytics.
vehicle_type_avg_consumption_wh_per_km:
type: number
format: float
description: >-
Average energy consumption in watt-hours per kilometer (Wh/km) for
electric vehicles. This OEM-specified value is used as baseline for
range calculations.
vehicle_type_tank_capacity_l:
type: number
format: float
description: >-
Fuel tank capacity in liters for fuel-powered vehicles. Used for
range calculations and fuel consumption analytics.
vehicle_type_avg_consumption_l_per_100km:
type: number
format: float
description: >-
Average fuel consumption in liters per 100 kilometers (L/100km) for
fuel-powered vehicles. This OEM-specified value is used as baseline
for range calculations.
drivetrain_type:
type: string
enum:
- ELECTRIC
- DIESEL
- GASOLINE
nullable: true
description: >
The drivetrain type of this vehicle type.
ELECTRIC for electric vehicles, DIESEL for diesel engines, GASOLINE
for gasoline engines.
Used to determine appropriate consumption parameters and analytics.
location_main_desc:
type: string
description: >-
The description of the main location (e.g., where it is parked) for
the vehicle.
VehicleDisplaySettings:
type: object
title: Vehicle Display Settings
description: >
Various settings related to how a vehicle is displayed in the native or
web app. Currently,
this is not editable, but only available as part of a vehicle GET
response.
properties:
webapp_sidebar_slot_1:
type: string
description: >
The vehicle status property to display in the first slot of the
vehicle sidebar in the web app.
Is given in vehicle status accessor form, e.g., "fuel_level_pct" or
nested as
"vehicle_status_can.battery_main_pct".
webapp_sidebar_slot_2:
type: string
description: >
The vehicle status property to display in the second slot of the
vehicle sidebar in the web app.
Is given in vehicle status accessor form, e.g., "fuel_level_pct" or
nested as
"vehicle_status_can.battery_main_pct".
nativeapp_dashboard_main:
type: string
description: >
What to show on the dashboard in the native app. Is given in vehicle
status accessor form, e.g.,
"fuel_level_pct" or nested as "vehicle_status_can.battery_main_pct".
nativeapp_four_most_important_1:
type: string
description: >
What to show as the most important additional property. Is given in
vehicle status accessor form, e.g.,
"fuel_level_pct" or nested as "vehicle_status_can.battery_main_pct".
nativeapp_four_most_important_2:
type: string
description: >
What to show as the second most important additional property. Is
given in vehicle status accessor form, e.g.,
"fuel_level_pct" or nested as "vehicle_status_can.battery_main_pct".
nativeapp_four_most_important_3:
type: string
description: >
What to show as the third most important additional property. Is
given in vehicle status accessor form, e.g.,
"fuel_level_pct" or nested as "vehicle_status_can.battery_main_pct".
nativeapp_four_most_important_4:
type: string
description: >
What to show as the fourth most important additional property. Is
given in vehicle status accessor form, e.g.,
"fuel_level_pct" or nested as "vehicle_status_can.battery_main_pct".
APIError:
type: object
title: API Error
description: |
A generic response after any erroneous process (error of any kind). This
response contains fields to identify the particular error.
required:
- header
- error
properties:
header:
$ref: '#/components/schemas/APIHeaderSingle'
error:
type: object
description: |
Containing detailed information about the error.
properties:
id:
type: string
description: |
An internal ID given to this particular error instance.
This might not be available, as not all errors are uniquely
logged and given an id.
readOnly: true
status:
type: number
description: |
An error code that can be used to identify this error.
readOnly: true
type:
type: string
description: |
A more generic description of the error that can be
used to generate an error message for the user.
readOnly: true
severity:
type: string
description: |
An indication of how severe the error is. You might use this
to custom-tailor the response to the user.
readOnly: true
enum:
- ALERT
- HIGH
- MEDIUM
- LOW
message:
type: string
description: |
A human-readable English message that describes the error.
readOnly: true
message_i18n:
type: string
description: |
A human-readable message in the primary language of the
user that describes the error. Note that this might not
always be available.
readOnly: true
data:
type: object
title: Error Data
description: |
Additional data that might be added to this error.
readOnly: true
responses:
APIResponseUnauthorized:
description: |
You need to be authenticated to perform this action.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
APIResponseForbidden:
description: |
You have no permission to perform this action.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
APIResponseInternalServerError:
description: |
The server encountered an internal error.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
description: |
Note that the API key has to be sent as `Token 123` where `123` is
the key you received after logging in or by creating on the developer
dashboard.
name: Authorization
````