API docs by Redocly

Zoellner ZCloud API (3.3.0)

Download OpenAPI specification:

The REST API for Zoellner ZCloud

AccountManagement

Management of users

Get a list of users

Returns a list of all users the current user has access to.

Authorizations:
bearerAuth
query Parameters
companyId
number

Users of which company should be returned. Only for SuperAdmin.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new user

Creates a new user. The new user will be returned in the response body.

Authorizations:
bearerAuth
Request Body schema: application/json

The new user data

email
required
string <email>

The email address of the user

givenName
required
string

The first name of the user

familyName
required
string

The surname of the user

companyId
required
integer

The id of the company the user belongs to

role
required
string
Enum: "SuperAdmin" "CompanyAdmin" "OuAdmin" "OuUser" "BaseUser"

The user role for the new user

Responses

Request samples

Content type
application/json
{
  • "givenName": "Max",
  • "familyName": "Muster",
  • "email": "max.muster@example.org",
  • "companyId": 2,
  • "role": "CompanyAdmin"
}

Response samples

Content type
application/json
{
  • "id": "1114f98a-d15e-4195-804c-c90376a2fb89",
  • "givenName": "Max",
  • "familyName": "Muster",
  • "email": "max.muster@example.org",
  • "companyId": 2,
  • "roles": [
    ],
  • "roleBindings": [
    ]
}

Get a single user

Returns the specified user

Authorizations:
bearerAuth
path Parameters
userId
required
string

The user id set by the identity provider

Responses

Response samples

Content type
application/json
{
  • "id": "1114f98a-d15e-4195-804c-c90376a2fb89",
  • "givenName": "Max",
  • "familyName": "Muster",
  • "email": "max.muster@example.org",
  • "companyId": 2,
  • "roles": [
    ],
  • "roleBindings": [
    ]
}

Update a user

Updates a user.

Authorizations:
bearerAuth
path Parameters
userId
required
string

The user id set by the identity provider

Request Body schema: application/json

The updated user data

email
string or null <email>

The email address of the user

givenName
string or null

The first name of the user

familyName
string or null

The surname of the user

password
string or null
role
string or null
Enum: "SuperAdmin" "CompanyAdmin" "OuAdmin" "OuUser" "BaseUser"

The user role for the new user

Responses

Request samples

Content type
application/json
{
  • "givenName": "Max",
  • "familyName": "Muster",
  • "email": "max.muster@example.org",
  • "role": "CompanyAdmin"
}

Delete a user

Deletes the user

Authorizations:
bearerAuth
path Parameters
userId
required
string

The user id set by the identity provider

Responses

DeviceManagement

Management of devices

Get a list of devices assigned to the company

Returns the full list of typed devices of any type.

Required Permissions

  • companies:read
Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Overwrite the current assignment list of company devices.

Updates the devices of a company. Previously assigned devices not included in the request will be unassigned.

Required Permissions

  • companies:update
Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Request Body schema: application/json

The list of devices to set for the company

Array
id
required
integer

The id of the device

displayName
string

The device's display name.

serialNumber
required
string <numeric>

The serial number of the device the tracker is attached to.

trackerSerialNumber
required
string <numeric>

The serial number of the tracker

deviceType
required
integer
Enum: 0 1 2 3 4 5 6 7 8 9 10 11 404
deviceName
required
integer
Enum: 0 1 2 3 4 5
deviceVariant
integer
Enum: 0 1 2 3 4 5 6 7
deviceHint
integer
Enum: 0 1

A device-dependent hint. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

itemNumber
string

Optional item number of the given device.

internalDeviceType
string
Enum: "unknown-device" "central-unit" "warning-unit" "detector-unit" "railroad-crossing-unit"

The internal device type on the zcloud

companyName
string

The name of the company a device is assigned to

companyId
integer

The id of the company a device is assigned to

deviceState
integer
Enum: 0 1 2 3 4 5 6
isOffline
boolean

Whether the device is offline

updateStatus
integer
Enum: 0 1 2 3 4 5 6

The update status of the device. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

updatePercentage
integer

The update progress in full percent.

updateDate
string <date-time>

The time when the device last received a firmware update

lastUpdated
string <date-time>

The time when the device last received a telemetry message

trackerSoftwareRevision
string <numeric>

The current version of the tracker software.

deviceRevision
integer

The current version of the device software.

hardwareRevision
string

The current version of the hardware.

radioId
integer

The radio id of the device.

trainCounter
integer

The current train counter.

annualCheckDate
string <date-time>

When the device was marked for an update.

distance
number

The (floating point) distance between a device and the connected central unit.

operatingMode
integer
Enum: 0 1

The operating mode of a device, depending on the device type. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

latitude
number

The latitude of the device's geo position.

longitude
number

The longitude of the device's geo position.

longRadioStrength
number

The strength of the long radio signal.

mobileRadioStrength
number

The strength of the mobile radio signal.

warningstate
integer
Enum: 0 1 2 3 4 5 6

The current warning state of the device. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

longRadioChannel
integer
Enum: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

The long radio channel of the device. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

longRadioChannelString
string or null

The long radio channel of the device as a string, instead of an enumerated value. Should override longRadioChannel, if set!

powerSupplyMode
integer
Enum: 0 1 2 3

The power supply mode of the device. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

object

Details on the device's power supply.

typeTranslatedName
string

Full name of the device.

gpsPrecision
number

The GPS precision of the positioning.

deviceOffline
boolean

Whether or not the device is offline

isAssignedToUnit
boolean

Whether or not the device is assigned to an organizational unit (group or branch) within a company.

lastGpsFix
string <date-time>

When the last gps fix was acquired.

positioningMode
string
Enum: "gps" "lte" "none"

The strategy used to position the device. Attention This is a legacy functionality and likely to be removed in the future.

isInstallation
boolean

Whether the device is an installation or a single device.

connectedCentralUnit
integer or null

The connected central unit.

manualDetection
boolean or null

Whether to use manual/mobile or stationary detection.

tiChannels
Array of booleans or null

The track interface channel status (enabled/disabled).

installationSystemState
integer or null
Enum: 0 1 2 3 4 5 6 7

The system state of a railroad crossing unit. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

activeDeviceCount
integer or null

The number of active devices within an installation.

Array of objects or null

The devices within the railroad crossing installation.

areaSwitch
boolean or null

The warning unit area switch.

acousticMode
integer
Enum: 0 1 2
acousticSignalCharacteristics
integer or null
Enum: 0 1 2 3 4

The acoustic signal characteristics. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

acousticVolume
number or null

The volume of the acoustic warning unit.

shortRadioWarningGroup
integer or null
Enum: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

The short radio warning group of the unit. Enum values defined at https://confluence.cloudflight.io/display/ZBIWAS/Struktur+Telemetriedaten

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Get a list of devices

Returns a list of all devices the user has access to

Authorizations:
bearerAuth
query Parameters
companyId
integer

Devices of which company should be returned. Only for SuperAdmin.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single device

Returns the specified device

Authorizations:
bearerAuth
path Parameters
deviceId
required
integer

The device id

Responses

Response samples

Content type
application/json
{
  • "id": 164,
  • "displayName": "ZRC-10",
  • "serialNumber": "1250859108250",
  • "trackerSerialNumber": "746281956182",
  • "deviceType": 1,
  • "deviceName": 1,
  • "deviceVariant": 2,
  • "deviceHint": 0,
  • "itemNumber": "0815",
  • "internalDeviceType": "central-unit",
  • "companyName": "TestCorp",
  • "companyId": 17,
  • "deviceState": 2,
  • "isOffline": true,
  • "updateStatus": 0,
  • "updatePercentage": 0,
  • "updateDate": "2024-05-23T12:46:05+0000",
  • "lastUpdated": "2024-05-23T12:46:05+0000",
  • "trackerSoftwareRevision": "426",
  • "deviceRevision": 8,
  • "hardwareRevision": 5,
  • "radioId": 12505,
  • "trainCounter": 5,
  • "annualCheckDate": "2024-10-12T08:00:00+0000",
  • "distance": 285.56,
  • "operatingMode": 0,
  • "latitude": 54.323334,
  • "longitude": 10.139444,
  • "longRadioStrength": 10,
  • "mobileRadioStrength": 5,
  • "warningState": 1,
  • "longRadioChannel": 13,
  • "powerSupplyMode": 3,
  • "powerSupply": {
    },
  • "typeTranslatedName": "ZRC-10",
  • "gpsPrecision": 5,
  • "deviceOffline": false,
  • "isAssignedToUnit": true,
  • "lastGpsFix": "2024-05-23T12:46:05+0000",
  • "positioningMode": "gps",
  • "isInstallation": false
}

Get device logs

Returns the logs of the specified device. Depending on the request parameters, this endpoint can return a json response or a csv or pdf file export of the logs.

Authorizations:
bearerAuth
path Parameters
deviceId
required
integer

The device id

query Parameters
format
string
Default: "json"
Enum: "json" "csv" "pdf"

The response log format

start
string

The start date

end
string

The end date

category
integer

The log entry category

offset
required
integer

The offset

limit
required
integer

The limit

Responses

Response samples

Content type
{
  • "entries": [
    ],
  • "categoryCount": [
    ],
  • "dateCount": [
    ]
}

Get a list of movement alerts for the current user

Returns a list of all movement alerts for the current user - user ID is inferred from the session

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new movement alert

Creates a new movement alert for a device for the current user

Authorizations:
bearerAuth
Request Body schema: application/json

The movement alert data

deviceId
required
integer

The database ID of the device the alert is to set for

origin
required
string

The comma-separated (latitude, longitude) point of origin for calculating the movement threshold

radius
required
integer

The desired movement alert threshold in meters - min 50, max 2000

Responses

Request samples

Content type
application/json
{
  • "deviceId": 113,
  • "origin": "54.320827, 10.039519",
  • "radius": 250
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "userId": "a6d7915c-b4ee-4e29-8d85-b6f7414804f2",
  • "deviceId": 119,
  • "origin": "54.320827, 10.039519",
  • "radius": 250,
  • "isActive": false
}

Delete the specified movement alert

Deletes the database entity

Authorizations:
bearerAuth
path Parameters
alertId
required
integer

The movement alert id

Responses

Update a movement alert

Updates the given movement alert

Authorizations:
bearerAuth
path Parameters
alertId
required
integer

The movement alert id

Request Body schema: application/json

The updated movement alert data

origin
string

The comma-separated (latitude, longitude) point of origin for calculating the movement threshold

radius
integer

The desired movement alert threshold in meters - min 50, max 2000

Responses

Request samples

Content type
application/json
{
  • "radius": 300
}

Overwrite the current assignment list of devices for an organizational unit.

Updates the devices of an org unit. Previously assigned devices not included in the request will be unassigned.

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

Request Body schema: application/json

The updated device assignments for the org unit

Array
required
Array of objects

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Assigns a device to a specific organizational unit

Creates a new device assignment of the given device to the org unit. A device can only be assigned to one top-level org unit at a time, and obviously the org unit must be within the company the device is assigned to.

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

deviceId
required
integer

The device id

Responses

Removes a device from an organizational unit

Deletes the given assignment of a device to an org unit, if it exists

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

deviceId
required
integer

The device id

Responses

Get a list of systems

Gets the list of systems. Systems are inferred by finding groups of devices with the same radio id connected to a central unit. They are not stored in the database directly, but need to be dynamically queried, so expect this endpoint to not achieve maximum performance. Systems are only valid if all included devices are assigned to the same company and org unit.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the system with the given system id (radio id)

Returns the specified system

Authorizations:
bearerAuth
path Parameters
systemId
required
number <int32>

The id of the system

Responses

Response samples

Content type
application/json
{
  • "id": 1122,
  • "systemName": 2154818,
  • "devicesCount": 2,
  • "trainCounter": 0,
  • "systemState": 2,
  • "warningState": 0,
  • "devices": [ ]
}

CompanyManagement

Management of companies

Get a list of companies

Returns a list of all companies the user has access to. For anyone except SuperAdmin users, this is just their own company.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new company

Creates a new company. The new company will be returned in the response body.

Authorizations:
bearerAuth
Request Body schema: application/json

The new company data

name
required
string

The company name

address
required
string

The company address information

phone
required
string

The company phone number

fax
required
string

The company fax number

mail
required
string <email>

The company mail address

miscellaneous
string

Further notes on the company

location
string

The location (country) of the company's HQ

Responses

Request samples

Content type
application/json
{
  • "name": "Cloudflight Germany",
  • "address": "Am-Kiel-Kanal 1, 24106 Kiel",
  • "phone": "+49 123456789",
  • "fax": "+49 123456789",
  • "mail": "operations@macio-devops.de",
  • "miscellaneous": "Test company"
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "name": "Cloudflight Germany",
  • "address": "Am-Kiel-Kanal 1, 24106 Kiel",
  • "phone": "+49 123456789",
  • "fax": "+49 123456789",
  • "mail": "operations@macio-devops.de",
  • "miscellaneous": "Test company"
}

Get a single company

Returns the specified company

Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Responses

Response samples

Content type
application/json
{
  • "id": 2,
  • "name": "Cloudflight Germany",
  • "address": "Am-Kiel-Kanal 1, 24106 Kiel",
  • "phone": "+49 123456789",
  • "fax": "+49 123456789",
  • "mail": "operations@macio-devops.de",
  • "miscellaneous": "Test company"
}

Update a company

Updates a company

Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Request Body schema: application/json

The updated company data

name
required
string

The company name

address
required
string

The company address information

phone
required
string

The company phone number

fax
required
string

The company fax number

mail
required
string <email>

The company mail address

miscellaneous
string

Further notes on the company

location
string

The location (country) of the company's HQ

Responses

Request samples

Content type
application/json
{
  • "name": "Cloudflight Germany",
  • "address": "Am-Kiel-Kanal 1, 24106 Kiel",
  • "phone": "+49 123456789",
  • "fax": "+49 123456789",
  • "mail": "operations@macio-devops.de",
  • "miscellaneous": "Test company"
}

Delete a company

Deletes the company

Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Responses

Get the company settings for a single company

Returns the company settings config object of the given company

Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Responses

Response samples

Content type
application/json
{
  • "settings": {
    },
  • "current": {
    }
}

Creates company settings for a company.

Creates a fresh set of company settings for a company.

Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Request Body schema: application/json

The company settings

required
object

The company settings

required
object

The current quota usage of the company

Responses

Request samples

Content type
application/json
{
  • "settings": {
    },
  • "current": {
    }
}

Response samples

Content type
application/json
{
  • "settings": {
    },
  • "current": {
    }
}

Update the company settings of a company

Updates the company settings of the given company, overriding any old settings

Authorizations:
bearerAuth
path Parameters
companyId
required
integer

The company id

Request Body schema: application/json

The updated company settings config object

required
object

The company settings

required
object

The current quota usage of the company

Responses

Request samples

Content type
application/json
{
  • "settings": {
    },
  • "current": {
    }
}

Get the current company settings of all companies

Returns a list of company settings config objects

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of organizational units

Returns a list of all org units the user has access to

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new organizational unit

Creates a new org unit of the given type within a company.

Authorizations:
bearerAuth
Request Body schema: application/json

The org unit data

companyId
required
number

The id of the company this OU belongs to

parentUnitId
number

The id of the parent OU; this only applies to group units within a branch of the company

unitType
string
Enum: "Branch" "Group"

The type of organizational unit

name
string

The name of the OU

Responses

Request samples

Content type
application/json
{
  • "companyId": 2,
  • "parentUnitId": 17,
  • "unitType": "Group",
  • "name": "Cluster D"
}

Response samples

Content type
application/json
{
  • "id": 17,
  • "companyId": 2,
  • "parentUnitId": null,
  • "unitType": "Branch",
  • "name": "Kiel",
  • "users": [ ],
  • "devices": [ ],
  • "subUnits": [ ]
}

Get a single organizational unit

Returns the specified org unit

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

Responses

Response samples

Content type
application/json
{
  • "id": 17,
  • "companyId": 2,
  • "parentUnitId": null,
  • "unitType": "Branch",
  • "name": "Kiel",
  • "users": [ ],
  • "devices": [ ],
  • "subUnits": [ ]
}

Update an organizational unit

Updates the given org unit

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

Request Body schema: application/json

The updated org unit data

companyId
required
number

The id of the company this OU belongs to

parentUnitId
number

The id of the parent OU; this only applies to group units within a branch of the company

unitType
string
Enum: "Branch" "Group"

The type of organizational unit

name
string

The name of the OU

Responses

Request samples

Content type
application/json
{
  • "companyId": 2,
  • "parentUnitId": 17,
  • "unitType": "Group",
  • "name": "Cluster D"
}

Delete an organizational unit

Deletes the org unit

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

Responses

Overwrite the current assignment list of users for an organizational unit.

Updates the users (members) of an org unit and / or their according role bindings. Previously assigned users not included in the request will be unassigned.

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

Request Body schema: application/json

The updated user assignments for the org unit

Array
required
Array of objects

The list of user assignments to add

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Assigns a user to a specific organizational unit

Creates a new user role assignment of the given user to the org unit with the given role. A user can only be assigned to one top-level org unit at a time, and obviously the org unit must be within the company the user is a member of.

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

userId
required
integer

The user id

Request Body schema: application/json

The role to assign the user with

role
required
string
Enum: "OuAdmin" "OuUser" "BaseUser"

Responses

Request samples

Content type
application/json
{
  • "role": "OuAdmin"
}

Removes a user from an organizational unit

Deletes the given assignment of a user to an org unit, if it exists

Authorizations:
bearerAuth
path Parameters
ouId
required
integer

The org unit id

userId
required
integer

The user id

Responses

Events

Handling of subscription to device events

Setup the basic SignalR connection used to subscribe to live updates

Returns the connection info for live updates

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "accessToken": "string"
}

Subscribes to device events / live updates

Creates a new subscription for the given org unit or system

Authorizations:
bearerAuth
Request Body schema: application/json

The subscription data

type
required
integer
Enum: 0 1

The type of subscription (0 = System / 1 = OrgUnit)

connectionId
required
string <uuid>

The uuid to identify the connection

id
required
integer

The id of the system or org unit

firebaseDeviceId
string

The token of the firebase client for push notifications

Responses

Request samples

Content type
application/json
{
  • "type": 1,
  • "connectionId": "153fcb86-debe-4ea0-8c78-6f0aac1ef9d2",
  • "id": 17,
  • "firebaseDeviceId": "aelighue09aWSA"
}

Response samples

Content type
application/json
{
  • "userId": "abc12345",
  • "type": 1,
  • "connectionId": "153fcb86-debe-4ea0-8c78-6f0aac1ef9d2",
  • "id": 17,
  • "firebaseDeviceId": "aelighue09aWSA",
  • "timestamp": "2023-12-21T11:50:29.000Z"
}

Unsubscribes from device events / live updates

Removes the subscription for the given org unit or system

Authorizations:
bearerAuth
Request Body schema: application/json

The subscription data

userId
string

The unique id of the subscribed user / client

type
required
integer
Enum: 0 1

The type of subscription (0 = System / 1 = OrgUnit)

connectionId
required
string <uuid>

The uuid to identify the connection

id
required
integer

The id of the system or org unit

firebaseDeviceId
string

The token of the firebase client for push notifications

timestamp
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "userId": "abc12345",
  • "type": 1,
  • "connectionId": "153fcb86-debe-4ea0-8c78-6f0aac1ef9d2",
  • "id": 17,
  • "firebaseDeviceId": "aelighue09aWSA",
  • "timestamp": "2023-12-21T11:50:29.000Z"
}

System

General functionality required for the system

Get the backend version

Returns the backend version

Authorizations:
bearerAuth

Responses