Tipos de nó e hierarquia

Todo recurso da API RealityConnect é endereçado por meio de uma hierarquia de conteúdo formada por nós tipados. Esta página cataloga os 10 tipos de nó, as regras de pai/filho que mantêm essa árvore válida, e quais tipos podem ser criados diretamente em comparação aos que só aparecem como resultado de outra ação.

Tipos de nó

DataNodeType tem 10 valores. Apenas Division, Site e Folder são criados diretamente por um endpoint de criação de nó; qualquer outro tipo é produzido como efeito colateral de uma ação específica de domínio: um upload, a criação de um bundle, um processamento ou uma operação de plataforma/administração.

Tipo	O que é	Criado por
`Organization`	A raiz da árvore. Todos os demais nós são seus descendentes. `parentId` é `null`.	Provisionado na criação da organização; nunca pela API
`Division`	Um agrupamento de nível superior sob a organização (por exemplo, uma unidade de negócio ou região).	`POST /v1/nodes/{parentId}/division`
`Site`	Um local físico sob uma divisão. Contém data bundles e é a unidade endereçada pelas rotas de twin e busca.	`POST /v1/nodes/{parentId}/site`
`Folder`	Um agrupamento aninhável para organizar conteúdo sob um site ou outra pasta.	`POST /v1/nodes/{parentId}/folder`
`Project`	Um RealityPlan Project.	`POST /v1/bundles/{bundleId}/create-project`, assim que um data bundle tiver um componente processado e visualizável
`Twin`	O descritor de espaço 3D de um site. Um twin é endereçado pelo id de nó do seu site, portanto não há uma etapa de criação própria.	Ação de plataforma (publicação de um twin)
`DataBundle`	Um conjunto de dados capturado (nuvem de pontos, malha, panoramas etc.) e seus resultados de processamento.	`POST /v1/nodes/{parentId}/bundle`, com um `dbuPath` resolvido
`SiteFile`	Um arquivo enviado em bruto que não faz parte de um data bundle.	`POST /v1/site-files` (um fluxo de upload dedicado, não um endpoint de criação de nó)
`Artifact`	Um anexo ou artefato de saída associado ao conteúdo de um twin.	Ação de plataforma/processamento
`AssetLibrary`	Uma biblioteca de modelos reutilizáveis no nível da organização.	Provisionada no nível da organização; nunca pela API

Regras de pai/filho e profundidade

Os três tipos criáveis formam uma estrutura fixa, cada um aceitando exatamente um tipo pai:

Pai	Aceita o tipo filho	Rota
`Organization`	`Division`	`POST /v1/nodes/{parentId}/division`
`Division`	`Site`	`POST /v1/nodes/{parentId}/site`
`Site` ou `Folder`	`Folder`	`POST /v1/nodes/{parentId}/folder`

Folder é o único tipo que se aninha sob seu próprio tipo, então é o único lugar onde a profundidade pode crescer arbitrariamente a partir de uma única chamada de API. Além dessa estrutura, a plataforma impõe uma profundidade máxima de hierarquia; ela não publica um número exato, mas os dois códigos de erro abaixo existem justamente para capturar uma requisição que a excederia ou posicionaria um nó no lugar errado:

MaxDepthExceeded (retornado por PATCH /v1/nodes/{nodeId}/move/{newParentId}): o destino deixaria o nó mais profundo do que a plataforma permite. Mova o nó para uma posição mais rasa em vez de aninhar pastas indefinidamente.
DoesNotMeetHierarchyConstraints (também retornado pelo endpoint de movimentação): o pai de destino não aceita o tipo deste nó. Verifique a tabela acima (ou a posição real do tipo, via navegação) antes de movê-lo.

Criar um nó sob o tipo de pai errado é rejeitado da mesma forma: POST /v1/nodes/{parentId}/site com um parentId que não seja uma Division retorna 409 { "error": "ParentTypeNotValid" }.

Consulte Códigos de erro para a estrutura completa da resposta e todos os demais códigos de movimentação/exclusão.

Os nós DataBundle são criados sob um site ou pasta, e os nós SiteFile são criados sob um id pai passado ao fluxo de upload. Ambos aceitam, na prática, os mesmos dois tipos de pai que Folder, mas por meio de seus próprios endpoints específicos de domínio em vez de uma rota genérica de criação de nó. Os tipos restantes (Twin, Artifact, AssetLibrary) são posicionados pela ação de plataforma ou processamento que os produz, portanto navegue pela árvore para encontrá-los em vez de presumir uma posição fixa.

A estrutura do DataNode

GET /v1/nodes/{id}/browse e GET /v1/nodes/search retornam os nós nesta estrutura:

{
  "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	Observações
`type`	Um dos 10 valores de `DataNodeType` acima
`parentId`	`null` apenas para a raiz `Organization`
`childrenCount`	Apenas filhos diretos, não a subárvore inteira
`bytesStored`	Tamanho de armazenamento da subárvore em bytes
`thumbnailSignedUrl`	Opcional. Presente apenas quando a requisição opta por isso com `includeThumbnail=true`, e apenas quando existe uma miniatura

Navegar versus pesquisar

Ambas as rotas retornam a mesma estrutura DataNode, mas respondem a perguntas diferentes e têm limites diferentes:

	`GET /v1/nodes/{id}/browse`	`GET /v1/nodes/search`
Responde	”Quais são os filhos diretos deste nó?"	"Encontre nós que correspondam a estes filtros, em qualquer lugar onde eu tenha acesso”
Escopo	Filhos diretos de um nó	Toda a árvore da organização vinculada ao token de acesso
`limit`	1–20	1–50
`limit` padrão	20	50
Filtragem	Nenhuma, apenas paginação e ordenação	Nome, tipo, pai/ancestral, criador, timestamps, tamanho de armazenamento, número de filhos

Para a mecânica de resolver seu primeiro id de nó e chamar o browse, veja Encontrando seus IDs. Para o conjunto completo de parâmetros de consulta do search, combinações de filtros e exemplos, veja Pesquisando objetos de negócio e nós.

Os nós Twin, DataBundle e AssetLibrary aparecem em resultados de navegação e pesquisa como qualquer outro nó, mas, uma vez obtido o id, você endereça seu conteúdo por meio de outra família de rotas em vez de /v1/nodes:

Tipo de nó	Endereçado pelo id em
`Twin`	`/v1/twin/{contextId}/...` (descritor de espaço, pesquisa de objetos de negócio)
`DataBundle`	`/v1/bundles/{bundleId}/...` (componentes, processamentos, opções de processamento)
`AssetLibrary`	`/v1/asset-library/...` (como `ownerContextId`)

O que vem a seguir?

Códigos de erro para todos os códigos de erro de movimentação/exclusão/criação e como tratá-los.
Pesquisando objetos de negócio e nós para a superfície completa de parâmetros do search.