> ## 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 actions
> Get actions of all vehicles. Actions are "things of interest" that happen with the vehicle,
such as errors generated by the engine, entering/leaving harbor/home locations, exceeding
speed limits, etc.
Most actions are generated independent of a user's settings, but some are dependent on
user choices (e.g., notification rules). In this case, the action contains a user ID for
which it is valid, and the action is *not* reported for other users.
The returned actions are sorted newest-first.
## OpenAPI
````yaml api-reference/openapi.yml get /vehicle/action
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/action:
get:
tags:
- Vehicle
summary: Get vehicle actions
description: >
Get actions of all vehicles. Actions are "things of interest" that
happen with the vehicle,
such as errors generated by the engine, entering/leaving harbor/home
locations, exceeding
speed limits, etc.
Most actions are generated independent of a user's settings, but some
are dependent on
user choices (e.g., notification rules). In this case, the action
contains a user ID for
which it is valid, and the action is *not* reported for other users.
The returned actions are sorted newest-first.
parameters:
- name: from
in: query
schema:
type: string
format: date-time
description: Limit the actions to those which timestamp is after `from`.
- name: to
in: query
schema:
type: string
format: date-time
description: Limit the actions to those which timestamp is before `to`.
- name: limit
in: query
schema:
type: number
description: Limit the number of returned actions.
- name: offset
required: false
in: query
schema:
type: number
description: Offset the returned actions.
- name: scope
in: query
schema:
$ref: '#/components/schemas/VisibilityScope'
description: The scope, publicly shared actions or a user's private ones.
responses:
'200':
description: Successful retrieval of vehicle actions.
content:
application/json:
schema:
type: object
title: VehicleActionPaginated
required:
- header
- data
properties:
header:
$ref: '#/components/schemas/APIHeaderPaginated'
data:
type: array
items:
$ref: '#/components/schemas/VehicleAction'
'400':
$ref: '#/components/responses/APIResponseBadRequest'
'401':
$ref: '#/components/responses/APIResponseUnauthorized'
'403':
$ref: '#/components/responses/APIResponseForbidden'
'500':
$ref: '#/components/responses/APIResponseInternalServerError'
security:
- ApiKeyAuth: []
components:
schemas:
VisibilityScope:
x-internal: true
type: string
description: |
The visibility scope of trips, actions, etc.
enum:
- PUBLIC
- PRIVATE
APIHeaderPaginated:
type: object
title: API Header Paginated
description: >
Default header sent along with multi-resource responses (lists of
resources).
required:
- num_results
properties:
api_version:
type: string
description: The API version that this response adheres to.
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
num_results:
type: number
description: The total number of results.
readOnly: true
offset:
type: number
description: The pagination offset.
readOnly: true
limit:
type: number
description: The pagination limit.
readOnly: true
VehicleAction:
type: object
title: Vehicle Action
description: >
Anything that happened with a given vehicle at a particular point in
time.
required:
- id
- vehicle_id
- trip_id
- timestamp
- type
- data
- message
properties:
id:
type: string
description: A unique identifier for this action.
readOnly: true
vehicle_id:
type: string
description: The ID of the vehicle this action is for.
readOnly: true
user_id:
type: string
nullable: true
description: The ID of the user for which this action was generated (if any).
readOnly: true
trip_id:
type: string
nullable: true
description: The ID of the trip during which this action was generated (if any).
readOnly: true
timestamp:
type: string
format: date-time
description: The date/time at which this action was generated.fdfd
readOnly: true
type:
type: string
readOnly: true
description: >
The type of action:
- `VEHICLE_MOV`: Vehicle starts moving (e.g., away from home
location/harbor).
- `VEHICLE_MOV_ACC`: Vehicle starts moving (as detected by
accelerometer).
- `VEHICLE_MOV_TOW`: Vehicle starts moving (as indicated via CAN
bus).
- `SZ_ENTER`: Vehicle enters shore zone (boats).
- `ISZ_ENTER`: Vehicle enters inner shore zone (boats).
- `OSZ_ENTER`: Vehicle enters outer shore zone (boats).
- `SZ_LEAVE`: Vehicle leaves shore zone (boats).
- `ISZ_LEAVE`: Vehicle leaves inner shore zone (boats).
- `OSZ_LEAVE`: Vehicle leaves outer shore zone (boats).
- `SZ_EXSPEED`: Vehicle exceeds speed limit in shore zone (boats).
- `ISZ_EXSPEED`: Vehicle exceeds speed limit in inner shore zone
(boats).
- `OSZ_EXSPEED`:Vehicle exceeds speed limit in outer shore zone
(boats).
- `HOME_LOCATION_ENTER`: Vehicle enters home location / harbor.
- `HOME_LOCATION_LEAVE`: Vehicle leaves home location / harbor.
- `STAYPOINT_ENTER`: Vehicle enters a new staypoint (point where it
stays for a longer time).
- `STAYPOINT_LEAVE`: Vehicle leaves staypoint (point where it stays
for a longer time).
- `TRIPLEG_START`: Tripleg starts (part of a larger trip between two
staypoints).
- `TRIPLEG_END`: Tripleg ends.
- `TRIP_START`: Trip starts (sequence of multiple triplegs driven in
a certain timeframe).
- `TRIP_STOP`: Trip stops. This can be a temporary stop, i.e., the
trip might be continued.
- `TRIP_CONTINUE`: Trip continues.
- `TRIP_COMPLETE`: Trip is complete. This action might be generated
quite a while after the trip stops due
to the time it takes to detect it.
- `JOURNEY_START`: Journey starts (a journey is a trip from one home
location / harbor to another).
- `JOURNEY_STOP`: Journey stops (might be continued).
- `JOURNEY_CONTINUE`: Journey continues.
- `JOURNEY_COMPLETE`: Jorney is complete. This action might be
generated quite a while after the trip stops due
to the time it takes to detect it.
- `LLV_NC_LT`: Low temperature was detected while no landline is
connected.
- `LLV_DISC`: Landline (220V) is disconnected.
- `LLV_CONN`: Landline (220V) is connected.
- `IGNITION_ON`: Ignition is turned off.
- `IGNITION_OFF`: Ignition is turned on.
- `DIST_REM_CRIT`: The remaining distance is critical. It is
recommended to refuel soon.
- `TEMP_CRIT`: The (ambient/outdoor) temperature is critical.
- `REFUEL`: The vehicle was refueled.
- `FUEL_LOW_RET`: The fuel is not 100% when returning to a home
location / harbor.
- `BAT_LOW`: The battery is low.
- `BAT_DISC`: The battery was disconnected.
- `USER_BAT_V`: The battery is above / below a user-defined
threshold (V).
- `USER_BAT_PCT`: The battery is above / below a user-defined
threshold (%).
- `USER_FUEL_PCT`: The fuel is above / below a user-defined
threshold (%).
- `USER_TEMP`: The temperature is above / below a user-defined
threshold (°C).
- `USER_TEMP_1`: Temperature 1 is above / below a user-defined
threshold (°C).
- `USER_TEMP_2`: Temperature 2 is above / below a user-defined
threshold (°C).
- `USER_TEMP_3`: Temperature 3 is above / below a user-defined
threshold (°C).
- `USER_TEMP_4`: Temperature 4 is above / below a user-defined
threshold (°C).
- `USER_HOME_LOCATION_DIST`: The distance to the home location /
harbor is above / below a
user-defined threshold (m).
- `USER_SHORE_DIST`: The distance to the shore is above / below a
user-defined threshold (m).
- `USER_GEOFENCE_ENTER`: The vehicle enters a user-defined geofence.
- `USER_GEOFENCE_LEAVE`: The vehicle leaves a user-defined geofence.
- `USER_STAYPOINT_DIST`: The distance to the last staypoint is above
a user-defined threshold (m).
- `WATER_IN`: The vehicle was put into the water (boats).
- `WATER_OUT`: The vehicle was taken out of the water (boats).
- `MAINTENANCE`: A maintenance event reached a critical threshold.
- `NEW_TICKET`: A new ticket was created by a user.
message:
type: string
description: The message corresponding to the action type.
readOnly: true
data:
type: object
description: Additional data that is used to describe the action in more detail.
readOnly: true
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
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
responses:
APIResponseBadRequest:
description: |
Your request is formatted wrongly.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
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
````