Tipos de nodo y jerarquía

Todos los recursos de la API de RealityConnect se direccionan a través de una jerarquía de contenido formada por nodos tipados. Esta página cataloga los 10 tipos de nodo, las reglas padre/hijo que mantienen ese árbol válido, y qué tipos se pueden crear directamente frente a los que solo aparecen como resultado de otra acción.

Tipos de nodo

DataNodeType tiene 10 valores. Solo Division, Site y Folder se crean directamente mediante un endpoint de creación de nodos; cualquier otro tipo se produce como efecto secundario de una acción específica de dominio: una carga, la creación de un bundle, un procesamiento o una operación de plataforma/administración.

Tipo	Qué es	Creado por
`Organization`	La raíz del árbol. Todos los demás nodos son sus descendientes. `parentId` es `null`.	Se aprovisiona al crear la organización; nunca a través de la API
`Division`	Una agrupación de nivel superior bajo la organización (por ejemplo, una unidad de negocio o una región).	`POST /v1/nodes/{parentId}/division`
`Site`	Una ubicación física bajo una división. Contiene bundles de datos y es la unidad a la que direccionan las rutas de twin y búsqueda.	`POST /v1/nodes/{parentId}/site`
`Folder`	Una agrupación anidable para organizar contenido bajo un site u otra carpeta.	`POST /v1/nodes/{parentId}/folder`
`Project`	Un RealityPlan Project.	`POST /v1/bundles/{bundleId}/create-project`, una vez que un bundle de datos tiene un componente procesado y visualizable
`Twin`	El descriptor de espacio 3D de un site. Un twin se direcciona por el id de nodo de su site; no hay un paso de creación independiente.	Acción de plataforma (publicación de un twin)
`DataBundle`	Un conjunto de datos capturado (nube de puntos, malla, panoramas, etc.) y sus resultados de procesamiento.	`POST /v1/nodes/{parentId}/bundle`, con un `dbuPath` resuelto
`SiteFile`	Un archivo cargado en bruto que no forma parte de un bundle de datos.	`POST /v1/site-files` (un flujo de carga dedicado, no un endpoint de creación de nodos)
`Artifact`	Un adjunto o artefacto de salida asociado al contenido de un twin.	Acción de plataforma/procesamiento
`AssetLibrary`	Una biblioteca de modelos reutilizables a nivel de organización.	Se aprovisiona a nivel de organización; nunca a través de la API

Reglas padre/hijo y profundidad

Los tres tipos creables forman una estructura fija, cada uno acepta exactamente un tipo padre:

Padre	Acepta el tipo hijo	Ruta
`Organization`	`Division`	`POST /v1/nodes/{parentId}/division`
`Division`	`Site`	`POST /v1/nodes/{parentId}/site`
`Site` o `Folder`	`Folder`	`POST /v1/nodes/{parentId}/folder`

Folder es el único tipo que se anida bajo su propio tipo, por lo que es el único lugar donde la profundidad puede crecer arbitrariamente a partir de una sola llamada a la API. Más allá de esta estructura, la plataforma impone una profundidad máxima de jerarquía; no publica un número exacto, pero los dos códigos de error siguientes existen precisamente para detectar una solicitud que la excedería o colocaría un nodo en el lugar equivocado:

MaxDepthExceeded (devuelto por PATCH /v1/nodes/{nodeId}/move/{newParentId}): el destino haría que el nodo quedara más profundo de lo que permite la plataforma. Mueva el nodo a una posición menos profunda en lugar de anidar carpetas indefinidamente.
DoesNotMeetHierarchyConstraints (también devuelto por el endpoint de movimiento): el padre de destino no acepta el tipo de este nodo. Revise la tabla anterior (o la posición real del tipo, mediante exploración) antes de moverlo.

Crear un nodo bajo el tipo de padre incorrecto se rechaza de la misma manera: POST /v1/nodes/{parentId}/site con un parentId que no es una Division devuelve 409 { "error": "ParentTypeNotValid" }.

Consulte Códigos de error para conocer la estructura completa de la respuesta y todos los demás códigos de movimiento/eliminación.

Los nodos DataBundle se crean bajo un site o una carpeta, y los nodos SiteFile se crean bajo un id padre pasado al flujo de carga; ambos aceptan en la práctica los mismos dos tipos de padre que Folder, pero a través de sus propios endpoints específicos de dominio en lugar de una ruta genérica de creación de nodos. Los tipos restantes (Twin, Artifact, AssetLibrary) se posicionan según la acción de plataforma o procesamiento que los produce: explore el árbol para encontrarlos en lugar de asumir una ubicación fija.

La estructura del DataNode

GET /v1/nodes/{id}/browse y GET /v1/nodes/search devuelven los nodos con esta estructura:

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

Campo	Notas
`type`	Uno de los 10 valores de `DataNodeType` anteriores
`parentId`	`null` solo para la raíz `Organization`
`childrenCount`	Solo hijos directos, no todo el subárbol
`bytesStored`	Tamaño de almacenamiento del subárbol en bytes
`thumbnailSignedUrl`	Opcional. Solo presente cuando la solicitud lo activa con `includeThumbnail=true`, y solo cuando existe una miniatura

Explorar frente a buscar

Ambas rutas devuelven la misma estructura DataNode, pero responden preguntas distintas y tienen límites distintos:

	`GET /v1/nodes/{id}/browse`	`GET /v1/nodes/search`
Responde	”¿Cuáles son los hijos directos de este nodo?"	"Encuentra nodos que coincidan con estos filtros, en cualquier lugar donde tenga acceso”
Alcance	Hijos directos de un nodo	Todo el árbol de la organización vinculado al token de acceso
`limit`	1–20	1–50
`limit` por defecto	20	50
Filtrado	Ninguno: solo paginación y orden	Nombre, tipo, padre/ancestro, creador, marcas de tiempo, tamaño de almacenamiento, número de hijos

Para conocer la mecánica de resolver su primer id de nodo y llamar a browse, consulte Cómo encontrar sus IDs. Para el conjunto completo de parámetros de consulta de search, combinaciones de filtros y ejemplos, consulte Búsqueda de objetos de negocio y nodos.

Los nodos Twin, DataBundle y AssetLibrary aparecen en los resultados de exploración y búsqueda como cualquier otro nodo, pero una vez que tiene su id, se direcciona su contenido a través de otra familia de rutas en lugar de /v1/nodes:

Tipo de nodo	Direccionado por id en
`Twin`	`/v1/twin/{contextId}/...` (descriptor de espacio, búsqueda de objetos de negocio)
`DataBundle`	`/v1/bundles/{bundleId}/...` (componentes, procesamientos, opciones de procesamiento)
`AssetLibrary`	`/v1/asset-library/...` (como `ownerContextId`)

¿Qué sigue?

Códigos de error para todos los códigos de error de movimiento/eliminación/creación y cómo manejarlos.
Búsqueda de objetos de negocio y nodos para la superficie completa de parámetros de search.