Knotentypen und Hierarchie

Jede Ressource der RealityConnect API wird über eine Inhaltshierarchie aus typisierten Knoten adressiert. Diese Seite katalogisiert die 10 Knotentypen, die Eltern-Kind-Regeln, die diesen Baum gültig halten, und welche Typen direkt erstellt werden können gegenüber solchen, die nur als Ergebnis einer anderen Aktion entstehen.

Knotentypen

DataNodeType hat 10 Werte. Nur Division, Site und Folder werden direkt über einen Knotenerstellungs-Endpunkt erstellt; jeder andere Typ entsteht als Nebeneffekt einer domänenspezifischen Aktion: ein Upload, eine Bundle-Erstellung, eine Verarbeitung oder eine Plattform-/Admin-Operation.

Typ	Was er ist	Erstellt durch
`Organization`	Die Wurzel des Baums. Jeder andere Knoten ist ihr Nachfahre. `parentId` ist `null`.	Wird beim Anlegen der Organisation bereitgestellt; niemals über die API
`Division`	Eine übergeordnete Gruppierung unter der Organisation (z. B. eine Geschäftseinheit oder Region).	`POST /v1/nodes/{parentId}/division`
`Site`	Ein physischer Standort unter einer Division. Enthält Datenbündel und ist die Einheit, die von den Twin- und Suchrouten adressiert wird.	`POST /v1/nodes/{parentId}/site`
`Folder`	Eine verschachtelbare Gruppierung zur Organisation von Inhalten unter einem Standort oder einem anderen Ordner.	`POST /v1/nodes/{parentId}/folder`
`Project`	Ein RealityPlan-Designprojekt.	`POST /v1/bundles/{bundleId}/create-project`, sobald ein Datenbündel eine verarbeitete, anzeigbare Komponente hat
`Twin`	Der 3D-Raumdeskriptor eines Standorts. Ein Twin wird über die Knoten-ID seines Standorts adressiert, daher gibt es keinen eigenen Erstellungsschritt.	Plattformaktion (Veröffentlichung eines Twins)
`DataBundle`	Ein erfasster Datensatz (Punktwolke, Mesh, Panoramen usw.) und seine Verarbeitungsergebnisse.	`POST /v1/nodes/{parentId}/bundle`, mit einem aufgelösten `dbuPath`
`SiteFile`	Eine roh hochgeladene Datei, die nicht Teil eines Datenbündels ist.	`POST /v1/site-files` (ein eigener Upload-Ablauf, kein Knotenerstellungs-Endpunkt)
`Artifact`	Ein Anhang oder Ausgabeartefakt, das mit Twin-Inhalten verknüpft ist.	Plattform-/Verarbeitungsaktion
`AssetLibrary`	Eine organisationsweite Bibliothek wiederverwendbarer Modelle.	Wird auf Organisationsebene bereitgestellt; niemals über die API

Eltern-Kind-Regeln und Tiefe

Die drei erstellbaren Typen bilden ein festes Rückgrat, wobei jeder genau einen Elterntyp akzeptiert:

Elternteil	Akzeptiert Kindtyp	Route
`Organization`	`Division`	`POST /v1/nodes/{parentId}/division`
`Division`	`Site`	`POST /v1/nodes/{parentId}/site`
`Site` oder `Folder`	`Folder`	`POST /v1/nodes/{parentId}/folder`

Folder ist der einzige Typ, der unter seinem eigenen Typ verschachtelt wird, weshalb dort die Tiefe durch einen einzigen API-Aufruf beliebig wachsen kann. Die Plattform erzwingt jenseits dieses Rückgrats eine maximale Hierarchietiefe; sie veröffentlicht keine exakte Zahl, aber die beiden folgenden Fehlercodes existieren genau, um eine Anfrage abzufangen, die diese Tiefe überschreiten oder einen Knoten falsch platzieren würde:

MaxDepthExceeded (zurückgegeben von PATCH /v1/nodes/{nodeId}/move/{newParentId}): Das Ziel würde den Knoten tiefer verschieben, als die Plattform erlaubt. Verschieben Sie den Knoten an eine flachere Position, anstatt Ordner beliebig zu verschachteln.
DoesNotMeetHierarchyConstraints (ebenfalls vom Verschiebe-Endpunkt zurückgegeben): Der Zielelternknoten akzeptiert den Typ dieses Knotens nicht. Prüfen Sie die obige Tabelle (oder die tatsächliche Position des Typs über Browse), bevor Sie ihn verschieben.

Das Erstellen eines Knotens unter dem falschen Elterntyp wird auf dieselbe Weise abgelehnt: POST /v1/nodes/{parentId}/site mit einer parentId, die keine Division ist, liefert 409 { "error": "ParentTypeNotValid" }.

Die vollständige Antwortstruktur und alle weiteren Verschiebe-/Löschcodes finden Sie unter Fehlercodes.

DataBundle-Knoten werden unter einem Standort oder Ordner erstellt, und SiteFile-Knoten werden unter einer an den Upload-Ablauf übergebenen Eltern-ID erstellt. Beide akzeptieren praktisch dieselben zwei Elterntypen wie Folder, jedoch über ihre eigenen domänenspezifischen Endpunkte statt über eine generische Knotenerstellungsroute. Die übrigen Typen (Twin, Artifact, AssetLibrary) werden durch die jeweilige Plattform- oder Verarbeitungsaktion positioniert, die sie erzeugt, durchsuchen Sie daher den Baum, um sie zu finden, statt einen festen Platz anzunehmen.

Die DataNode-Struktur

GET /v1/nodes/{id}/browse und GET /v1/nodes/search liefern Knoten beide in dieser Struktur zurück:

{
  "id": "a6f75b3c-f261-4b27-9a2a-9a6cc1234c53",
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:00:00.000Z",
  "name": "Building A",
  "type": "Site",
  "createdById": "8f0b9a2c-8f1b-4a10-9e1c-0b3a2d9a4b7d",
  "parentId": "d2a1c4b7-3e10-4f2c-9a6b-7c1d8e2f3a45",
  "childrenCount": 4,
  "bytesStored": 15728640,
  "thumbnailSignedUrl": null
}

Feld	Hinweise
`type`	Einer der 10 oben genannten `DataNodeType`-Werte
`parentId`	Nur bei der `Organization`-Wurzel `null`
`childrenCount`	Nur direkte Kinder, nicht der gesamte Teilbaum
`bytesStored`	Speichergröße des Teilbaums in Bytes
`thumbnailSignedUrl`	Optional. Nur vorhanden, wenn die Anfrage mit `includeThumbnail=true` explizit zustimmt und ein Thumbnail existiert

Browse und Suche im Vergleich

Beide Routen liefern dieselbe DataNode-Struktur, beantworten aber unterschiedliche Fragen und haben unterschiedliche Limits:

	`GET /v1/nodes/{id}/browse`	`GET /v1/nodes/search`
Beantwortet	„Was sind die direkten Kinder dieses Knotens?”	„Finde Knoten, die diesen Filtern entsprechen, überall wo ich Zugriff habe”
Umfang	Direkte Kinder eines Knotens	Der gesamte Organisationsbaum, der mit dem Access Token verknüpft ist
`limit`	1–20	1–50
Standard-`limit`	20	50
Filterung	Keine, nur Paginierung und Sortierung	Name, Typ, Eltern-/Vorfahrknoten, Ersteller, Zeitstempel, Speichergröße, Kinderanzahl

Zur Vorgehensweise beim Auflösen Ihrer ersten Knoten-ID und dem Aufruf von Browse siehe Ihre IDs finden. Für die vollständige Liste der search-Query-Parameter, Filterkombinationen und Beispiele siehe Business-Objekte und Knoten durchsuchen.

Twin-, DataBundle- und AssetLibrary-Knoten erscheinen in Browse- und Suchergebnissen wie jeder andere Knoten, aber sobald Sie deren ID haben, adressieren Sie deren Inhalte über eine andere Routenfamilie statt über /v1/nodes:

Knotentyp	Adressiert über die ID unter
`Twin`	`/v1/twin/{contextId}/...` (Raumdeskriptor, Business-Objekt-Suche)
`DataBundle`	`/v1/bundles/{bundleId}/...` (Komponenten, Verarbeitungen, Verarbeitungsoptionen)
`AssetLibrary`	`/v1/asset-library/...` (als `ownerContextId`)

Wie geht es weiter?

Fehlercodes für alle Verschiebe-/Lösch-/Erstell-Fehlercodes und deren Behandlung.
Business-Objekte und Knoten durchsuchen für die vollständige search-Query-Oberfläche.