17. Vollständige Liste der Endpunkte

Dies ist die Zuordnung der REST-Endpunkte der PlantPulse API zu den Client-Methoden. Der Basispfad ist /api/v5.

Authentifizierung: Da bei einem Aufruf von APIClient_V5.connect() automatisch ein api_key ausgestellt und verwaltet wird, gibt es keinen Authentifizierungs-Endpunkt, den der Benutzer direkt aufrufen muss.

17.1 System

HTTP	Endpunkt	Methode
GET	/api/v5/ping	client.system().ping()

17.2 ID-Ausstellung

Methode	Pfad	Beschreibung
POST	/api/v5/domain-ids	Erhalt der Domain-ID im Voraus (keine Client-Methode) — ID-Regeln

17.3 Site (6 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/site	client.site().create(req)
PUT	/api/v5/site/{id}	client.site().update(id, req)
DELETE	/api/v5/site/{id}	client.site().delete(id)
GET	/api/v5/site/{id}	client.site().get(id)
GET	/api/v5/site	client.site().list()
GET	/api/v5/site/{id}/exists	client.site().exists(id)

17.4 OPC (10 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/opc	client.opc().create(req)
PUT	/api/v5/opc/{id}	client.opc().update(id, req)
DELETE	/api/v5/opc/{id}	client.opc().delete(id)
GET	/api/v5/opc/{id}	client.opc().get(id)
GET	/api/v5/opc	client.opc().list()
GET	/api/v5/opc?site_id={id}	client.opc().listBySite(siteId)
GET	/api/v5/opc?opc_source_type={type}	client.opc().listByType(sourceType)
GET	/api/v5/opc/{id}/exists	client.opc().exists(id)
GET	/api/v5/opc/count	client.opc().count()
GET	/api/v5/opc/count?site_id={id}	client.opc().countBySite(siteId)

17.5 Asset (6 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/asset	client.asset().create(req)
PUT	/api/v5/asset/{id}	client.asset().update(id, req)
DELETE	/api/v5/asset/{id}	client.asset().delete(id)
GET	/api/v5/asset/{id}	client.asset().get(id)
GET	/api/v5/asset	client.asset().list()
GET	/api/v5/asset/{id}/exists	client.asset().exists(id)

Beziehungsontologie (4 Stück)

Dies sind richtungsgebundene Beziehungen, die getrennt von der Hierarchie (Eltern-Kind) existieren. Sie werden verwendet, um Fragen wie „Welche Bereiche sind betroffen, wenn diese Anlage stillsteht?“ zu beantworten.

HTTP	Endpunkt	Funktion
POST	/api/v5/assets/{asset_id}/relations	Registrierung der Beziehung — Body {site_id, to_entity_type, to_entity_id, relation_type, description?} → 201
GET	/api/v5/assets/{asset_id}/relations?type=	Liste der direkten Beziehungen (eingehend · ausgehend)
DELETE	/api/v5/relations/{relation_id}	Löschen der Beziehung → 204
GET	/api/v5/ontology/graph/{entity_id}?relation=&direction=DOWN&depth=2	Graphensuche (BFS)

Beziehung	Bedeutung	Richtung
FEEDS	Prozessfluss	Asset → Asset
DEPENDS_ON	Versorgungsabhängigkeit (Strom · Luft · Kühlung)	Asset → Asset
PRODUCES	Produktionsausstoß	Asset → Produkt

• direction beträgt UP · DOWN · BOTH (Standard DOWN), depth liegt zwischen 1~5 (Standard 2).
• Beziehungen auf sich selbst werden nicht gespeichert; Beziehungen mit der gleichen Kombination werden nur einmal registriert.
• Registrierung und Löschung gelten als Änderungen, daher werden die ADMIN/API-Rollen und Audit-Logs angewendet.
• Wenn ein KI-Assistent dieselbe Suche aufruft, entspricht dies trace_asset_relations von MCP.

QR-Label

HTTP	Endpunkt	Funktion
GET	/api/v5/asset/qr/{token}	Anlage des Label-Tokens. 404, wenn es kein Token ist oder ein bereits neu ausgestelltes altes Token vorliegt.

Die im Label enthaltene Adresse entspricht qr_payload der Antwort von GET /api/v5/asset/{id}. Da dieser Aufruf kein Token erstellt, erfolgt eine Antwort mit "", wenn noch kein Token oder kein PP_UI_CONSOLE_URL vorhanden ist. Die öffentliche Seite ohne Login ist nicht V5, sondern /qr/{token} — QR-Label und öffentliche Seiten.

17.6 Tag (23 Stück)

CRUD + Liste

HTTP	Endpunkt	Methode
POST	/api/v5/tag	client.tag().create(req)
PUT	/api/v5/tag/{id}	client.tag().update(id, req)
DELETE	/api/v5/tag/{id}	client.tag().delete(id)
GET	/api/v5/tag/{id}	client.tag().get(id)
GET	/api/v5/tag/{id}/exists	client.tag().exists(id)
GET	/api/v5/tag	client.tag().list()
GET	/api/v5/tag?site_id={id}	client.tag().listBySite(siteId)
GET	/api/v5/tag?opc_id={id}	client.tag().listByOpc(opcId)
GET	/api/v5/tag?asset_id={id}	client.tag().listByAsset(assetId)
GET	/api/v5/tag/count	client.tag().count()
GET	/api/v5/tag/count?site_id={id}	client.tag().countBySite(siteId)
GET	/api/v5/tag/count?opc_id={id}	client.tag().countByOpc(opcId)
GET	/api/v5/tag/count?asset_id={id}	client.tag().countByAsset(assetId)

PATCH (10 Stück — Teilweise Änderung pro Tab)

HTTP	Endpunkt	Methode
PATCH	/api/v5/tag/{id}/basic	patchBasic(id, req)
PATCH	/api/v5/tag/{id}/alarm	patchAlarm(id, req)
PATCH	/api/v5/tag/{id}/metadata	patchMetadata(id, req)
PATCH	/api/v5/tag/{id}/calculation	patchCalculation(id, req)
PATCH	/api/v5/tag/{id}/sampling	patchSampling(id, req)
PATCH	/api/v5/tag/{id}/aggregation	patchAggregation(id, req)
PATCH	/api/v5/tag/{id}/ai	patchAi(id, req)
PATCH	/api/v5/tag/{id}/publish	patchPublish(id, req)
PATCH	/api/v5/tag/{id}/attribute	patchAttribute(id, req)
PATCH	/api/v5/tag/{id}/link	patchLink(id, req)

17.7 Alarm (3 Stück)

HTTP	Endpunkt	Methode
GET	/api/v5/alarm/{seq}	client.alarm().get(seq)
GET	/api/v5/alarm?limit={n}	client.alarm().list(limit)
GET	/api/v5/alarm/performance?scope_type=&scope_id=	Alarm-Systemleistung (keine Client-Methode)

/alarm/performance — scope_type sind SITE · AREA · LINE, scope_id ist die Site-ID oder Asset-ID, beides ist erforderlich. Der Zeitraum ist days (1~31, Standard 7) oder from + to (zusammen, bis zu 31 Tage), wobei from/to gegenüber days Vorrang haben. Nur das Auftreten von Alarmen wird gezählt; Alarmierungen, die während einer Ausblendung oder Unterdrückung geöffnet wurden, erscheinen separat unter suppression. Bei falschem Bereich oder Zeitraum erfolgt ein 400. Dieselben Werte liefert MCP get_alarm_performance zurück.

17.8 Order (11 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/order	client.order().create(req)
PUT	/api/v5/order/{id}	client.order().update(id, req)
DELETE	/api/v5/order/{id}	client.order().delete(id)
GET	/api/v5/order/{id}	client.order().get(id)
GET	/api/v5/order	client.order().list()
GET	/api/v5/order/{id}/exists	client.order().exists(id)
POST	/api/v5/order/{id}/start	client.order().start(id)
POST	/api/v5/order/{id}/end	client.order().end(id)
POST	/api/v5/order/{id}/pause	client.order().pause(id)
POST	/api/v5/order/{id}/resume	client.order().resume(id)
POST	/api/v5/order/{id}/abort	client.order().abort(id)

17.8.1 Instandhaltungsauftrag

Dies sind Aufrufe, Reparaturen und präventive Instandhaltungsarbeiten für Anlagen (ISA-95 maintenance work order). Dies ist ein anderes Objekt als Produktionsarbeitsaufträge (/order) und wird per REST ohne Client-Methode aufgerufen.

HTTP	Endpunkt	Funktion
GET	/api/v5/maintenance-orders	Liste. Filter scope+scope_id(asset · line · area · site) · status_code · open · maintenance_kind_code · assignee_employee_id · failure_mode_code · maintainable_item_code · from/to · period_of · overdue · external_system · external_id. Seite page · limit(Standard 50, Max 500) · sort · order
GET	/api/v5/asset/{asset_id}/maintenance-orders	Liste für eine einzelne Anlage
POST	/api/v5/asset/{asset_id}/maintenance-orders	Instandhaltungsaufruf hinzufügen
GET	/api/v5/maintenance-orders/{maintenance_order_id}	Einzeldatensatz
PATCH	/api/v5/maintenance-orders/{maintenance_order_id}	Inhalte ändern
POST	/api/v5/maintenance-orders/{maintenance_order_id}/transition	Status ändern (Erhalten · Start · Abgeschlossen · Storniert). Body status_code · version, Stornierung cancel_reason_code
GET	/api/v5/maintenance-orders/{maintenance_order_id}/revisions	Beurteilungshistorie
GET	/api/v5/maintenance-orders/summary	Instandhaltungszusammenfassung für Bereich · Zeitraum
GET	/api/v5/maintenance-orders/options	Zulässige Typen · Status · Codes
GET	/api/v5/maintenance-orders/board	Instandhaltungsdashboard für Bereich
GET	/api/v5/maintenance-orders/changes	Änderungsfeed (Cursor) zur CMMS-Synchronisation
GET · PUT	/api/v5/maintenance-orders/by-external/{system}/{external_id}	Suche per externer (CMMS) Nummer · idempotentes Schreiben
GET · PUT	/api/v5/maintenance-orders/by-external?system=&external_id=	Gleiche Funktion, wenn die Nummer / enthält
POST · GET	/api/v5/maintenance-orders/{maintenance_order_id}/attachments	Fotos hochladen · Liste
GET	/api/v5/maintenance-orders/{maintenance_order_id}/attachments/{maintenance_attachment_seq}/content	Fotoinhalt

Felder des Instandhaltungsauftrags

Die Feldnamen sind in Antwort- und Anforderungsbodys sowie in Listenabfragen identisch.

Feld	Typ	Bedeutung
maintenance_order_id	Zeichenfolge	MAINTENANCE_ORDER_000001. Alte Zeilen sind numerische Zeichenfolgen("12")
maintenance_kind_code	Zeichenfolge	Instandhaltungsart(CORRECTIVE …)
status_code	Zeichenfolge	Status(REQUESTED · ACCEPTED · IN_PROGRESS · COMPLETED · CANCELLED)
cancel_reason_code	Zeichenfolge	Stornierungsgrund
failure_record_seq	Zahl	Verknüpfte Ausfallhistorie
maintenance_plan_id · maintenance_plan_name	Zeichenfolge	Präventiver Instandhaltungsplan. MAINTENANCE_PLAN_000001 oder alte numerische Zeichenfolge
failure_mode_code · failure_mechanism_code · failure_cause_code · maintainable_item_code	Zeichenfolge	ISO 14224 Code. Anzeigename ist _name statt _code
cause_code	Zeichenfolge	Ursachenlexikon-Code (gleiches Lexikon wie bei Alarmen)
checklist_results[].maintenance_attachment_seq	Zahl	Foto des Inspektionspunktes

CMMS-Webhook

Wenn eine Adresse im Konfigurationsschlüssel PP_MAINTENANCE_WEBHOOK_URL hinterlegt ist, wird bei jeder Änderung des Status eines Instandhaltungsauftrags einmalig ein JSON per POST gesendet (Aufruf · Erhalten · Start · Abgeschlossen · Storniert). Bei reinen Inhaltsänderungen erfolgt kein Versand; ist das Feld leer, ist der Webhook deaktiviert. Bei Fehlern wird die Diagnose diagnostic.maintenance.webhook_failed aktiviert und beim nächsten Erfolg wieder deaktiviert; es erfolgt kein erneuter Versand.

Schlüssel	Wert
text	Einzeiliger Satz in der Installationssprache
event	maintenance.requested · maintenance.accepted · maintenance.in_progress · maintenance.completed · maintenance.cancelled
maintenance_order_id	Instandhaltungsauftrags-ID (Zeichenfolge)
asset_id · asset_name	Anlage
maintenance_kind_code · status_code	Art · Status
description · failure_mode_code	Beschreibung · Ausfallmode
requested_by · accepted_by · assignee_employee_id	Person
cancel_reason_code	Stornierungsgrund
external_system · external_id · owner	Externe Nummer und Besitzer
anomaly_found · checklist_results	Vorhandensein einer Inspektionsanomalie und Antwort(item_id · checked · value · maintenance_attachment_seq · out_of_range)
maintenance_plan_id · plan_due_at	Präventiver Instandhaltungsplan
at · version	Zeitpunkt des Statuswechsels (epoch ms) · Beurteilung

Schlüssel mit unbekannten Werten werden nicht ausgelassen, sondern als null übertragen.

17.9 Calendar (6 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/calendar	client.calendar().create(req)
PUT	/api/v5/calendar/{id}	client.calendar().update(id, req)
DELETE	/api/v5/calendar/{id}	client.calendar().delete(id)
GET	/api/v5/calendar/{id}	client.calendar().get(id)
GET	/api/v5/calendar	client.calendar().list()
GET	/api/v5/calendar/search?from={iso}&to={iso}	client.calendar().search(from, to)

17.10 Customer (8 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/customer	client.customer().create(req)
PUT	/api/v5/customer/{id}	client.customer().update(id, req)
DELETE	/api/v5/customer/{id}	client.customer().delete(id)
GET	/api/v5/customer/{id}	client.customer().get(id)
GET	/api/v5/customer	client.customer().list()
GET	/api/v5/customer?site_id={id}	client.customer().listBySite(siteId)
GET	/api/v5/customer/{id}/exists	client.customer().exists(id)
GET	/api/v5/customer/count	client.customer().count()

17.11 Employee (7 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/employee	client.employee().create(req)
PUT	/api/v5/employee/{id}	client.employee().update(id, req)
DELETE	/api/v5/employee/{id}	client.employee().delete(id)
GET	/api/v5/employee/{id}	client.employee().get(id)
GET	/api/v5/employee	client.employee().list()
GET	/api/v5/employee/{id}/exists	client.employee().exists(id)
GET	/api/v5/employee/count	client.employee().count()

17.12 Product (7 Stück)

HTTP	Endpunkt	Methode
POST	/api/v5/product	client.product().create(req)
PUT	/api/v5/product/{id}	client.product().update(id, req)
DELETE	/api/v5/product/{id}	client.product().delete(id)
GET	/api/v5/product/{id}	client.product().get(id)
GET	/api/v5/product	client.product().list()
GET	/api/v5/product/{id}/exists	client.product().exists(id)
GET	/api/v5/product/count	client.product().count()

17.13 Path (2 Stück)

HTTP	Endpunkt	Methode
GET	/api/v5/path/asset/{id}	client.path().getByAsset(assetId)
GET	/api/v5/path/tag/{id}	client.path().getByTag(tagId)

17.14 Flow (3 Stück)

HTTP	Endpunkt	Methode
GET	/api/v5/flow/{id}	client.flow().get(flowId)
GET	/api/v5/flow	client.flow().list()
GET	/api/v5/flow/{id}/node	client.flow().listNodes(flowId)

---

17.15 Statistik

Die folgenden Zahlen zählen nur Pfade, die über plantpulse-api Client-Methoden verfügen.

Domain	Anzahl Endpunkte
System	1
Site	6
OPC	10
Asset	6
Tag	23 (CRUD 5 + Liste 7 + Count 4 + PATCH 10)
Alarm	2
Order	11 (CRUD 6 + Lebenszyklus 5)
Calendar	6
Customer	8
Employee	7
Product	7
Path	2
Flow	3
Gesamt	92 (+ Authentifizierung 1)

17.16 HTTP-Methodenverteilung

HTTP	Anzahl	Verwendung
GET	56	Abfrage (Einzeldatensatz/Liste/Existenzprüfung/Count)
POST	16	Registrierung + Order-Lebenszyklus
PUT	10	Vollständige Änderung
PATCH	10	Teilweise Änderung pro Tag-Tab
DELETE	10	Löschen

17.17 Listen vollständig lesen — Cursor

GET /api/v5/site · /product · /customer · /employee verwenden einen Cursor zum sequentiellen Lesen. Die Seitengröße limit beträgt standardmäßig 100, maximal 1000 (bei größeren Werten wird auf 1000 reduziert); beim ersten Aufruf wird cursor nicht mitgesendet.

curl -H "X-API-Key: $TOKEN" "$BASE/api/v5/site?limit=500"
curl -H "X-API-Key: $TOKEN" "$BASE/api/v5/site?limit=500&cursor=<next_cursor>"

{
  "data": [ ],
  "meta": {
    "status": "OK",
    "pagination": { "limit": 500, "total": 1234 },
    "cursor": { "next_cursor": "…", "has_more": true, "limit": 500 }
  },
  "errors": null
}

• data ist das Zeilenarray dieser Seite.
• meta.pagination.total ist die Gesamtzahl der Datensätze für denselben Filter.
• next_cursor wird unverändert als cursor an den nächsten Aufruf übergeben, bis meta.cursor.has_more zu false wird.
• Der Cursor ist an die jeweilige Liste und den Filter gebunden. Die Verwendung eines Cursors einer anderen Liste oder eines Aufrufs mit geänderten site_id führt zu einem 422 E1002.
• Kunden, Produkte und Mitarbeiter sind nach ID sortiert, Sites nach Name · ID. Zeilen, die während des Lesens geändert werden, gehen nicht verloren.

Die Methode list() des Java-Clients gibt nur die erste Seite zurück, da sie cursor nicht übermittelt. Verwenden Sie REST, um die gesamte Liste zu lesen.

17.18 Empfang nur bei Änderungen — ETag von /tag/export

GET /api/v5/tag/export liefert Tags für Site, Verbindung oder die gesamte Anlage in einem Aufruf. Die Filterung erfolgt über site_id · opc_id; bei include=config wird die Konfiguration pro Zeile mitgeliefert (einzelne Aufrufe der Konfiguration pro Tag sind somit nicht erforderlich). Die Antwort erfolgt als data = {tags: [...], count: N}.

Speichern Sie den Wert von ETag der Antwort und geben Sie ihn beim nächsten Lesen als If-None-Match zurück.

curl -i -H "X-API-Key: $TOKEN" "$BASE/api/v5/tag/export?site_id=SITE_000001&include=config"
# ETag: "<SHA-256>"

curl -i -H "X-API-Key: $TOKEN" -H 'If-None-Match: "<SHA-256>"' \
  "$BASE/api/v5/tag/export?site_id=SITE_000001&include=config"
# 304 Not Modified — 본문 없음

• ETag ist der SHA-256-Hash des exportierten data. Wenn sich die sichtbaren Daten ändern — Änderungen an Tags oder Konfigurationen, Hinzufügen · Löschen von Tags, Verschiebung einer Verbindung zu einer anderen Site — ändert sich der Wert unabhängig vom Auslöser. Wenn keine Änderung vorliegt, bleibt der Wert gleich, selbst nach einem Neustart oder bei Abfrage von einem anderen Knoten.
• Es werden auch schwache Formate W/"…" und * akzeptiert, die von Proxys angehängt wurden.
• 304 spart lediglich die Übertragung und das Parsing, nicht den Lesevorgang. Der Server liest alle Zeilen, um den Wert zu berechnen. Rufen Sie die Daten nicht häufiger ab, als das Update-Intervall der Daten erfordert.

---

KOPENS All rights reserved.