Management API Reference

The Management API is responsible for handling users, companies, services, networks and devices. Moreover it can be used to setup telemetry data sinks. Although this page describes the pure REST API for managing these entities the recommended way to reach the management API is though client libraries that are currently available for .NET-based devices and devices running Linux (Raspberry Pi, etc.).

The API is versioned and uses HTTP Cookie authentication. The reason for using Cookie authentication is because most of the times this API will be used from a browser running JavaScript. All requests and responses are in JSON format.

In the following description you will see some placeholders:

  • <APIURL>: the full url root of the API. Like api.thriot.io/management
  • <USERID>: 32 characters long unique identifier for user
  • <COMPANYID>, <SERVICEID>, <NETWORKID>, <DEVICEID>: 32 characters long unique identifier for company, service, nework or device
  • <APIKEY>: 32 characters long crypto-random key

The name of the authentication cookie is ThriotMgmtAuth .

 User management

User registration
Description New user registration
Url
<APIURL>/v1/users/register
Verb POST
Auth cookie not required
Request object
{
 "Name": "<FULLNAME>",
 "Email": "<EMAIL-ADDRESS>",
 "Password": "<PASSWORD>"
}
Response object If the system requires email activation then the register API returns the following object:

{
 "NeedsActivation": true
}

If there is no requirement for email-based activation then the register API returns the Basic authentication token:

{
 "NeedsActivation": false
}

A cookie called ThriotMgmtAuth is also returned after successful authentication which must be passed to any subsequent calls that require authentication.

HTTP Response code 200 (OK)
Error codes 400 (Bad request): input parameter or validation error
409 (Conflict): the email address already exists in the database

 

User activation
Description Activate user. This is a link embedded into the welcome email after registration.
Url
<APIURL>/v1/users/<USERID>/activate/<ACTIVATIONCODE>
Verb GET
Auth cookie not required
Request object none
Response object none. A cookie called ThriotMgmtAuth is also returned after successful operation which must be passed to any subsequent calls that require authentication.
HTTP Response code 204 (No content)
Error codes 400 (Bad request): input parameter or validation error
403 (Forbidden): Some activation error like already activated, bad token, etc.

 

User login
Description Login an already registered user. If activation is required by the system, the user must be first activated to successfully login.
Url
<APIURL>/v1/users/login
Verb POST
Auth cookie not required
Request object
{
 "Email": "<EMAIL-ADDRESS>",
 "Password": "<PASSWORD>"
}
Response object
none

A cookie called ThriotMgmtAuth is returned after successful authentication which must be passed to any subsequent calls that require authentication.

HTTP Response code 204 (No Content)
Error codes 401 (Unauthorized): Invalid email or password specified
403 (Forbidden): Activation required

 

User logoff
Description Logoff the user. It just means that an invalidated cookie is returned.
Url
<APIURL>/v1/users/logoff
Verb POST
Auth cookie not required
Request object
none
Response object
none

A cookie called ThriotMgmtAuth that is already expired.

HTTP Response code 204 (No Content)
Error codes no

 

Resend activation email
Description When the user requires activation and the activation email didn’t arrive then  resend the activation email
Url
<APIURL>/v1/users/resendActivationEmail
Verb POST
Auth cookie none
Request object
{
 "Email": "<EMAIL-ADDRESS>"
}
Response object none
HTTP Response code 204 (No Content)
Error codes 401 (Unauthorized): Occurs when there is an active logged in user.
400 (Bad request): invalid parameters
403 (Forbidden): when the user is activated

 

Send Forgot Password Email
Description Send a forgot password email to an email address
Url
<APIURL>/v1/users/sendForgotPasswordEmail
Verb POST
Auth cookie none
Request object
{
 "Email": "<EMAIL-ADDRESS>"
}
Response object none
HTTP Response code 204 (No Content)
Error codes 401 (Unauthorized): Occurs when there is an active logged in user.
400 (Bad request): invalid parameters
403 (Forbidden): when the user is not yet activated

 

Reset password
Description Reset password. This is initiated by the send forgot password operation.
Url
<APIURL>/v1/users/resetPassword
Verb POST
Auth cookie none
Request object
{
  "UserId": "<USERID>",
  "ConfirmationCode": "<CONFIRMATIONCODE>",
  "Password": "<PASSWORD>"
}
Response object
none
HTTP Response code 204 (No Content)
Error codes 401 (Unauthorized): Occurs when there is an active logged in user.
400 (Bad request): invalid parameters
403 (Forbidden): when the user is not yet activated or invalid confirmation code

 

Change password
Description Change the currently logged in user’s password
Url
<APIURL>/v1/users/changePassword
Verb POST
Auth cookie required
Request object
{
"CurrentPassword": "<PASSWORD>",
"NewPassword": "<PASSWORD>"
}
Response object
none
HTTP Response code 204 (No Content)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated. The current password doesn’t match
400 (Bad request): invalid parameters, not quite complex password

 

 Get current user details
Description Get details for the currently logged in user
Url
<APIURL>/v1/users/me
Verb GET
Auth cookie required
Request object none
Response object
{
 "Id": "<USERID>",
 "Name": "<FULLNAME>",
 "Email": "<EMAIL-ADDRESS>"
}
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.

 

Find and user in the system by email address
Description Find user in the system database by email address.
Url
<APIURL>/v1/users/byemail/<EMAIL-ADDRESS>/

Do not forget to Urlencode  the email address in the url and add a trailing / at the end of the url.

Verb GET
Auth cookie required
Request object none
Response object If found:

{
 "Id": "<USERID>",
 "Name": "<FULLNAME>",
 "Email": "<EMAIL-ADDRESS>"
}

If not found:

null
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.

 

 Telemetry metadata

List telemetry data sinks
Description List all telemetry data sinks metadata available in the system
Url
<APIURL>/v1/telemetryMetadata
Verb GET
Auth cookie required
Request object none
Response object
[{
 "Name": "<NAME>",
 "Description": "<DESCRIPTION>",
 ["<PARAM1>", "<PARAM2>", ...]
}, ...]
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.

 

Info service

Get Public/web-related runtime parameters
Description Gives basic information about the public/web-related runtime parameters of the service
Url
<APIURL>/v1/info
Verb GET
Auth cookie required
Request object none
Response object
{
 "ServiceProfile": "<SERVICEPROFILE>",
 "PrebuiltCompany": "<COMPANYID>",
 "PrebuiltService": "<SERVICEID>",
 "CanCreateCompany": true/false,
 "CanDeleteCompany": true/false,
 "CanCreateService": true/false,
 "CanDeleteService": true/false
}

ServiceProfile: ServiceProvider/SingleCompany/SingleService
PrebuiltCompany: The automatically registered unique company in the system in SingleCompany or SingleService mode
PrebuiltService: The automatically registered unique service in the system in SingleService mode
Can*: Can create/delete company/service. This is based on the operation modes mentioned above.

HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.

 

Get API/Website endpoint Urls
Description Getr API/Website endpoint Urls
Url
<APIURL>/v1/info/url
Verb GET
Auth cookie required
Request object none
Response object
{
 "WebsiteUrl": "<URL>",
 "ManagementApiUrl": "<URL>",
 "PlatformApiUrl": "<URL>",
 "PlatformWsUrl": "<URL>",
 "ReportingApiUrl": "<URL>"
}
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.

 

Company management

List companies
Description List all companies of the user can access. Such companies were either created by the user or received permission from other user.
Url
<APIURL>/v1/companies
Verb GET
Auth cookie required
Request object none
Response object
[{
 "Id": "<COMPANYID>",
 "Name": "<NAME>",
}, ...]
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.

 

Get company
Description Get a company by id
Url
<APIURL>/v1/companies/<COMPANYID>
Verb GET
Auth cookie required
Request object none
Response object
{
 "Id": "<COMPANYID>",
 "Name": "<NAME>",
 "TelemetryDataSinkSettings": [
   "Incoming": [
     {
       "SinkName": "<DATASINKNAME>",
       {"Param1": "Value1", "Param2": "Value2", ...}
     }, ...
   ]
  ]
}
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve company details
404 (Not found): The given company not found

 

Create company
Description Create new company
Url
<APIURL>/v1/companies
Verb POST
Auth cookie required
Request object
{
 "Name": "<NAME>"
}
Response object
"<COMPANYID>"
HTTP Response code 200 (OK)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Cannot create company. Not in ServiceProvider operation mode.

 

Update company
Description Update company
Url
<APIURL>/v1/companies
Verb PUT
Auth cookie required
Request object
{
 "Id": "<COMPANYID>"
 "Name": "<NAME>"
}
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to update the company
404 (Not found): Company not found.

 

Delete company
Description Delete company
Url
<APIURL>/v1/companies/<COMPANYID>
Verb DELETE
Auth cookie required
Request object none
Response object none
HTTP Response code 204 (No content)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to delete the company
404 (Not found): Company not found.

 

List services of a company
Description List services under a company given by id
Url
<APIURL>/v1/companies/<COMPANYID>/services
Verb GET
Auth cookie required
Request object none
Response object
[{
 "Id": "<SERVICEID>",
 "Name": "<NAME>"
}, ...
]
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve services
404 (Not found): The given company not found

 

List users of a company
Description List users who can see and manage the company given by id
Url
<APIURL>/v1/companies/<COMPANYID>/users
Verb GET
Auth cookie required
Request object none
Response object
[{
 "Id": "<USERID>",
 "Name": "<NAME>"
}, ...
]
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve users
404 (Not found): The given company not found

 

Add user to a company
Description Add user to a company where the user will have admin permissions
Url
<APIURL>/v1/companies/adduser
Verb POST
Auth cookie required
Request object
{
 "CompanyId": "<COMPANYID>",
 "UserId": "<USERID>"
}
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): The current user has no admin permission on the company.

 

Add or modify the incoming telemetry data sinks
Description Add or modify the incoming telemetry data sinks. The data sinks and required parameters can be queried using the TelemetryMetadata service
Url
<APIURL>/v1/companies/<COMPANYID>/incomingTelemetryDataSinks
Verb POST
Auth cookie required
Request object
[
 {
   "SinkName": "<DATASINKNAME>",
   {"Param1": "Value1", "Param2": "Value2", ...}
 }, ...
]
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): The current user has no admin permission on the company.

 

Service management

List services of a company
Description List all services under a given company. Endpoint was already described under company management section.

 

Get service
Description Get a service by id
Url
<APIURL>/v1/services/<SERVICEID>
Verb GET
Auth cookie required
Request object none
Response object
{
 "Id": "<SERVICEID>",
 "Name": "<NAME>",
 "CompanyId": "<COMPANYID>",
 "ApiKey": "<APIKEY>",
 "TelemetryDataSinkSettings": [
   "Incoming": [
     {
       "SinkName": "<DATASINKNAME>",
       {"Param1": "Value1", "Param2": "Value2", ...}
     }, ...
   ]
  ]
}
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve service details
404 (Not found): The given service not found

 

Create service
Description Create a new service under the company specified by the request object
Url
<APIURL>/v1/services
Verb POST
Auth cookie required
Request object
{
 "CompanyId": "<COMPANYID>"
 "Name": "<NAME>"
}
Response object
"<SERVICEID>"
HTTP Response code 200 (OK)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Cannot create service. Not in ServiceProvider, SingleCompany operation mode.

 

Update service
Description Update service
Url
<APIURL>/v1/services
Verb PUT
Auth cookie required
Request object
{
 "Id": "<SERVICEID>",
 "Name": "<NAME>"
}
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to update the service
404 (Not found): Service not found.

 

Delete service
Description Delete service
Url
<APIURL>/v1/services/<SERVICEID>
Verb DELETE
Auth cookie required
Request object none
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to delete the service
404 (Not found): Service not found.

 

List networks of a service
Description List networks under a service given by id
Url
<APIURL>/v1/services/<SERVICEID>/networks
Verb GET
Auth cookie required
Request object none
Response object
[{
 "Id": "<NETWORKID>",
 "Name": "<NAME>"
}, ...
]
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve networks
404 (Not found): The given service not found

 

Add or modify the incoming telemetry data sinks
Description Add or modify the incoming telemetry data sinks. The data sinks and required parameters can be queried using the TelemetryMetadata service
Url
<APIURL>/v1/services/<SERVICEID>/incomingTelemetryDataSinks
Verb POST
Auth cookie required
Request object
[
 {
  "SinkName": "<DATASINKNAME>",
  {"Param1": "Value1", "Param2": "Value2", ...}
 }, ...
]
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): The current user has no admin permission on the service.

 

Network management

List networks of a service
Description List all networks of a service. The endpoint was already described under the service management section.

 

Get network
Description Get a network by id
Url
<APIURL>/v1/networks/<NETWORKID>
Verb GET
Auth cookie required
Request object none
Response object
{
 "Id": "<NETWORKID>",
 "Name": "<NAME>",
 "CompanyId": "<COMPANYID>",
 "ServiceId": "<SERVICEID>",
 "ParentNetworkId": "<NETWORKID>",
 "NetworkKey": "<APIKEY>",
 "TelemetryDataSinkSettings": [
   "Incoming": [
     {
       "SinkName": "<DATASINKNAME>",
       {"Param1": "Value1", "Param2": "Value2", ...}
     }, ...
   ]
  ]
}

Query a network with the given id. If the network was created under an other network then there is a ParentNetworkId field in the response object. Otherwise the field is missing.

HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve network details
404 (Not found): The given networknot found

 

Create network
Description Create a new network under the service or other network specified by the request object
Url
<APIURL>/v1/networks
Verb POST
Auth cookie required
Request object
{
 "CompanyId": "<COMPANYID>",
 "ServiceId": "<SERVICEID>",
 "NetworkId": "<NETWORKID>",
 "Name": "<NAME>"
}

The NetworkId parameter should be present only in case when the network should be created under an other network otherwise the field should not be specified.

Response object
"<NETWORKID>"
HTTP Response code 200 (OK)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Cannot create network.

 

Update network
Description Update network
Url
<APIURL>/v1/networks
Verb PUT
Auth cookie required
Request object
{
 "Id": "<NETWORKID>",
 "Name": "<NAME>"
}
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to update the network
404 (Not found): Network not found.

 

Delete network
Description Delete network
Url
<APIURL>/v1/networks/<NETWORKID>
Verb DELETE
Auth cookie required
Request object none
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to delete the network
404 (Not found): Network not found.

 

List networks of a network
Description List networks under a network given by id
Url
<APIURL>/v1/networks/<NETWORKID>/networks
Verb GET
Auth cookie required
Request object none
Response object
[{
 "Id": "<NETWORKID>",
 "Name": "<NAME>"
}, ...
]
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve network
404 (Not found): The given network not found

 

List devices of a network
Description List devices under a network given by id
Url
<APIURL>/v1/networks/<NETWORKID>/devices
Verb GET
Auth cookie required
Request object none
Response object
[{
 "Id": "<DEVICEID>",
 "Name": "<NAME>"
}, ...
]
HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve network
404 (Not found): The given network not found

 

Add or modify the incoming telemetry data sinks
Description Add or modify the incoming telemetry data sinks. The data sinks and required parameters can be queried using the TelemetryMetadata service
Url
<APIURL>/v1/networks/<NETWORKID>/incomingTelemetryDataSinks
Verb POST
Auth cookie required
Request object
[
 {
  "SinkName": "<DATASINKNAME>",
  {"Param1": "Value1", "Param2": "Value2", ...}
 }, ...
]
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): The current user has no admin permission on the network.

 

Device management

List devices of a network
Description List all devices of a network. The endpoint is already described under the network management section.

 

Get device
Description Get a device by id
Url
<APIURL>/v1/devices/<DEVICEID>
Verb GET
Auth cookie required
Request object none
Response object
{
 "Id": "<DEVICEID>",
 "Name": "<NAME>",
 "CompanyId": "<COMPANYID>",
 "ServiceId": "<SERVICEID>",
 "NetworkId": "<NETWORKID>",
 "DeviceKey": "<APIKEY>",
 "NumericId": "<LONG>"
}

 

HTTP Response code 200 (OK)
Error codes 401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Forbidden to retrieve device details
404 (Not found): The given device not found

 

Create device
Description Create a new device under the network specified by the request object
Url
<APIURL>/v1/devices
Verb POST
Auth cookie required
Request object
{
 "CompanyId": "<COMPANYID>",
 "ServiceId": "<SERVICEID>",
 "NetworkId": "<NETWORKID>",
 "Name": "<NAME>"
}

 

Response object
"<DEVICE>"
HTTP Response code 200 (OK)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbiddden): Cannot create device.

 

Update device
Description Update device
Url
<APIURL>/v1/devices
Verb PUT
Auth cookie required
Request object
{
 "Id": "<DEVICEID>",
 "Name": "<NAME>"
}
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to update the device
404 (Not found): Device not found.

 

Delete device
Description Delete device
Url
<APIURL>/v1/devices/<DEVICEID>
Verb DELETE
Auth cookie required
Request object none
Response object none
HTTP Response code 200 (Ok)
Error codes 400 (Bad request): Input parameter validation error
401 (Unauthorized): Bad or missing auth header. User not authenticated.
403 (Forbidden): No permission to delete the device
404 (Not found): Device not found.

 

Advertisements