REST API Reference

Proxus IIoT platform provides a comprehensive REST API that allows you to programmatically manage and access all platform resources including devices, gateways, rules, alerts, and telemetry data. The API is built on OData protocol and includes JWT-based authentication. For more information about authentication methods, see Authentication Providers.

Authentication

The API uses JWT Bearer Token authentication. To obtain a token:

Send a POST request to the /api/Authentication/Authenticate endpoint with your credentials.
Include the returned token in the Authorization header of subsequent requests.

The authentication endpoint returns the JWT token as a plain string (not a JSON object).

# Obtain token
curl -X POST https://<your-server-url>/api/Authentication/Authenticate \
  -H "Content-Type: application/json" \
  -d '{"userName": "<username>", "password": "<password>"}'

# Use token in subsequent requests
curl -X GET https://<your-server-url>/api/odata/Device \
  -H "Authorization: Bearer <jwt_token>"

OData Endpoints

The Proxus API is primarily based on OData protocol, providing CRUD operations for all platform entities. Base URL: https://<your-server-url>/api/odata

Core Entities

Entity	Methods	Description
`Device`	GET, POST, PUT, PATCH, DELETE	Manage industrial devices and their configurations.
`Gateway`	GET, POST, PUT, PATCH, DELETE	Manage edge computing gateways.
`Alert`	GET, POST, PUT, PATCH, DELETE	Access and manage system alerts.
`Rule`	GET, POST, PUT, PATCH, DELETE	Configure and manage rule engine rules.
`RuleAction`	GET, POST, PUT, PATCH, DELETE	Define actions for rules.
`TargetProfile`	GET, POST, PUT, PATCH, DELETE	Configure target system profiles (MSSQL, PostgreSQL, ClickHouse, etc.).
`DeviceProfile`	GET, POST, PUT, PATCH, DELETE	Manage device communication profiles.
`NotificationChannel`	GET, POST, PUT, PATCH, DELETE	Configure notification channels.

Note: Telemetry (DeviceRawData) is not exposed via OData. Use the Telemetry API for SELECT queries. For more information about the telemetry storage system, see ClickHouse Integration.

Supported OData Operations

All entity endpoints support standard OData operations:

$filter: Filter results (e.g., /api/odata/Device?$filter=Name eq 'MyDevice')
$select: Select specific fields (e.g., /api/odata/Device?$select=Name,Status)
$top & $skip: Pagination (e.g., /api/odata/Device?$top=10&$skip=20)
$orderby: Sort results (e.g., /api/odata/Device?$orderby=Name)
$count: Get total count (e.g., /api/odata/Device/$count)

Telemetry API

For direct access to telemetry data stored in ClickHouse, use the dedicated telemetry endpoint:

Execute Telemetry Query

Endpoint: POST /api/Telemetry/execute
Description: Execute secure SELECT queries against ClickHouse telemetry data

Request Body:

{
  "query": "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
}

Query Parameters:
- maxRows: Maximum number of rows to return (default: 10000, max: 50000)

This endpoint includes SQL injection protection and enforces query limits (SELECT-only).

Response Format: ClickHouse returns JSONEachRow (NDJSON). Clients should read the response body as text or stream it line-by-line. For more information about the data structure and how it relates to the Unified Namespace, see Unified Namespace.

Swagger Documentation

For an interactive explorer of all available endpoints and schemas, access the Swagger UI on your local installation:

http://<your-server-url>/swagger

The Swagger UI provides:

Interactive endpoint testing
Request/response schema definitions
Example payloads for all API calls
OAuth 2.0 authentication flow

Code Examples

Here are examples of how to interact with the Proxus API using different programming languages:

Authentication

# Get JWT token
curl -X POST https://<your-server-url>/api/Authentication/Authenticate \
  -H "Content-Type: application/json" \
  -d '{"userName": "<username>", "password": "<password>"}'

Get Devices

# List all devices
curl -X GET https://<your-server-url>/api/odata/Device \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json"

Get Gateways

# List all gateways
curl -X GET https://<your-server-url>/api/odata/Gateway \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json"

Create Device

# Create a new device
curl -X POST https://<your-server-url>/api/odata/Device \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceName": "Example Device",
    "enabled": true,
    "status": "Active"
  }'

Create Gateway

# Create a new gateway
curl -X POST https://<your-server-url>/api/odata/Gateway \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Gateway",
    "status": "Active"
  }'

Query Telemetry Data

# Execute a telemetry query
curl -X POST https://<your-server-url>/api/Telemetry/execute \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
  }'

Authentication

// Get JWT token
const authResponse = await fetch('https://<your-server-url>/api/Authentication/Authenticate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userName: '<username>',
    password: '<password>'
  })
});

const token = (await authResponse.text()).replace(/"/g, "");

Get Devices

// List all devices
const devicesResponse = await fetch('https://<your-server-url>/api/odata/Device', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const devices = await devicesResponse.json();

Get Gateways

// List all gateways
const gatewaysResponse = await fetch('https://<your-server-url>/api/odata/Gateway', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const gateways = await gatewaysResponse.json();

Create Device

// Create a new device
const createResponse = await fetch('https://<your-server-url>/api/odata/Device', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deviceName: "Example Device",
    enabled: true,
    status: "Active"
  })
});

Create Gateway

// Create a new gateway
const createGatewayResponse = await fetch('https://<your-server-url>/api/odata/Gateway', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Example Gateway",
    status: "Active"
  })
});

Query Telemetry Data

// Execute a telemetry query
const telemetryResponse = await fetch('https://<your-server-url>/api/Telemetry/execute', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
  })
});

const telemetryText = await telemetryResponse.text(); // NDJSON (JSONEachRow)

Authentication

import requests
import json

# Get JWT token
auth_url = "https://<your-server-url>/api/Authentication/Authenticate"
auth_payload = {
    "userName": "<username>",
    "password": "<password>"
}

auth_response = requests.post(auth_url, json=auth_payload)
token = auth_response.text.strip('"')

Get Devices

# List all devices
devices_url = "https://<your-server-url>/api/odata/Device"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

devices_response = requests.get(devices_url, headers=headers)
devices = devices_response.json()

Get Gateways

# List all gateways
gateways_url = "https://<your-server-url>/api/odata/Gateway"
gateways_response = requests.get(gateways_url, headers=headers)
gateways = gateways_response.json()

Create Device

# Create a new device
create_url = "https://<your-server-url>/api/odata/Device"
device_payload = {
    "deviceName": "Example Device",
    "enabled": True,
    "status": "Active"
}

create_response = requests.post(create_url, json=device_payload, headers=headers)

Create Gateway

# Create a new gateway
gateway_url = "https://<your-server-url>/api/odata/Gateway"
gateway_payload = {
    "name": "Example Gateway",
    "status": "Active"
}

gateway_response = requests.post(gateway_url, json=gateway_payload, headers=headers)

Query Telemetry Data

# Execute a telemetry query
telemetry_url = "https://<your-server-url>/api/Telemetry/execute"
telemetry_payload = {
    "query": "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
}

telemetry_response = requests.post(telemetry_url, json=telemetry_payload, headers=headers)
telemetry_data = telemetry_response.text  # NDJSON (JSONEachRow)

Authentication

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

// Get JWT token
using var client = new HttpClient();
var authPayload = new {
    userName = "<username>",
    password = "<password>"
};

var json = JsonConvert.SerializeObject(authPayload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var authResponse = await client.PostAsync("https://<your-server-url>/api/Authentication/Authenticate", content);

var authToken = await authResponse.Content.ReadAsStringAsync();
string token = authToken.Trim().Trim('"');

Get Devices

// List all devices
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);

var devicesResponse = await client.GetAsync("https://<your-server-url>/api/odata/Device");
var devicesJson = await devicesResponse.Content.ReadAsStringAsync();
dynamic devices = JsonConvert.DeserializeObject(devicesJson);

Get Gateways

// List all gateways
var gatewaysResponse = await client.GetAsync("https://<your-server-url>/api/odata/Gateway");
var gatewaysJson = await gatewaysResponse.Content.ReadAsStringAsync();
dynamic gateways = JsonConvert.DeserializeObject(gatewaysJson);

Create Device

// Create a new device
var devicePayload = new {
    deviceName = "Example Device",
    enabled = true,
    status = "Active"
};

var deviceJson = JsonConvert.SerializeObject(devicePayload);
var deviceContent = new StringContent(deviceJson, Encoding.UTF8, "application/json");

var createResponse = await client.PostAsync("https://<your-server-url>/api/odata/Device", deviceContent);

Create Gateway

// Create a new gateway
var gatewayPayload = new {
    name = "Example Gateway",
    status = "Active"
};

var gatewayJson = JsonConvert.SerializeObject(gatewayPayload);
var gatewayContent = new StringContent(gatewayJson, Encoding.UTF8, "application/json");

var gatewayResponse = await client.PostAsync("https://<your-server-url>/api/odata/Gateway", gatewayContent);

Query Telemetry Data

// Execute a telemetry query
var telemetryPayload = new {
    query = "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
};

var telemetryJson = JsonConvert.SerializeObject(telemetryPayload);
var telemetryContent = new StringContent(telemetryJson, Encoding.UTF8, "application/json");

var telemetryResponse = await client.PostAsync("https://<your-server-url>/api/Telemetry/execute", telemetryContent);
var telemetryData = await telemetryResponse.Content.ReadAsStringAsync();

Core Capabilities

Intelligence

Operations

Industries

Use Cases

Authentication

OData Endpoints

Core Entities

Supported OData Operations

Telemetry API

Execute Telemetry Query

Swagger Documentation

Code Examples

Authentication

Get Devices

Get Gateways

Create Device

Create Gateway

Query Telemetry Data

Authentication

Get Devices

Get Gateways

Create Device

Create Gateway

Query Telemetry Data

Authentication

Get Devices

Get Gateways

Create Device

Create Gateway

Query Telemetry Data

Authentication

Get Devices

Get Gateways

Create Device

Create Gateway

Query Telemetry Data