Authentication

Endpoint to authenticate the user and obtain an access token for accessing any entitled enpoints. This follows the OAuth 2.0 password based grant. The same user may successfully log-in once per second, on average. Occasional log-in bursts are allowed, and the maximum lock-out time is 2 seconds. Failed login attempts are throttled more aggressively, using an exponentially increasing lock-out times.

post

Obtain an access token for a given user and client. The response code, either 200 or 303, depends on whether the redirect_uri optional field was not set or set in the request, respectively.

Communication Units

Endpoints to retrieve information about communication unit(s).

get

Get a list of all communication units visible to the current user.

get

Get information about a single communication unit.

get

Get the number of communication units.

Clustering

Endpoints to obtain clustering reports.

post

Generate a k-means clustering report. Each report point (aggregated point) corresponds to a machine of the model. Aggregated points are calculated by applying the reduction function to all measurements of given signal of the machine. The number of requested clusters has to be greater than the number of machines of a model.

Images

Endpoints to retrieve images.

get

Gets the image for a given machine.

get

Gets an image of the given model.

Machines

Endpoints to retrieve information about machine(s).

get

Get a list of machines satisfying the given criteria.

get

Get information about a single machine.

get

Gets geo location (latitude and longitude) of a machine for a given time range.

Spatial resolution varies with latitude, and is about 5 meters at the equator.

This endpoint can be used to visualize a GPS track in a UI (by aggregating the data into buckets, or taking raw location data if no time bucket is provided).

To get full GNSS data (including altitude, heading, speed) see /machines/{id}/gnss endpoint.

post

Exposes historical raw data from GNSS sensor of the communication unit installed to the machine.

get

Counts stored data points of given machine in given time range. Maximal range is 90 days.

get

Get the latest signal values of a machine.

Measurements are most useful when showing the current state of a vehicle. For example, a gauge with the latest temperature.

Signals are grouped by type (numeric or string).

Signal names are retrieved from metrics seen during last 30 days or in given interval (see 'from' and 'to' parameters). Maximal lookup interval is 30 days.

get

Get the Diagnostic Trouble Codes for this machine. Consistent with J1939 specification.

get

Get the J1939 lamps for this machine aggregated per lamp type by time with given bucketSize. Consistent with J1939 specification.

get

Get all signals a machine could possibly have based on its configuration.

get

Get a single signal a machine could possibly have based on its configuration.

put

Update machine name. User should be entitled for machine management.

put

Update machine serial number. User should be entitled for machine management.

put

Update machine organization. User should be entitled for organization management.

put

Update machine's model. This includes clearing it, if the request specifies a null value explicitly. User should be entitled for machine management.

put

Update machine PIN (Product Identification Number). User should be entitled for machine management. A valid PIN must contain 17 characters length, only alphanumeric characters are allowed and must be unique between all machine. Note that the request accepts mixed-case characters, but it will be stored in uppercase.

put

Update machine VIN (Vehicle Identification Number). User should be entitled for machine management. A valid VIN must contain 17 characters length, only alphanumeric characters are allowed and must be unique between all machine. Note that the request accepts mixed-case characters, but it will be stored in uppercase.

put

Switch the machine's CU into a specific mode. This instructs the Proemion Platform to switch the CU into to a given mode, if the CU is currently online. Available modes are "realtime" and "logging".

See also POST */realtimeTokens.

post

Generates realtime session token. The token together with connection details is required for diagnosis client to connect to a machine's CU via Proemion Communication Server.

get

Get the number of machines.

get

Get GeoLeash info including current state of the feature known by the platform and the list of 10 last GeoLeash actions.

post

Perform GeoLeash action. For action_types activate and setLength payload with leashLength is expected.

get

List of machine actions.

get

Machine action details.

get

List of machine numeric action executions. The list is filtered based on permissions defined in the current machine's PDC.

post

Execute an action in an async way.

GeoLeash machine events

Endpoints to retrieve and manage GeoLeash machine events

get

Get GeoLeash breached events. If no query parameters specified following defaults are applied:

  • events of all accessible machines;
  • events of all types;
  • time range - last 14 days;
  • ordered by time descending.
get

Get an image depicting the GeoLeash breach event on the map.

get

Gets the authenticated user's status of machine GeoLeash events subscription.

put

Subscribes the authenticated user to (or unsubscribes them from) machine GeoLeash events.

Machine assignments

Endpoints to create, edit, delete and retrieve machine assignments.

get

Get a page of all available machine assignments matching the given criteria. Only assignments directly in the requester's organization unit are considered.

post

Creates a new assignment.

delete

Deletes an assignment.

put

Updates the assignment's title.

put

Updates the assignment's description. This includes clearing it, if the request specifies a null value explicitly.

put

Updates the assignment's timerange.

put

Updates the assignment's external key. This includes clearing it, if the request specifies a null value explicitly.

put

Updates the assignment's status.

put

Updates the assignment's machines. All machines have to be in the requester's organization tree.

Models

Endpoints to retrieve information about model(s).

get

Get a page of all visible models matching the given criteria. A model is visible if it belongs to the requester's organization tree, or if it belongs to any parent organization and is used by a machine belonging to the requester's organization tree. Results can be sorted by model "name" only.

post

Creates a new model. The authenticated user should be entitled to model management.

get

Get information about a single model.

delete

Deletes the model.

get

Get all signals configured for machines assigned to this model.

put

Updates the model's name.

put

Updates the model's description. This includes clearing it, if the request specifies a null value explicitly.

put

Updates the model's image. This includes clearing it, if the request specifies a null value explicitly.

post

Gets the aggregated measurement for each machine of the given model.

get

Gets the number of all visible models.

Signals

Endpoints to retrieve information about signals.

get

Get all signals configured for visible machines. The results are deduplicated by signal key - this means that if multiple signals share the same key, just an arbitrarily chosen one of them will be returned.

Organization Units

Endpoints to retrieve information about organization unit(s).

get

Get a page of organization units matching the given criteria. Results can be sorted by organization "id" or "name" only.

post

Creates a new organization. User should be entitled for organization management.

get

Get the number of organization units.

get

Get Organization Unit by ID, optionally having a tree of sub organization units. It might also return organization SAP reference number if the requester has view permission for contracts.

delete

Deletes an organization.

get

Get a list of users belonging the specified organization unit and matching the given criteria. Results can be sorted by name, firstname and lastname.

get

Get a page of visible models for this organization unit. A model is visible if it belongs to this organization unit, or if it belongs to any parent organization and is used by a machine belonging to this organization tree. This endpoint is deprecated and is going to be removed by the end of July 2019. Please use "GET /models/?organizationUnit={id}" instead.

get

Get a list of communication units belonging the specified organization unit and matching the given criteria.

put

Updates organization name.

get

Get the organization's type and a list of other types that can be assigned to it.

put

Updates organization type. The given type must not be higher than the parent organization type. By default organizations have type as 'none'.

get

Get the current parent organization and potential parents for the given organization under the user's accessible organizations tree. User should be entitled for organization management.

put

Moves the current organization to another part of the organization tree by changing its parent organization.

Note that the organization type matters here. The available types are, from highest to lowest, "distributor", "oem", "dealer", "machine_owner" and "none". An organization can change to a parent with a type higher or equal to the one it has. Trying to set a parent with a lower type will cause an error.

User should be entitled for organization management.

Timeseries

Endpoints to query timeseries. Timeseries are composed of raw or aggregated values for a particular signal of a machine or a model.

Timeseries are useful when querying a number of values over a date range, we support a wide range of aggregations and raw (non-aggregated) datapoints.

An example usage is providing data for plotting signal value changes over time.

This is in contrast to the /measurements API, which returns just the last data point.

post

Run the given query.

IMPORTANT NOTE: As a result of our internal bucket division and how aggregation operations are calculated, you might experience an unexpected amount of results in those situations where aggregation functions are used in combination with a time range that crosses more than one of our internal data buckets. In those situations, the result will contain one datapoint per crossed bucket. As an example, a request with a selected bucket size of 1h under a 2h time range could be answered with 2+ datapoint. Assume, storage contains data points with timestamps "10:30:00", "11:30:00", "12:03:00". If requested timerange is "Nov 21 2018 10:05:00" - "Nov 21 2018 12:05:00" then the response will contain 3 buckets (instead of 2) with timestamps "10:00:00", "11:00:00" and "12:00:00". Keep in mind that the bucket content is not wrong. The combined 3 buckets get the correct number. For example, if you use the sum aggregation, the total for the 3 buckets will be as expected. This is just the way the response is presented (in a full hour interval broken on the hour).

Users

Endpoints to retrieve users.

get

Get a list of all users.

get

Get a single user by their UUID.

get

Get an array of permission sets for a given user (target), containing assignable levels for each subject. Assignable levels are based on the logged in user's (actor) ability to change the permission sets.

put

Updates the current permissions for a given user.

put

Update user detail (First name and Last name).

put

Update user's "banned" status (i.e. impose or revoke a ban upon a user). A banned user will not able to successfully authenticate with any Proemion application. User can not ban/unban himself.

get

Get the number of users.

Endpoints to search for following entities: models, machines, communication units, organization units and users.

Entitlements

The entitlements are used to control access to the REST endpoints for each user. This listing provides all possible entitlements.

get

Get a list of all dataportal entitlements.

Users administration

Endpoint to update user's organization.

put

Move user to another organization unit. Executor should be entitled for the target organization unit and needs to have organization management permission.