This is the documentation of the nomos system AG Controller API. nomos system is a Smart Home and building automation controller that manages devices, rooms, zones, users, automations, scenes, and integrations with platforms such as Matter, HomeKit, KNX, Philips Hue, Sonos, Miele, Husqvarna, and many more.

Two communication protocols are available:

• socket.io API — bidirectional, event-driven, recommended for apps and persistent connections
• HTTP REST API — request/response, ideal for scripts and one-shot integrations

Authentication

All endpoints require authentication. Two schemes are supported on both protocols:

• User credentials — username and password
• Session ID — reusable token returned after a successful login

Sessions live for two years and are extended on every access (rolling expiration), so a stored Session ID typically remains valid as long as the client keeps using the API.

socket.io

Authenticate by emitting auth with username and password. The callback returns a sessionID that can be reused on subsequent connections via the x-nomos-sid query parameter, skipping the credentials prompt.

socket.emit('auth', {username: 'admin', password: '••••••••'}, function(result) {
  if(result && result.sessionID) {
    // store result.sessionID and reuse it on the next connection
    localStorage.setItem('nomos-sid', result.sessionID);
  } else {
    // result contains {errorCode, errorText} on failure
  }
});

// Reconnect later with the stored session — no password required
var sid = localStorage.getItem('nomos-sid');
var socket = io('http://{host}:{port}/api/v1?x-nomos-sid=' + sid, {path: '/socket.io-v4'});

HTTP

Send credentials via the auth-username and auth-password headers, or a stored Session ID via the x-nomos-sid header.

# With user credentials
curl -H 'auth-username: admin' -H 'auth-password: ••••••••' https://{host}/api/v1/getRooms
# With a stored Session ID
curl -H 'x-nomos-sid: <session-id>' https://{host}/api/v1/getRooms

Errors

Every API call returns a result object. On failure, the object has the following shape:

{
  "errorCode": 106,
  "errorText": "Parameter(s) error"
}

• errorCode — integer error code, stable across versions. Use this in code for branching and logging.
• errorText — human-readable message localized to the client language sent during init. Use this for display only, never for control flow.

A successful response never contains an errorCode field. Inspect its absence to distinguish success from failure:

socket.emit('getRooms', {}, function(result) {
  if(result.errorCode) {
    console.error('Failed:', result.errorCode, result.errorText);
    return;
  }
  // result is the success payload
});

Operations that return no payload on success reply with an empty object ({}).

Sorting

Many API functions support sort order definitions. For example:

socket.emit('getEvents', {sortBy: ['name', 'created']}, function(result) {
  // Result sorted by name and created Timestamp
  console.debug(result);
});

socket.emit('getEvents', {sortBy: ['-created', 'name']}, function(result) {
  // Result sorted by created Timestamp ('-' means reverse sort order) and name
  console.debug(result);
});