Skip to main content

Node Navigation

Exploring Document Structures

This guide covers retrieving individual nodes, listing child nodes, understanding node relationships, and navigating document hierarchies. For document management basics, see Document Management.

Retrieving Nodes​

Node retrieval enables you to access individual content elements by identifier. Each node carries complete information including content, positions, metadata, embeddings, and relationships. This information enables you to understand node context, navigate document structures, and access specific content elements.

To retrieve a node, provide the node identifier and root node identifier. The root node identifier groups nodes by document, enabling efficient queries that understand document boundaries. The response includes complete node information, enabling you to access content, understand relationships, and navigate hierarchies.

Node retrieval returns nodes regardless of processing state, so you can access nodes even while processing is in progress. This enables progressive access to content as it becomes available, supporting the bonsai philosophy of selective, attentive processing.

GET /v1/nodes/node-123?root_node_id=corpus-456
Authorization: Bearer <your-token>

See the API Reference for complete endpoint documentation.

Listing Child Nodes​

Child node listing enables you to explore document hierarchies by retrieving nodes that belong to a specific parent. This operation supports pagination, enabling efficient navigation through large document structures without loading complete hierarchies.

The list operation accepts a root node identifier and optional filters for node types. You can list all child nodes, or filter to specific types like text nodes or image nodes. This filtering enables focused exploration that matches your navigation needs.

List results include pagination tokens enabling you to retrieve additional pages. The response includes total counts indicating hierarchy sizes, enabling you to understand document structure and plan navigation strategies. Results are ordered to preserve document structure, enabling sequential navigation through content.

GET /v1/nodes/children?root_node_id=corpus-456&parent_node_id=node-100&node_types=TEXT&page_size=20
Authorization: Bearer <your-token>
Efficient Navigation
  • Use node type filters to focus on relevant content types
  • Leverage pagination for large document hierarchies
  • Use total_count to understand structure size before navigation
  • Combine with search to find entry points, then navigate from there

Understanding Node Relationships​

Nodes maintain relationships that enable hierarchical and sequential navigation. Parent-child relationships create vertical hierarchies where nodes contain other nodes, enabling navigation from containers to contents. Sequential relationships create horizontal flows where nodes link to their successors, enabling navigation through reading order.

The node response includes parent and next node identifiers when relationships exist. You can use these identifiers to navigate hierarchies: follow parent links to move upward toward document roots, or follow next links to move laterally through sequential content. This navigation enables exploration of document structures without requiring complete hierarchy loading.

Hierarchical paths provide encoded lineage from root to node, enabling efficient queries that find descendants, identify ancestors, and count nodes at specific depths. These paths enable structural queries that understand document organization without requiring tree traversal.

Relationship Types
  • Parent-child: Vertical hierarchy (containment relationships)
  • Sequential: Horizontal flow (reading order)
  • Ancestral paths: Encoded lineage for efficient queries

For detailed information about node structure, see the Node concept documentation.

Document navigation combines node retrieval and child listing to explore complete document hierarchies. Start with the corpus node to understand document metadata, then list child nodes to discover document structure. Retrieve specific nodes to access content, and use relationships to navigate between related nodes.

Navigation patterns depend on your use case:

Follow sequential links to move through content in reading order. Start with the first node and follow next_node_id links to read through the document sequentially.

The navigation system supports progressive exploration where you discover structure incrementally rather than loading complete hierarchies. This approach enables efficient navigation of large documents while maintaining flexibility to explore different paths based on your needs.

import requests

headers = {"Authorization": "Bearer <your-token>"}

# Start with corpus
corpus_id = "corpus-123"
response = requests.get(
    f"https://<your_domain>/v1/corpus/{corpus_id}",
    headers=headers
)
corpus = response.json()

# List child nodes (ARTIFACT)
response = requests.get(
    f"https://<your_domain>/v1/nodes/children",
    headers=headers,
    params={"root_node_id": corpus_id}
)
children = response.json()

# Navigate to first child
if children["nodes"]:
    first_node_id = children["nodes"][0]["node_id"]
    response = requests.get(
        f"https://<your_domain>/v1/nodes/{first_node_id}",
        headers=headers,
        params={"root_node_id": corpus_id}
    )
    node = response.json()
    print(f"Content: {node['content']}")

    # Follow sequential link
    if node.get("next_node_id"):
        next_response = requests.get(
            f"https://<your_domain>/v1/nodes/{node['next_node_id']}",
            headers=headers,
            params={"root_node_id": corpus_id}
        )
        next_node = next_response.json()
        print(f"Next: {next_node['content']}")

Next Steps​

Now that you understand node navigation, explore:

  1. Search Operations: Find nodes to navigate from
  2. Common Patterns: Real-world navigation workflows
  3. Node Concept: Deep dive into node structure and relationships
Related Concepts

Understanding these concepts will help you navigate effectively:

  • Node: The fundamental unit you're navigating
  • Position: Understanding where nodes are located
  • Metadata: Additional information stored in nodes