MTS Device API Documentation

Collection of articles for working with Multitech devices in LoRaWAN networks.

MTS Device API Documentation

This repository contains comprehensive API documentation for the Multi-Tech Systems (MTS) IoT device management platform (mPower Edge Intelligence).

Overview

The MTS Device API is a RESTful API that provides complete control and monitoring capabilities for MTS IoT gateway devices. The API enables configuration and management of:

Documentation Files

Quick Start

Authentication

The API uses session-based authentication with cookies. To authenticate:

  1. Login - POST to /api/login with credentials: 
    curl -X POST http://192.168.2.1/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}' \
  -c cookies.txt
  2. Use the session cookie for subsequent requests: 
    curl -X GET http://192.168.2.1/api?fields=system \
  -b cookies.txt
  3. Logout when done: 
    curl -X POST http://192.168.2.1/api/logout \
  -b cookies.txt

Basic API Usage

Query Resources

The primary endpoint for retrieving data is /api with a fields query parameter:

# Get system information
curl -X GET "http://192.168.2.1/api?fields=system" -b cookies.txt

# Get multiple resources
curl -X GET "http://192.168.2.1/api?fields=system,cellular,users" -b cookies.txt

# Get nested fields
curl -X GET "http://192.168.2.1/api?fields=system/capabilities" -b cookies.txt

Update Configuration

Use PUT requests to update resource configurations:

# Update system settings
curl -X PUT http://192.168.2.1/api/system \
  -H "Content-Type: application/json" \
  -d '{"deviceName": "MyDevice"}' \
  -b cookies.txt

# Update cellular configuration
curl -X PUT http://192.168.2.1/api/cellular \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' \
  -b cookies.txt

Execute Commands

Use POST requests to execute device commands:

# Save configuration
curl -X POST http://192.168.2.1/api/command/save -b cookies.txt

# Restart device
curl -X POST http://192.168.2.1/api/command/restart -b cookies.txt

# Ping test
curl -X POST http://192.168.2.1/api/command/ping \
  -H "Content-Type: application/json" \
  -d '{"host": "8.8.8.8", "count": 4}' \
  -b cookies.txt

API Structure

Resource Endpoints

The API follows a consistent pattern for resource management:

HTTP Method Pattern Description
GET /api?fields=<resource> Retrieve resource data
PUT /api/<resource> Update entire resource
POST /api/<resource> Create new resource item
DELETE /api/<resource>/<id> Delete resource item

Available Resources

Core System Resources

Network Resources

VPN Resources

IoT Protocol Resources

Device Management Resources

Communication Resources

Security Resources

Monitoring Resources

Command Endpoints

Commands are executed via POST to /api/command/<command>:

Configuration Commands

System Commands

Firmware Commands

Network Commands

User Commands

LoRa Commands

SMS Commands

Role-Based Access Control

The API implements role-based access control with three built-in roles:

Admin Role

Engineer Role (User)

Monitor Role (Guest)

Each endpoint in the API has associated permissions:

Response Format

All API responses follow a consistent JSON format:

Success Response

{
  "success": true,
  "result": {
    // Response data varies by endpoint
  }
}

Error Response

{
  "success": false,
  "error": "Error message description",
  "code": 404
}

Common HTTP Status Codes

Configuration Workflow

The device uses a two-stage configuration model:

  1. Runtime Configuration - Changes made via PUT requests update the runtime configuration
  2. Persistent Configuration - Use POST /api/command/save to persist changes

Typical Workflow

# 1. Login
curl -X POST http://192.168.2.1/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}' \
  -c cookies.txt

# 2. Get current configuration
curl -X GET "http://192.168.2.1/api?fields=cellular" -b cookies.txt

# 3. Update configuration
curl -X PUT http://192.168.2.1/api/cellular \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, ...}' \
  -b cookies.txt

# 4. Check if configuration is dirty (has unsaved changes)
curl -X GET "http://192.168.2.1/api?fields=system/dbDirty" -b cookies.txt

# 5. Save configuration
curl -X POST http://192.168.2.1/api/command/save -b cookies.txt

# 6. Optionally restart to apply changes
curl -X POST http://192.168.2.1/api/command/restart -b cookies.txt

# 7. Logout
curl -X POST http://192.168.2.1/api/logout -b cookies.txt

Special Endpoints

Device Policy Check

Check if device is available (not in commissioning mode):

curl -X GET http://192.168.2.1/api/policy

Commissioning Mode

For first-time device setup:

curl -X POST http://192.168.2.1/api/commissioning \
  -H "Content-Type: application/json" \
  -d '{"password": "newpassword"}'

Status Notifications

Get system status notifications:

curl -X GET "http://192.168.2.1/api?fields=status" -b cookies.txt

Clear a specific notification:

curl -X DELETE http://192.168.2.1/api/status/{guid} -b cookies.txt

Cellular Configuration Example

Complete example of configuring cellular connectivity:

# Get current cellular configuration
curl -X GET "http://192.168.2.1/api?fields=cellular" -b cookies.txt

# Update cellular configuration
curl -X PUT http://192.168.2.1/api/cellular \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "enabled": true,
    "providerProfiles": [
      {
        "_id": "550e8400-e29b-41d4-a716-446655440000",
        "profileName": "My Carrier",
        "cellularMode": "4g-preferred",
        "dataCtx": {
          "apnString": "internet",
          "contextIpMode": "AUTO",
          "authentication": {
            "type": "NONE",
            "username": "",
            "password": ""
          }
        }
      }
    ],
    "simProfiles": [
      {
        "_id": "550e8400-e29b-41d4-a716-446655440001",
        "profileName": "My SIM",
        "providerProfileId": "550e8400-e29b-41d4-a716-446655440000",
        "simIccid": "ANY",
        "simPin": ""
      }
    ]
  }'

# Save configuration
curl -X POST http://192.168.2.1/api/command/save -b cookies.txt

User Management Example

# List all users (admin only)
curl -X GET "http://192.168.2.1/api?fields=users" -b cookies.txt

# Create new user
curl -X POST http://192.168.2.1/api/users \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "engineer1",
    "password": "password123",
    "permission": "user",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  }'

# Update user
curl -X PUT http://192.168.2.1/api/users/engineer1 \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "email": "newemail@example.com",
    "enabled": true
  }'

# Delete user
curl -X DELETE http://192.168.2.1/api/users/engineer1 -b cookies.txt

# Save changes
curl -X POST http://192.168.2.1/api/command/save -b cookies.txt

LoRa Network Server Example

# Get LoRa configuration
curl -X GET "http://192.168.2.1/api?fields=loraNetwork" -b cookies.txt

# Update LoRa network server mode
curl -X PUT http://192.168.2.1/api/loraNetwork \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "enabled": true,
    "mode": "NETWORK_SERVER"
  }'

# List registered gateways
curl -X GET http://192.168.2.1/api/lora/gateways -b cookies.txt

# Restart LoRa service
curl -X POST http://192.168.2.1/api/lora/restart -b cookies.txt

Viewing the Documentation

Using Swagger UI

  1. Install Swagger UI locally or use the online editor
  2. Load the api-documentation.yaml file
  3. Interact with the API directly from the UI

Online Swagger Editor: Visit https://editor.swagger.io/ and paste the contents of api-documentation.yaml

Using Postman

  1. Open Postman
  2. Click Import → Upload Files
  3. Select api-documentation.yaml
  4. The entire API collection will be imported with all endpoints

Generating Client Code

Use OpenAPI Generator to create client libraries in various languages:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate Python client
openapi-generator-cli generate \
  -i api-documentation.yaml \
  -g python \
  -o ./python-client

# Generate JavaScript/TypeScript client
openapi-generator-cli generate \
  -i api-documentation.yaml \
  -g typescript-axios \
  -o ./typescript-client

# Generate Java client
openapi-generator-cli generate \
  -i api-documentation.yaml \
  -g java \
  -o ./java-client

API Versioning

The current API version is included in the system information:

curl -X GET "http://192.168.2.1/api?fields=system/apiVersion" -b cookies.txt

Security Considerations

  1. HTTPS: Always use HTTPS in production environments
  2. Session Management: Sessions expire after inactivity (default 30 minutes)
  3. Password Complexity: Enforce strong passwords via passwordComplexityRules
  4. Trusted IPs: Restrict access using trustedIp configuration
  5. Firewall: Configure firewall rules to limit API access
  6. Certificates: Use valid SSL/TLS certificates for HTTPS

Troubleshooting

Authentication Issues

If you receive 401 errors:

Configuration Not Persisting

If changes are lost after reboot:

Device Unavailable

If you receive “device unavailable” errors:

Additional Resources

Support

For technical support and additional documentation:

License

This API documentation is provided for use with Multi-Tech Systems devices. Refer to your device license agreement for terms and conditions.

Document Version: 1.0.0
Last Updated: December 17, 2025
API Version: Based on mtsDeviceAPI and mtsDeviceUI projects