Skip to main content
Die REST-API gibt externen Systemen Zugriff auf die Assets eines Mandanten: lesen, abfragen, anlegen. Sie liefert dieselben Daten wie die Oberfläche unter denselben Rechten — nicht mehr und nicht weniger.

​
Was die API kann

Die API arbeitet ausschließlich mit Assets: den Systemen, Geräten, Anwendungen und manuell angelegten Objekten des Inventars. Sie kann
  • Assets auflisten und lesen — einzeln oder seitenweise,
  • Assets abfragen — mit Filter, Sortierung und Feldauswahl,
  • Assets anlegen — einzeln oder bis zu 100 in einem Aufruf.
Sie kann nicht: Scans starten, Risiken oder Maßnahmen bearbeiten, Dokumente lesen oder schreiben. Dafür gibt es keine Endpunkte.
Die API wächst mit dem Produkt. Weitere Bereiche — ITAM, ISMS, Dokumente — folgen; die Referenz zeigt jeweils den aktuellen Stand.

​
Schlüssel und Rechte

Jeder Aufruf trägt einen API-Schlüssel im Header x-api-key. Schlüssel legen Sie unter Verwaltung › API-Schlüssel an; wie das geht, steht unter API-Schlüssel verwalten. Ein Schlüssel gehört einem Benutzer, und dessen Rechte gelten: Was dieser Benutzer in der Oberfläche nicht sieht, liefert die API auch nicht. Fehlende Rechte erzeugen keinen Fehler, sondern eine kleinere Ergebnismenge. Jeder Schlüssel trägt die Berechtigung Lesen; Schreiben lässt sich zusätzlich vergeben. Lesende Endpunkte verlangen Lesen, POST /asset und POST /asset/bulk verlangen Schreiben.
Geliefert werden nur aktive Assets. Gelöschte, archivierte und ausgeblendete Assets erreicht die API nicht — auch nicht über einen Filter auf status.

​
Der erste Aufruf

Die Antwort ist eine Seite mit höchstens 50 Assets. Enthält sie einen cursor, gibt es weitere Seiten — dazu unten.

​
Abfrage, Cursor, Details

Die Referenz kennt sieben Endpunkte. Drei Begriffe erklären, wie sie zusammenhängen: Abfrage. POST /assets/query ist der Weg für alles, was über eine einfache Liste hinausgeht: Filter auf Felder, Sortierung, Auswahl der zurückgegebenen Felder. Felder mit dem Präfix data. adressieren die Daten des Typs — welche es gibt, sagt das Datenmodell. Cursor. Große Ergebnisse kommen seitenweise. Jede Antwort, die nicht vollständig ist, trägt einen cursor; POST /cursor/continue liefert damit die nächste Seite. Cursor sind an Mandant und Benutzer gebunden und verfallen nach einer Stunde. Details. Ein Asset besteht aus Stammdaten und Details: den Daten seines Typs, der Kurzansicht, typisierten Blöcken, untergeordneten Assets. In einer Abfrage laden Sie Details über expands mit; für ein einzelnes Asset lädt POST /assets/expand sie seitenweise nach.
Der Expand object_blocks ist der teure Fall: Ein Asset trägt im Mittel mehrere tausend Blöcke. Fordern Sie ihn nur mit limit oder filter an.

​
Typen

Jedes Asset hat einen Typ — schemaId in der API. Der Typ bestimmt, welche Felder objectData trägt und welche data.-Pfade sich abfragen lassen. Die Typen mit ihren Feldern stehen im Datenmodell; für das Anlegen eines Assets brauchen Sie die schemaId des passenden Typs.

​
Weiterführend