@wityai/root2-api-client

Official Root2 API Client for Node.js.

Root2 is the vector memory layer of Wity AI and is available for use on its own. It provides an import → vectorize → semantize pipeline for converting any temporal data stream into vectors. On the downstream side, it offers a querying interface and context integration interface for intelligent information retrieval.

Root2 is model and database agnostic - it's not tied to any specific embedding model or vector database. It can be configured to use a range of embedding models and vector databases, giving you flexibility in your AI infrastructure choices.

With this API Client, you can programmatically manage vector memory blocks, convert data into computable knowledge, query information, and supply dynamic memory context to your AI workflows.

CLI Available

Command Line Interface: A CLI is also available for Root2 operations. For CLI usage information, check out: @wityai/root2-cli

Getting API Key

To get your API key, go to Wity API Clients and create a new client. You will receive a Client ID and API Key to use below.

Installation

Using npm:

npm install @wityai/root2-api-client

Or using yarn:

yarn add @wityai/root2-api-client

Usage Example

import { Root2Api } from "@wityai/root2-api-client";

const apiClient = new Root2Api({
  clientId: process.env.ROOT2_CLIENT_ID!,
  apiKey: process.env.ROOT2_API_KEY!
});

async function main() {
  try {
    // List available memory blocks
    const memoryBlocks = await apiClient.listMyMemoryBlocks();
    console.log("Available Memory Blocks:", memoryBlocks);

    // Import a file
    const fileResult = await apiClient.importFile(
      "mb_1a2b3c4d5e6f7g8h9i0j", // memory block ID
      {
        filePath: "/path/to/document.pdf",
        fileName: "important-document.pdf",
        metadata: { category: "documentation" }
      }
    );

    // Import a directory
    const dirResult = await apiClient.importDir(
      "mb_1a2b3c4d5e6f7g8h9i0j", // memory block ID
      {
        dirPath: "/path/to/documents",
        recursive: true,
        includePattern: "*.{pdf,txt,md}",
        metadata: { source: "local-docs" }
      }
    );

    // Import a webpage
    const webResult = await apiClient.importWebpage(
      "mb_9z8y7x6w5v4u3t2s1r0q", // memory block ID
      {
        url: "https://example.com/article",
        includeLinks: false,
        metadata: { type: "article" }
      }
    );

    // Query information
    const queryResult = await apiClient.queryInfo(
      "What are the main topics discussed?",
      {
        outputFormat: "structured",
        maxResults: 10,
        includeMetadata: true
      }
    );

    console.log("Query Results:", queryResult);
  } catch (err) {
    console.error("Error:", err);
  }
}

main();

API Reference

new Root2Api({ clientId, apiKey, apiHost?, enableLogging? })

Creates a new Root2 API client instance.

Options:

• clientId: Your Root2 client ID
• apiKey: Your Root2 API key
• apiHost: (Optional) API host URL, defaults to https://api.wity.ai
• enableLogging: (Optional) Enable request/response logging, defaults to false

listMyMemoryBlocks()

Lists all memory blocks available to your account.

Returns:

{
  memoryBlocks: Array<{
    id: string;
    name: string;
    description?: string;
    createdAt: string;
    itemCount: number;
  }>
}

importFile(memoryBlockId: string, payload: ImportFilePayload)

Imports a single file into the specified memory block.

Parameters:

• memoryBlockId: ID of the memory block to import the file into (e.g., "mb_1a2b3c4d5e6f7g8h9i0j")

Payload:

{
  filePath: string;          // Path to the file to import
  fileName?: string;         // Optional custom filename
  metadata?: Record<string, any>;  // Optional metadata object
  unitizationConfig?: UnitizationConfig[];  // Optional: Advanced chunking settings
  vectorizationConfig?: VectorizationConfig;  // Optional: Custom embedding settings
}

Note: unitizationConfig and vectorizationConfig are optional advanced settings. Root2 uses intelligent defaults if not specified.

importDir(memoryBlockId: string, payload: ImportDirPayload)

Imports a directory and its contents into the specified memory block.

Parameters:

• memoryBlockId: ID of the memory block to import the directory into (e.g., "mb_1a2b3c4d5e6f7g8h9i0j")

Payload:

{
  dirPath: string;           // Path to the directory to import
  recursive?: boolean;       // Whether to import subdirectories
  includePattern?: string;   // File pattern to include (e.g., "*.pdf")
  excludePattern?: string;   // File pattern to exclude
  metadata?: Record<string, any>;  // Optional metadata object
  unitizationConfig?: UnitizationConfig[];  // Optional: Advanced chunking settings
  vectorizationConfig?: VectorizationConfig;  // Optional: Custom embedding settings
}

importWebpage(memoryBlockId: string, payload: ImportWebpagePayload)

Imports a webpage into the specified memory block.

Parameters:

• memoryBlockId: ID of the memory block to import the webpage into (e.g., "mb_1a2b3c4d5e6f7g8h9i0j")

Payload:

{
  url: string;               // URL of the webpage to import
  includeLinks?: boolean;    // Whether to follow and import linked pages
  maxDepth?: number;         // Maximum depth for link following
  metadata?: Record<string, any>;  // Optional metadata object
  unitizationConfig?: UnitizationConfig[];  // Optional: Advanced chunking settings
  vectorizationConfig?: VectorizationConfig;  // Optional: Custom embedding settings
}

queryInfo(query: string, options?: QueryInfoOptions)

Queries information from your Root2 knowledge base.

Parameters:

• query: The question or search query string
• options: Optional query configuration

Options:

{
  outputFormat?: string;     // Format of the response (e.g., "structured", "text")
  maxResults?: number;       // Maximum number of results to return
  includeMetadata?: boolean; // Whether to include metadata in results
  filters?: Record<string, any>;  // Additional filters to apply
}

Response Format

All methods return a Root2ApiResponse<T> with the following structure:

{
  success: boolean;          // Whether the operation was successful
  data?: T;                  // Response data (if successful)
  error?: string;            // Error message (if failed)
}

Advanced Usage

For users who need more control over how content is processed and vectorized, Root2 provides optional advanced configurations:

Advanced Import Examples

// Advanced file import with custom chunking and vectorization
const advancedFileResult = await apiClient.importFile(
  "mb_1a2b3c4d5e6f7g8h9i0j",
  {
    filePath: "/path/to/technical-document.pdf",
    fileName: "advanced-document.pdf",
    metadata: { category: "technical", complexity: "high" },
    unitizationConfig: [
      {
        modality: "text",
        chunkingStrategy: "sliding-window",
        resolution: 512,
        overlap: 256
      }
    ],
    vectorizationConfig: {
      embeddingModel: "text-embedding-3-small",
      dimensionality: 1536,
      distanceMetric: "cosine",
      indexType: "hnsw",
      normalizationStrategy: "l2"
    }
  }
);

// Advanced directory import with multi-modal processing
const advancedDirResult = await apiClient.importDir(
  "mb_1a2b3c4d5e6f7g8h9i0j",
  {
    dirPath: "/path/to/mixed-content",
    recursive: true,
    includePattern: "*.{pdf,txt,md,py,js,png,jpg}",
    metadata: { source: "codebase", version: "v2.1" },
    unitizationConfig: [
      {
        modality: "text",
        chunkingStrategy: "sliding-window",
        resolution: 512,
        overlap: 256
      },
      {
        modality: "code",
        chunkingStrategy: "function-level",
        resolution: 0
      },
      {
        modality: "image",
        chunkingStrategy: "ROI",
        resolution: "128x128"
      }
    ],
    vectorizationConfig: {
      embeddingModel: "text-embedding-3-large",
      dimensionality: 3072,
      distanceMetric: "cosine",
      indexType: "hnsw",
      normalizationStrategy: "l2"
    }
  }
);

// Advanced webpage import with custom processing
const advancedWebResult = await apiClient.importWebpage(
  "mb_9z8y7x6w5v4u3t2s1r0q",
  {
    url: "https://technical-blog.example.com",
    includeLinks: true,
    maxDepth: 2,
    metadata: { type: "blog", domain: "technical" },
    unitizationConfig: [
      {
        modality: "text",
        chunkingStrategy: "semantic-sections",
        resolution: 1024
      }
    ],
    vectorizationConfig: {
      embeddingModel: "text-embedding-ada-002",
      dimensionality: 1536,
      distanceMetric: "cosine",
      indexType: "flat",
      normalizationStrategy: "none"
    }
  }
);

Advanced Configuration Reference

For most use cases, you can skip these configurations. Root2 uses intelligent defaults that work well for common content types. Use these advanced options only when you need specific control over chunking or vectorization.

UnitizationConfig (Optional)

Only use if you need custom chunking behavior. Configures how content is chunked and processed for different modalities:

{
  modality: string;          // Content type (e.g., "text", "code", "image")
  chunkingStrategy: string;  // How to split content (e.g., "sliding-window", "function-level", "ROI")
  resolution: number | string; // Chunk size or resolution
  [key: string]: any;        // Additional modality-specific options
}

Example configurations:

// Text processing
{
  modality: "text",
  chunkingStrategy: "sliding-window", 
  resolution: 512,
  overlap: 256
}

// Code processing  
{
  modality: "code",
  chunkingStrategy: "function-level",
  resolution: 0
}

// Image processing
{
  modality: "image", 
  chunkingStrategy: "ROI",
  resolution: "128x128"
}

VectorizationConfig (Optional)

Only use if you need custom embedding settings. Configures the embedding and vector storage settings:

{
  embeddingModel: string;           // Model to use for embeddings
  dimensionality: number;           // Vector dimension size
  distanceMetric: string;           // Distance calculation method
  indexType: string;                // Vector index type
  normalizationStrategy: string;    // Vector normalization approach
  [key: string]: any;               // Additional vectorization options
}

Example configuration:

{
  embeddingModel: "text-embedding-3-small",
  dimensionality: 1536,
  distanceMetric: "cosine", 
  indexType: "hnsw",
  normalizationStrategy: "l2"
}

Error Handling

The client throws Root2ApiError instances for API errors:

try {
  const result = await apiClient.importFile("mb_1a2b3c4d5e6f7g8h9i0j", { filePath: "document.pdf" });
} catch (error) {
  if (error instanceof Root2ApiError) {
    console.error("API Error:", error.message);
    console.error("Status:", error.status);
    console.error("Details:", error.details);
  }
}

License

MIT