Get Objects

Retrieve a list of devices (objects) visible to the authenticated user. This endpoint provides comprehensive information about each device including connection status, hardware details, and session history.

Request

GET /api/objects

Authentication Required: Must include JWT token in Authorization header.

Required Scope: objects

Request Example

curl -X GET "http://your-server-ip:port/api/objects" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

Success (200 OK)

{
  "objects": [
    {
      "id": 123,
      "partial_uid": 456789,
      "oid": 987654,
      "uid": "AABBCCDDEEFF",
      "registered_at": "2025-10-18T12:34:56+02:00",
      "iccid": "1234567890123456789",
      "signal_level": 4,
      "com_type": 1,
      "con_type": 2,
      "ip": "192.168.1.100",
      "ping_interval": 60,
      "sms_ping_interval": 120,
      "hw_type": 1,
      "fw_version": "1.2.3",
      "receiver_id": 1,
      "receiver_nr": 2,
      "line_nr": 3,
      "last_activity": 1634567890,
      "status": 1,
      "last_sms_activity": 1634567891,
      "has_received_sms": true,
      "cloud_access_code": "XYZ123",
      "info_update_needed": false,
      "dev_receiver_nr": 1,
      "dev_line_nr": 2,
      "oid_override": 0,
      "next_time_update": "2025-10-19T12:00:00+02:00",
      "session_log": {
        "sessions": [
          {
            "start_time": 1634567890,
            "duration": 3600,
            "close_reason": 1
          },
          {
            "start_time": 1634564290,
            "duration": 1800,
            "close_reason": 0
          }
        ],
        "average_session_time": 2700
      },
      "related_objects": [
        {
          "id": 124,
          "oid": 987655,
          "uid": 789012,
          "status": 1,
          "last_activity": 1634567890,
          "device_id": 123,
          "oid_override": 0,
          "ping_interval": 60,
          "dev_receiver_nr": 1,
          "dev_line_nr": 2,
          "area": 1
        }
      ],
      "module_id": 42
    }
  ]
}

Response Fields

Main Object Fields

Field	Type	Description
id	integer	ID in database
partial_uid	integer	Partial unique identifier
oid	integer	Object identifier
uid	string	Full unique identifier (hex format)
registered_at	string	ISO 8601 timestamp when device was registered
iccid	string	SIM card ICCID number
signal_level	integer	Signal strength level (0-10)
com_type	integer	Communication type identifier (see Communication Types)
con_type	integer	Connection type identifier (see Connection Types)
ip	string	Device IP address
ping_interval	integer	Ping interval in seconds
sms_ping_interval	integer	SMS ping interval in seconds
hw_type	integer	Hardware type identifier
fw_version	string	Firmware version
receiver_id	integer	Receiver ID
receiver_nr	integer	Receiver number
line_nr	integer	Line number
last_activity	integer	Unix timestamp of last activity
status	integer	Device status (see Device Status Values)
last_sms_activity	integer	Unix timestamp of last SMS activity
has_received_sms	boolean	Whether device has received SMS
cloud_access_code	string	Cloud access code
info_update_needed	boolean	Whether device info needs updating
dev_receiver_nr	integer	Device receiver number
dev_line_nr	integer	Device line number
oid_override	integer	OID override value (0 if not overridden)
next_time_update	string	ISO 8601 timestamp for next scheduled update
module_id	integer	Module identifier for SIA DC-09

Session Log Object

Field	Type	Description
sessions	array	Array of device session objects
average_session_time	integer	Average session duration in seconds

Device Session Object

Field	Type	Description
start_time	integer	Unix timestamp when session started
duration	integer	Session duration in seconds
close_reason	integer	Reason why session ended (see Session Close Reasons)

Related Object

Field	Type	Description
id	integer	Related object ID
oid	integer	Related object OID
uid	integer	Related object UID
status	integer	Related object status (see Device Status Values)
last_activity	integer	Unix timestamp of last activity
device_id	integer	Parent device ID
oid_override	integer	OID override value
ping_interval	integer	Ping interval in seconds
dev_receiver_nr	integer	Device receiver number
dev_line_nr	integer	Device line number
area	integer	Area identifier

Device Status Values

Value	Description
0	Online
1	SMS mode
2	Offline
3	Untracked

Session Close Reasons

Value	Description
0	Unknown
1	Timeout - Device tracker closed the session
2	Client disconnect - Module closed the session itself
3	New session - Old session remained open when module connected with new session
4	Object deleted - Session closed due to object deletion

Communication Types

Value	Description
0	Device too old to report this information
1	GSM
2	LAN
3	WiFi
4	SigFox

Connection Types

Value	Description
0	None
1	TCP
2	UDP
3	SMPP
4	COM
5	Modem

Error Responses

All error responses are returned as plain text:

401 Unauthorized

NOT_LOGGED_IN

403 Forbidden

FORBIDDEN

503 Service Unavailable

Database is not ready

405 Method Not Allowed

Method Not Allowed

Filtering and Visibility

User-Based Filtering

Objects returned are filtered based on the authenticated user's visible_receivers configuration:

• If visible_receivers.all is true, user sees all objects
• If visible_receivers.all is false, user only sees objects from receivers listed in visible_receivers.custom

Example Filtering Scenarios

Admin user (sees all receivers):

{
  "visible_receivers": {
    "all": true,
    "custom": []
  }
}

Limited user (sees only specific receivers):

{
  "visible_receivers": {
    "all": false,
    "custom": [1, 3, 5]
  }
}

Usage Examples

Get All Objects

curl -X GET "http://your-server:8080/api/objects" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response Processing (JavaScript)

async function getObjects() {
  try {
    const response = await fetch('/api/objects', {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
    
    if (!response.ok) {
      const error = await response.text();
      throw new Error(error);
    }
    
    const data = await response.json();
    
    // Process objects
    data.objects.forEach(obj => {
      console.log(`Device ${obj.id}: ${obj.uid} - Status: ${obj.status}`);
      
      // Check session history
      if (obj.session_log && obj.session_log.sessions.length > 0) {
        console.log(`Average session time: ${obj.session_log.average_session_time}s`);
      }
      
      // Process related objects
      if (obj.related_objects && obj.related_objects.length > 0) {
        console.log(`Has ${obj.related_objects.length} related objects`);
      }
    });
    
    return data.objects;
  } catch (error) {
    console.error('Failed to fetch objects:', error);
    throw error;
  }
}

Filter Online Devices

function getOnlineDevices(objects) {
  return objects.filter(obj => obj.status === 1);
}

Get Devices with Recent Activity

function getRecentlyActiveDevices(objects, hoursAgo = 24) {
  const cutoffTime = Math.floor(Date.now() / 1000) - (hoursAgo * 3600);
  return objects.filter(obj => obj.last_activity > cutoffTime);
}

Important Notes

• Scope Required: Users must have the objects scope to access this endpoint
• Visibility Filtering: Only objects from receivers visible to the user are returned
• Plain Text Errors: Error responses are not in JSON format
• Session Logs: May be empty for devices with no recorded sessions
• Related Objects: Can be an empty array if no related objects exist
• Timestamps: Unix timestamps are used for time-based fields
• Hardware Types: Hardware type values depend on device manufacturer specifications