SOT Learning Portal

Master data API

Use the master data API and its MCP server to read and manage devices, device types, measuring points and facilities. For authentication, tenants and general conventions, see Concepts.

All endpoints with their parameters and data structures: Master data API reference.

REST API

Base URL:

https://<sot-host>/mdm/api/v1/tenants/{tenantId}
Path Methods Purpose Permission

/devices

GET, POST

List devices, create a device

devices:read, devices:write

/devices/{id}

GET, PATCH, DELETE

Read, change or delete a device

devices:read, devices:write, devices:delete

/devices/{id}/measuring-points

GET, POST

List the measuring points of a device, assign a measuring point directly

devices:read, devices:write

/devices/{id}/measuring-points/{mpId}

DELETE

Remove a directly assigned measuring point

devices:write

/device-types

GET, POST

List device types, create a device type

device_types:read, device_types:write

/device-types/{id}

GET, PATCH, DELETE

Read, change or delete a device type

device_types:read, device_types:write, device_types:delete

/device-types/{id}/measuring-points

GET, POST

List and assign the measuring points of a device type

device_types:read, device_types:write

/device-types/{id}/measuring-points/{mpId}

DELETE

Remove a measuring point from a device type

device_types:write

/measuring-points

GET, POST

List measuring points, create a measuring point

measuring_points:read, measuring_points:write

/measuring-points/{id}

GET, PATCH, DELETE

Read, change or delete a measuring point

measuring_points:read, measuring_points:write, measuring_points:delete

/facilities

GET, POST

List facilities, create a facility

facilities:read, facilities:write

/facilities/{id}

GET, PATCH, DELETE

Read, change or delete a facility

facilities:read, facilities:write, facilities:delete

/facilities/tree

GET

Facility hierarchy as tree

facilities:read

/facilities/{id}/path

GET

Path from the top of the hierarchy to the facility

facilities:read

/facilities/types

GET

Facility types and the nesting rule

facilities:read

Lists

List endpoints support the following query parameters:

Parameter Description

page

Page number, starting with 1. Default: 1.

pageSize

Entries per page, 1 to 100. Default: 20.

sortBy

Field to sort by, for example name, createdAt or updatedAt.

sortOrder

asc (default) or desc.

search

Search term. Searches the visible attributes, for example name, technical ID and description of devices.

Rules

  • The technicalId of a device is required and unique within the tenant. It must match reference.identifier in the messages that the machine sends. See Mapping to your configuration.

  • Field lengths: names, manufacturer and technical ID up to 255 characters, descriptions up to 4,000 characters, units up to 50 characters.

  • A device type can only be deleted when no device uses it.

  • A measuring point can only be deleted when no device type or device uses it.

  • A measuring point that a device gets from its device type cannot be assigned to the device directly.

  • Facilities: a facility can only be placed under a parent of a higher type. GET /facilities/types returns the types and the rule. A wrong hierarchy is rejected with 409 and INVALID_FACILITY_HIERARCHY.

Errors

{
  "code": "...",
  "error": "human-readable message",
  "timestamp": "2026-10-16T09:26:25Z",
  "traceId": "fbbe93fe1e60700c88e556e49f5cc560"
}

MCP server

https://<sot-host>/mdm/tenants/{tenantId}/mcp
Tool Purpose Permission

sot-mdm_query_devices

List devices or read one device

devices:read

sot-mdm_manage_device

Create or change a device, assign measuring points

devices:write

sot-mdm_delete_device

Delete a device

devices:delete

sot-mdm_remove_measuring_point_from_device

Remove a directly assigned measuring point

devices:write

sot-mdm_query_device_types

List device types, read one device type or its measuring points

device_types:read

sot-mdm_manage_device_type

Create or change a device type, assign measuring points

device_types:write

sot-mdm_delete_device_type

Delete a device type

device_types:delete

sot-mdm_remove_measuring_point_from_device_type

Remove a measuring point from a device type

device_types:write

sot-mdm_query_measuring_points

List measuring points or read one

measuring_points:read

sot-mdm_manage_measuring_point

Create or change a measuring point

measuring_points:write

sot-mdm_delete_measuring_point

Delete a measuring point

measuring_points:delete

sot-mdm_query_facilities

List facilities, read the tree, the path or the types

facilities:read

sot-mdm_manage_facility

Create or change a facility

facilities:write

sot-mdm_delete_facility

Delete a facility

facilities:delete

Query tools return 20 entries per page by default, at most 100. Tools that delete data are marked as destructive.

Stammdaten-API

Die Stammdaten-API und ihr MCP-Server dienen zum Lesen und Verwalten von Geräten, Gerätetypen, Messpunkten und Anlagen. Authentifizierung, Tenants und allgemeine Konventionen: siehe Konzepte.

Alle Endpunkte mit ihren Parametern und Datenstrukturen: Referenz der Stammdaten-API.

REST-API

Basis-URL:

https://<sot-host>/mdm/api/v1/tenants/{tenantId}
Pfad Methoden Zweck Berechtigung

/devices

GET, POST

Geräte auflisten, Gerät anlegen

devices:read, devices:write

/devices/{id}

GET, PATCH, DELETE

Gerät lesen, ändern oder löschen

devices:read, devices:write, devices:delete

/devices/{id}/measuring-points

GET, POST

Messpunkte eines Geräts auflisten, Messpunkt direkt zuordnen

devices:read, devices:write

/devices/{id}/measuring-points/{mpId}

DELETE

Direkt zugeordneten Messpunkt entfernen

devices:write

/device-types

GET, POST

Gerätetypen auflisten, Gerätetyp anlegen

device_types:read, device_types:write

/device-types/{id}

GET, PATCH, DELETE

Gerätetyp lesen, ändern oder löschen

device_types:read, device_types:write, device_types:delete

/device-types/{id}/measuring-points

GET, POST

Messpunkte eines Gerätetyps auflisten und zuordnen

device_types:read, device_types:write

/device-types/{id}/measuring-points/{mpId}

DELETE

Messpunkt von einem Gerätetyp entfernen

device_types:write

/measuring-points

GET, POST

Messpunkte auflisten, Messpunkt anlegen

measuring_points:read, measuring_points:write

/measuring-points/{id}

GET, PATCH, DELETE

Messpunkt lesen, ändern oder löschen

measuring_points:read, measuring_points:write, measuring_points:delete

/facilities

GET, POST

Anlagen auflisten, Anlage anlegen

facilities:read, facilities:write

/facilities/{id}

GET, PATCH, DELETE

Anlage lesen, ändern oder löschen

facilities:read, facilities:write, facilities:delete

/facilities/tree

GET

Anlagenhierarchie als Baum

facilities:read

/facilities/{id}/path

GET

Pfad von der obersten Ebene der Hierarchie bis zur Anlage

facilities:read

/facilities/types

GET

Anlagentypen und Verschachtelungsregel

facilities:read

Listen

Listen-Endpunkte unterstützen folgende Query-Parameter:

Parameter Beschreibung

page

Seitennummer, beginnend mit 1. Standard: 1.

pageSize

Einträge je Seite, 1 bis 100. Standard: 20.

sortBy

Feld für die Sortierung, zum Beispiel name, createdAt oder updatedAt.

sortOrder

asc (Standard) oder desc.

search

Suchbegriff. Durchsucht die sichtbaren Attribute, zum Beispiel Name, technische ID und Beschreibung von Geräten.

Regeln

  • Die technicalId eines Geräts ist Pflicht und innerhalb des Tenants eindeutig. Sie muss mit reference.identifier in den Nachrichten übereinstimmen, die die Maschine sendet. Siehe Zuordnung zur Konfiguration.

  • Feldlängen: Namen, Hersteller und technische ID bis 255 Zeichen, Beschreibungen bis 4.000 Zeichen, Einheiten bis 50 Zeichen.

  • Ein Gerätetyp lässt sich nur löschen, wenn kein Gerät ihn verwendet.

  • Ein Messpunkt lässt sich nur löschen, wenn kein Gerätetyp und kein Gerät ihn verwendet.

  • Ein Messpunkt, den ein Gerät über seinen Gerätetyp erhält, lässt sich dem Gerät nicht direkt zuordnen.

  • Anlagen: Eine Anlage lässt sich nur unter einer übergeordneten Anlage höheren Typs einordnen. GET /facilities/types liefert die Typen und die Regel. Eine falsche Hierarchie lehnt die API mit 409 und INVALID_FACILITY_HIERARCHY ab.

Fehler

{
  "code": "...",
  "error": "human-readable message",
  "timestamp": "2026-10-16T09:26:25Z",
  "traceId": "fbbe93fe1e60700c88e556e49f5cc560"
}

MCP-Server

https://<sot-host>/mdm/tenants/{tenantId}/mcp
Tool Zweck Berechtigung

sot-mdm_query_devices

Geräte auflisten oder ein Gerät lesen

devices:read

sot-mdm_manage_device

Gerät anlegen oder ändern, Messpunkte zuordnen

devices:write

sot-mdm_delete_device

Gerät löschen

devices:delete

sot-mdm_remove_measuring_point_from_device

Direkt zugeordneten Messpunkt entfernen

devices:write

sot-mdm_query_device_types

Gerätetypen auflisten, einen Gerätetyp oder seine Messpunkte lesen

device_types:read

sot-mdm_manage_device_type

Gerätetyp anlegen oder ändern, Messpunkte zuordnen

device_types:write

sot-mdm_delete_device_type

Gerätetyp löschen

device_types:delete

sot-mdm_remove_measuring_point_from_device_type

Messpunkt von einem Gerätetyp entfernen

device_types:write

sot-mdm_query_measuring_points

Messpunkte auflisten oder einen Messpunkt lesen

measuring_points:read

sot-mdm_manage_measuring_point

Messpunkt anlegen oder ändern

measuring_points:write

sot-mdm_delete_measuring_point

Messpunkt löschen

measuring_points:delete

sot-mdm_query_facilities

Anlagen auflisten, Baum, Pfad oder Typen lesen

facilities:read

sot-mdm_manage_facility

Anlage anlegen oder ändern

facilities:write

sot-mdm_delete_facility

Anlage löschen

facilities:delete

Abfrage-Tools liefern standardmäßig 20 Einträge je Seite, höchstens 100. Tools, die Daten löschen, sind als destruktiv gekennzeichnet.

Diese Seite bearbeiten Edit this page

Feedback on this pageFeedback zu dieser Seite