Types de nœuds et hiérarchie

Chaque ressource de l’API RealityConnect est adressée via une hiérarchie de contenu composée de nœuds typés. Cette page recense les 10 types de nœuds, les règles parent/enfant qui maintiennent cet arbre valide, et quels types peuvent être créés directement par rapport à ceux qui n’apparaissent qu’en résultat d’une autre action.

Types de nœuds

DataNodeType compte 10 valeurs. Seuls Division, Site et Folder sont créés directement via un point de terminaison de création de nœud ; tout autre type est produit comme effet secondaire d’une action spécifique à un domaine : un téléversement, la création d’un bundle, un traitement ou une opération de plateforme/administration.

Type	Ce que c’est	Créé par
`Organization`	La racine de l’arbre. Tout autre nœud en est un descendant. `parentId` vaut `null`.	Provisionné à la création de l’organisation ; jamais via l’API
`Division`	Un regroupement de premier niveau sous l’organisation (par ex. une unité commerciale ou une région).	`POST /v1/nodes/{parentId}/division`
`Site`	Un emplacement physique sous une division. Contient des bundles de données et constitue l’unité adressée par les routes de twin et de recherche.	`POST /v1/nodes/{parentId}/site`
`Folder`	Un regroupement imbricable pour organiser le contenu sous un site ou un autre dossier.	`POST /v1/nodes/{parentId}/folder`
`Project`	Un RealityPlan Project (projet de conception).	`POST /v1/bundles/{bundleId}/create-project`, une fois qu’un bundle de données possède un composant traité et visualisable
`Twin`	Le descripteur d’espace 3D d’un site. Un twin est adressé par l’id de nœud de son site, il n’y a donc pas d’étape de création dédiée.	Action de plateforme (publication d’un twin)
`DataBundle`	Un jeu de données capturé (nuage de points, mesh, panoramas, etc.) et ses résultats de traitement.	`POST /v1/nodes/{parentId}/bundle`, avec un `dbuPath` résolu
`SiteFile`	Un fichier téléversé brut ne faisant pas partie d’un bundle de données.	`POST /v1/site-files` (un flux de téléversement dédié, pas un point de terminaison de création de nœud)
`Artifact`	Une pièce jointe ou un artefact de sortie associé au contenu d’un twin.	Action de plateforme/traitement
`AssetLibrary`	Une bibliothèque de modèles réutilisables au niveau de l’organisation.	Provisionnée au niveau de l’organisation ; jamais via l’API

Règles parent/enfant et profondeur

Les trois types créables forment une ossature fixe, chacun n’acceptant qu’un seul type parent :

Parent	Accepte le type enfant	Route
`Organization`	`Division`	`POST /v1/nodes/{parentId}/division`
`Division`	`Site`	`POST /v1/nodes/{parentId}/site`
`Site` ou `Folder`	`Folder`	`POST /v1/nodes/{parentId}/folder`

Folder est le seul type qui s’imbrique sous son propre type, c’est donc le seul endroit où la profondeur peut croître arbitrairement à partir d’un seul appel API. Au-delà de cette ossature, la plateforme impose une profondeur de hiérarchie maximale ; elle ne publie pas de chiffre exact, mais les deux codes d’erreur suivants existent précisément pour intercepter une requête qui la dépasserait ou placerait un nœud au mauvais endroit :

MaxDepthExceeded (renvoyé par PATCH /v1/nodes/{nodeId}/move/{newParentId}) : la destination pousserait le nœud plus profond que ce que la plateforme autorise. Déplacez le nœud vers une position moins profonde plutôt que d’imbriquer les dossiers indéfiniment.
DoesNotMeetHierarchyConstraints (également renvoyé par le point de terminaison de déplacement) : le parent de destination n’accepte pas le type de ce nœud. Vérifiez le tableau ci-dessus (ou la position réelle du type, via le parcours) avant de le déplacer.

Créer un nœud sous le mauvais type de parent est rejeté de la même façon : POST /v1/nodes/{parentId}/site avec un parentId qui n’est pas une Division renvoie 409 { "error": "ParentTypeNotValid" }.

Consultez Codes d’erreur pour la structure complète des réponses et tous les autres codes de déplacement/suppression.

Les nœuds DataBundle sont créés sous un site ou un dossier, et les nœuds SiteFile sont créés sous un id parent transmis au flux de téléversement. Les deux acceptent en pratique les deux mêmes types de parent que Folder, mais via leurs propres points de terminaison spécifiques plutôt qu’une route générique de création de nœud. Les types restants (Twin, Artifact, AssetLibrary) sont positionnés par l’action de plateforme ou de traitement qui les produit ; parcourez donc l’arbre pour les trouver plutôt que de supposer un emplacement fixe.

La structure du DataNode

GET /v1/nodes/{id}/browse et GET /v1/nodes/search renvoient tous deux les nœuds dans cette structure :

{
  "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
}

Champ	Remarques
`type`	Une des 10 valeurs `DataNodeType` ci-dessus
`parentId`	`null` uniquement pour la racine `Organization`
`childrenCount`	Enfants directs uniquement, pas tout le sous-arbre
`bytesStored`	Taille de stockage du sous-arbre en octets
`thumbnailSignedUrl`	Optionnel. Présent uniquement si la requête l’active avec `includeThumbnail=true`, et seulement si une miniature existe

Parcourir ou rechercher

Les deux routes renvoient la même structure DataNode, mais répondent à des questions différentes et ont des limites différentes :

	`GET /v1/nodes/{id}/browse`	`GET /v1/nodes/search`
Répond à	« Quels sont les enfants directs de ce nœud ? »	« Trouve les nœuds correspondant à ces filtres, partout où j’ai accès »
Portée	Enfants directs d’un nœud	Tout l’arbre de l’organisation lié au jeton d’accès
`limit`	1–20	1–50
`limit` par défaut	20	50
Filtrage	Aucun, pagination et tri uniquement	Nom, type, parent/ancêtre, créateur, horodatages, taille de stockage, nombre d’enfants

Pour la mécanique de résolution de votre premier id de nœud et l’appel à browse, voir Trouver vos IDs. Pour l’ensemble complet des paramètres de requête search, des combinaisons de filtres et des exemples, voir Rechercher des objets métier et des nœuds.

Les nœuds Twin, DataBundle et AssetLibrary apparaissent dans les résultats de parcours et de recherche comme n’importe quel autre nœud, mais une fois leur id obtenu, vous adressez leur contenu via une autre famille de routes plutôt que /v1/nodes :

Type de nœud	Adressé par son id à
`Twin`	`/v1/twin/{contextId}/...` (descripteur d’espace, recherche d’objets métier)
`DataBundle`	`/v1/bundles/{bundleId}/...` (composants, traitements, options de traitement)
`AssetLibrary`	`/v1/asset-library/...` (en tant que `ownerContextId`)

Et ensuite ?

Codes d’erreur pour tous les codes d’erreur de déplacement/suppression/création et leur traitement.
Rechercher des objets métier et des nœuds pour l’ensemble complet des paramètres de requête search.