Devices

The main artifact of the system is the device. A device is a physical or virtual entity that can be tracked, monitored and controlled.

Devices are managed by the system and can be assigned to users and groups.

The Devices Model

A devices is represented by the following schema:

Scheme

Name
id
Type
integer
Description
Name
name
Type
string
Description
Name
uniqueId
Type
string
Description
Name
status
Type
string
Description
Name
disabled
Type
boolean
Description
Name
lastUpdate
Type
string
Description
in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
Name
positionId
Type
integer
Description
Name
groupId
Type
integer
Description
Name
phone
Type
string
Description
Name
model
Type
string
Description
Name
contact
Type
string
Description
Name
category
Type
string
Description
Name
attributes
Type
object
Description

GET/devices

Retrieve devices information

Without any params, returns a list of the user's devices

Authorizations

BasicAuth or ApiKey

Name
BasicAuth
Type
scheme
Description
HTTP Authorization Scheme: basic
Name
ApiKey
Type
scheme
Description
HTTP Authorization Scheme: bearer

Query Parameters

Name
all
Type
boolean
Description
Can only be used by administrators or managers to retrieve all Device objects.
Name
userId
Type
integer
Description
Standard users can use this only with their own userId
Name
id
Type
integer
Description
To fetch one or more devices. Multiple params can be passed like id=1&id=2
Name
uniqueId
Type
string
Description
To fetch one or more devices. Multiple params can be passed like uniqueId=1&uniqueId=2
Name
excludeAttributes
Type
boolean
Description
Exclude attributes field from device payload
Name
limit
Type
integer
Description
Limit the number of returned results
Name
offset
Type
integer
Description
Offset for pagination
Name
keyword
Type
string
Description
Search keyword filter (searches name, uniqueId, phone, model, contact)

Response schema

Name
application/json
Type
schema
Description

Responses

Name
200
Type
success
Description
Array of Device
Name
400
Type
error
Description
Not permission

Request

GET

/devices

curl --location 'https://gw.onemap8.com/api/devices?all=<boolean>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

[
  {
    "id": 0,
    "name": "string",
    "uniqueId": "string",
    "status": "string",
    "disabled": true,
    "lastUpdate": "2019-08-24T14:15:22Z",
    "positionId": 0,
    "groupId": 0,
    "phone": "string",
    "model": "string",
    "contact": "string",
    "category": "string",
    "attributes": { }
  },
  {
    ...
  }
]

POST/devices

Create a device

Authorizations

BasicAuth or ApiKey

Name
BasicAuth
Type
scheme
Description
HTTP Authorization Scheme: basic
Name
ApiKey
Type
scheme
Description
HTTP Authorization Scheme: bearer

Request body schema

Name
application/json
Type
schema
Description

Body schema

Name
id
Type
integer
Description
Name
name
Type
string
Description
Name
uniqueId
Type
string
Description
Name
status
Type
string
Description
Name
disabled
Type
boolean
Description
Name
lastUpdate
Type
string
Description
in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
Name
positionId
Type
integer
Description
Name
groupId
Type
integer
Description
Name
phone
Type
string
Description
Name
model
Type
string
Description
Name
contact
Type
string
Description
Name
category
Type
string
Description
Name
attributes
Type
object
Description

Response schema

Name
application/json
Type
schema
Description

Responses

Name
200
Type
success
Description
Device

Request

POST

/devices

curl --location 'https://gw.onemap8.com/api/devices' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": "<integer>",
"name": "<string>",
"uniqueId": "<string>",
"status": "<string>",
"disabled": "<boolean>",
"lastUpdate": "<dateTime>",
"positionId": "<integer>",
"groupId": "<integer>",
"phone": "<string>",
"model": "<string>",
"contact": "<string>",
"category": "<string>",
"attributes": {}
}'

Response

{
  "id": 0,
  "name": "string",
  "uniqueId": "string",
  "status": "string",
  "disabled": true,
  "lastUpdate": "2019-08-24T14:15:22Z",
  "positionId": 0,
  "groupId": 0,
  "phone": "string",
  "model": "string",
  "contact": "string",
  "category": "string",
  "attributes": { }
}

PUT/devices/{id}

Update a device

Authorizations

BasicAuth or ApiKey

Name
BasicAuth
Type
scheme
Description
HTTP Authorization Scheme: basic
Name
ApiKey
Type
scheme
Description
HTTP Authorization Scheme: bearer

Path parameters

Name
id
Type
integer
Description
required

Request body schema

Name
application/json
Type
schema
Description

Body schema

Name
id
Type
integer
Description
Name
name
Type
string
Description
Name
uniqueId
Type
string
Description
Name
status
Type
string
Description
Name
disabled
Type
boolean
Description
Name
lastUpdate
Type
string
Description
in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
Name
positionId
Type
integer
Description
Name
groupId
Type
integer
Description
Name
phone
Type
string
Description
Name
model
Type
string
Description
Name
contact
Type
string
Description
Name
category
Type
string
Description
Name
attributes
Type
object
Description

Response schema

Name
application/json
Type
schema
Description

Responses

Name
200
Type
success
Description
Device

Request

PUT

/devices/{id}

  curl --location --request PUT 'https://gw.onemap8.com/api/devices/<integer>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": "<integer>",
"name": "<string>",
"uniqueId": "<string>",
"status": "<string>",
"disabled": "<boolean>",
"lastUpdate": "<dateTime>",
"positionId": "<integer>",
"groupId": "<integer>",
"phone": "<string>",
"model": "<string>",
"contact": "<string>",
"category": "<string>",
"attributes": {}
}'

Response

{
    "id": 0,
    "name": "string",
    "email": "string",
    "phone": "string",
    "readonly": true,
    "administrator": true,
    "map": "string",
    "latitude": 0,
    "longitude": 0,
    "zoom": 0,
    "password": "string",
    "coordinateFormat": "string",
    "disabled": true,
    "expirationTime": "2019-08-24T14:15:22Z",
    "deviceLimit": 0,
    "userLimit": 0,
    "deviceReadonly": true,
    "limitCommands": true,
    "fixedEmail": true,
    "poiLayer": "string",
    "attributes": { }
}

DELETE/devices/{id}

Delete a device

Authorizations

BasicAuth or ApiKey

Name
BasicAuth
Type
scheme
Description
HTTP Authorization Scheme: basic
Name
ApiKey
Type
scheme
Description
HTTP Authorization Scheme: bearer

Path parameters

Name
id
Type
integer
Description
required

Responses

Name
204
Type
success
Description
No content

Request

DELETE

/devices/{id}

  curl --location --request DELETE 'https://gw.onemap8.com/api/devices/<integer>' \
  --header 'Authorization: Basic {your_access_token}'

Response

No content

PUT/devices/{id}/accumulators

Update device accumulators

Update total distance and hours of the Device.

Authorizations

BasicAuth or ApiKey

Name
BasicAuth
Type
scheme
Description
HTTP Authorization Scheme: basic
Name
ApiKey
Type
scheme
Description
HTTP Authorization Scheme: bearer

Path parameters

Name
id
Type
integer required
Description
Device ID

Request body schema

Name
application/json
Type
schema
Description

Body schema

Name
deviceId
Type
integer
Description
Device identifier for the accumulator entry
Name
totalDistance
Type
number
Description
Total distance in meters
Name
hours
Type
number
Description
Total engine hours recorded by the device

Responses

Name
204
Type
success
Description
No content

Request

PUT

/devices/{id}/accumulators

curl --location --request PUT 'https://gw.onemap8.com/api/devices/<integer>/accumulators' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"deviceId": <integer>,
"totalDistance": <number>,
"hours": <number>
}'

Response

No content

POST/devices/{id}/image

Upload device image

Upload or update a device image. The image will be stored and associated with the device.

Authorizations

BasicAuth or ApiKey

Name
BasicAuth
Type
scheme
Description
HTTP Authorization Scheme: basic
Name
ApiKey
Type
scheme
Description
HTTP Authorization Scheme: bearer

Path parameters

Name
id
Type
integer required
Description
Device ID

Request body schema

Name
image/*
Type
schema
Description
Binary image data (JPEG, PNG, etc.)

Responses

Name
200
Type
success
Description
Name
text/plain
Type
response schema
Description
Filename of the uploaded image (e.g., device.png)
Name
400
Type
error
Description
Invalid image type or size
Name
404
Type
error
Description
Device not found

Request

POST

/devices/{id}/image

curl --location 'https://gw.onemap8.com/api/devices/<integer>/image' \
--header 'Content-Type: image/png' \
--header 'Authorization: Basic {your_access_token}' \
--data-binary '@/path/to/image.png'

Response

device.png