SDKs – Node and Python

Installation

npm install @hydradb/sdk

pip install hydradb-sdk

Client setup

import { HydraDBClient } from "@hydradb/sdk";

const client = new HydraDBClient({
  token: process.env.HYDRA_DB_API_KEY,
});

import os
from hydra_db import HydraDB

client = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])

import os
from hydra_db import AsyncHydraDB

async_client = AsyncHydraDB(token=os.environ["HYDRA_DB_API_KEY"])

Python: Both synchronous (HydraDB) and asynchronous (AsyncHydraDB) clients are available. They share an identical surface – choose based on your application’s concurrency model.

Naming conventions

The REST API uses snake_case for all request and response fields. The SDKs adapt this to native idioms:

	Method naming	Parameter field naming	Example
Raw HTTP / cURL	-	snake_case	`tenant_id`, `sub_tenant_id`
TypeScript SDK	camelCase	snake_case	method: `fullRecall()`, params: `tenant_id`, `sub_tenant_id`
Python SDK	snake_case	snake_case	method: `full_recall()`, params: `tenant_id`, `sub_tenant_id`

TypeScript SDK uses snake_case for all parameter field names. Only method names are camelCase (e.g., client.recall.fullRecall({tenant_id: "...", max_results: 5})). This applies to every request object passed to an SDK method.

The TypeScript SDK transparently maps camelCase parameters to snake_case on the wire. You can rely on your IDE’s autocomplete and type checking – if a field is optional in the API, it’s optional in the SDK.

SDK method structure

SDK methods are grouped by capability, not by URL path. The mapping is mostly intuitive but a few groups span multiple URL prefixes:

URL prefix	SDK group	Why
`/tenants/*`	`client.tenant`	Tenant lifecycle
`/ingestion/*`	`client.upload`	Content upload + verification
`/memories/*`	`client.upload`	Memories share the upload group (add, delete)
`/recall/*`	`client.recall`	All retrieval modes
`/list/`, `/fetch/`	`client.fetch`	Browse and retrieve
`/knowledge/*`	`client.data`	Bulk knowledge delete

Additional clients available: client.key for API key management, client.ingestionPipeline for pipeline operations, client.graphHealth for health checks, and client.metrics for metrics, client.passthrough for passthrough operations.

Method reference

Method names map to the URL by removing the leading slash and replacing path separators:

Tenants

Method	Endpoint
`client.tenant.create()`	`POST /tenants/create`
`client.tenant.getInfraStatus()`	`GET /tenants/infra/status`
`client.tenant.monitor()`	`GET /tenants/monitor`
`client.tenant.getSubTenantIds()`	`GET /tenants/sub_tenant_ids`
`client.tenant.getTenantIds()`	`GET /tenants/tenant_ids`
`client.tenant.deleteTenant()`	`DELETE /tenants/delete`

Ingestion + Memories (under `upload`)

Method	Endpoint
`client.upload.knowledge()`	`POST /ingestion/upload_knowledge`
`client.upload.verifyProcessing()`	`POST /ingestion/verify_processing`
`client.upload.addMemory()`	`POST /memories/add_memory`
`client.upload.deleteMemory()`	`DELETE /memories/delete_memory`

Recall

Method	Endpoint
`client.recall.fullRecall()`	`POST /recall/full_recall`
`client.recall.recallPreferences()`	`POST /recall/recall_preferences`
`client.recall.booleanRecall()`	`POST /recall/boolean_recall`

List + Fetch (under `fetch`)

Method	Endpoint
`client.fetch.listData()`	`POST /list/data`
`client.fetch.graphRelationsBySourceId()`	`GET /list/graph_relations_by_id`
`client.fetch.content()`	`POST /fetch/content`

Knowledge Deletion

Method	Endpoint
`client.data.delete()`	`POST /knowledge/delete_knowledge`
In TypeScript, snake_case method names use camelCase: `client.tenant.getInfraStatus()`, `client.recall.fullRecall()`, etc.

In Python, all method names use snake_case: client.tenant.get_infra_status(), client.recall.full_recall(), etc.

Additional clients

Method	Endpoint
`client.graphHealth.getSuperNodes()`	`GET /graph/super_nodes`
`client.ingestionPipeline.ingestMemory()`	`POST /memories/ingestion_pipeline`
`client.metrics.getMetrics()`	`GET /metrics`
`client.passthrough.fetch()`	`POST /passthrough/fetch`

Getting started

Create a tenant

A tenant is an isolated workspace. Most organizations create one tenant total, with sub-tenants for users or teams. See Multi-Tenant for the full model.

const response = await client.tenant.create({
  tenant_id: "my_first_tenant"
});

response = client.tenant.create(
    tenant_id="my_first_tenant",
    tenant_metadata_schema={"department": "string"},
)

response = await async_client.tenant.create(tenant_id="my_first_tenant")

Tenant creation is asynchronous. Poll getInfraStatus until provisioning completes:

while (true) {
  const status = await client.tenant.getInfraStatus({
    tenant_id: "my_first_tenant"
  });
  const { graph_status, vectorstore_status } = status.infra;
  if (graph_status && vectorstore_status.every(Boolean)) break;
  await new Promise(r => setTimeout(r, 2000));
}

import time

while True:
    status = client.tenant.get_infra_status(tenant_id="my_first_tenant")
    if (status.infra.graph_status
        and all(status.infra.vectorstore_status)):
        break
    time.sleep(2)

Ingest knowledge

Upload documents, app sources, or both via upload.knowledge:

import { openAsBlob } from "node:fs";

const result = await client.upload.knowledge({
  tenant_id: "my_first_tenant",
  files: [
    { path: "contract.pdf", filename: "contract.pdf", contentType: "application/pdf" },
    { path: "policy.pdf", filename: "policy.pdf", contentType: "application/pdf" },
  ],
  file_metadata: JSON.stringify([
    {
      file_id: "contract_q4",
      metadata: { category: "legal" },
      additional_metadata: { author: "Alice" }
    },
    {
      file_id: "policy_2025",
      metadata: { category: "legal" },
      additional_metadata: { author: "Bob" }
    }
  ])
});

import json

with open("contract.pdf", "rb") as f1, open("policy.pdf", "rb") as f2:
    result = client.upload.knowledge(
        tenant_id="my_first_tenant",
        files=[
            ("contract.pdf", f1, "application/pdf"),
            ("policy.pdf", f2, "application/pdf"),
        ],
        file_metadata=json.dumps([
            {
                "file_id": "contract_q4",
                "metadata": {"category": "legal"},
                "additional_metadata": {"author": "Alice"},
            },
            {
                "file_id": "policy_2025",
                "metadata": {"category": "legal"},
                "additional_metadata": {"author": "Bob"},
            },
        ]),
    )

For full options including app sources and forceful relations, see Upload knowledge.

Add user memories

Store user preferences and conversation history via upload.addMemory:

// Plain text memory
const result = await client.upload.addMemory({
  tenant_id: "my_first_tenant",
  memories: [
    {
      text: "User prefers detailed technical explanations and dark mode",
      infer: true,
      user_name: "Alex",
      metadata: { team: "engineering" },
      additional_metadata: { source: "onboarding" }
    }
  ]
});

// Conversation pairs
const conversation = await client.upload.addMemory({
  tenant_id: "my_first_tenant",
  memories: [
    {
      user_assistant_pairs: [
        { user: "What are my preferences?", assistant: "You prefer dark mode." },
        { user: "How do I like reports?", assistant: "Weekly summaries." }
      ],
      infer: true,
      user_name: "Alex"
    }
  ]
});

# Plain text memory
result = client.upload.add_memory(
    tenant_id="my_first_tenant",
    memories=[
        {
            "text": "User prefers detailed technical explanations and dark mode",
            "infer": True,
            "user_name": "Alex",
            "metadata": {"team": "engineering"},
            "additional_metadata": {"source": "onboarding"},
        }
    ],
)

# Conversation pairs
conversation = client.upload.add_memory(
    tenant_id="my_first_tenant",
    memories=[
        {
            "user_assistant_pairs": [
                {"user": "What are my preferences?", "assistant": "You prefer dark mode."},
                {"user": "How do I like reports?", "assistant": "Weekly summaries."},
            ],
            "infer": True,
            "user_name": "Alex",
        }
    ],
)

infer defaults to false. Set infer: true for conversational content where you want HydraDB to extract implicit preferences. Use infer: false for content that should be stored verbatim.

Recall

Three retrieval modes for different use cases:

// Hybrid recall over knowledge
const knowledge = await client.recall.fullRecall({
  tenant_id: "my_first_tenant",
  query: "What are the pricing tiers?",
  mode: "thinking",
  graph_context: true
});

// Hybrid recall over user memories
const prefs = await client.recall.recallPreferences({
  tenant_id: "my_first_tenant",
  sub_tenant_id: "user_alex",
  query: "What are this user's display preferences?",
  mode: "thinking"
});

// Exact-match search
const exact = await client.recall.booleanRecall({
  tenant_id: "my_first_tenant",
  query: "ERROR_429 rate limit",
  operator: "and"
});

# Hybrid recall over knowledge
knowledge = client.recall.full_recall(
    tenant_id="my_first_tenant",
    query="What are the pricing tiers?",
    mode="thinking",
    graph_context=True,
)

# Hybrid recall over user memories
prefs = client.recall.recall_preferences(
    tenant_id="my_first_tenant",
    sub_tenant_id="user_alex",
    query="What are this user's display preferences?",
    mode="thinking",
)

# Exact-match search
exact = client.recall.boolean_recall(
    tenant_id="my_first_tenant",
    query="ERROR_429 rate limit",
    operator="and",
)

For full parameter documentation, see Recall.

Browse and inspect

// List knowledge sources with pagination
const sources = await client.fetch.listData({
  tenant_id: "my_first_tenant",
  kind: "knowledge",
  page: 1,
  page_size: 50
});

// Inspect graph relationships for a specific source
const relations = await client.fetch.graphRelationsBySourceId({
  tenant_id: "my_first_tenant",
  source_id: "doc_12345"
});

// Fetch original file content or get a presigned URL
const file = await client.fetch.content({
  tenant_id: "my_first_tenant",
  source_id: "doc_12345",
  mode: "url"
});

# List knowledge sources with pagination
sources = client.fetch.list_data(
    tenant_id="my_first_tenant",
    kind="knowledge",
    page=1,
    page_size=50,
)

# Inspect graph relationships for a specific source
relations = client.fetch.graph_relations_by_source_id(
    tenant_id="my_first_tenant",
    source_id="doc_12345",
)

# Fetch original file content or get a presigned URL
file = client.fetch.content(
    tenant_id="my_first_tenant",
    source_id="doc_12345",
    mode="url",
)

Type safety

Both SDKs are fully typed:

Autocomplete for all method names and parameters
Type checking for request and response objects
Inline documentation for each parameter
Compile-time validation for required vs optional fields

The SDKs provide exact type parity with the API specification:

Request parameters – every field documented in the API reference is reflected in method signatures
Response objects – return types match the JSON schema for each endpoint
Error types – exception structures mirror error response formats
Nested objects – complex parameters and responses keep their full structure

Error handling

Both SDKs throw exceptions for non-2xx responses. Error objects expose the API’s detail payload:

import { HydraDBError } from "@hydradb/sdk";

try {
  const result = await client.recall.fullRecall({
    tenant_id: "my_first_tenant",
    query: "..."
  });
} catch (error) {
  if (error instanceof HydraDBError) {
    const code = error.body?.detail?.error_code;

    if (code === "TENANT_NOT_FOUND") {
      // Handle missing tenant
    } else if (error.statusCode === 429) {
      // Rate limit - retry with backoff
    } else {
      throw error;
    }
  } else {
    throw error;
  }
}

from hydra_db import HydraDBError

try:
    result = client.recall.full_recall(
        tenant_id="my_first_tenant",
        query="...",
    )
except HydraDBError as e:
    code = e.error_code
    status = e.status_code

    if code == "TENANT_NOT_FOUND":
        # Handle missing tenant
        pass
    elif status == 429:
        # Rate limit - retry with backoff
        pass
    else:
        raise

For the full list of error codes and retry patterns, see Error Responses.

IDE-driven discovery

Whether you’re using TypeScript, Python, VS Code, PyCharm, or any modern IDE, the workflow is the same:

Type the method name → see all available methods
Open the parentheses → see all required and optional parameters
Press Cmd+Space (macOS) or Ctrl+Space (Windows/Linux) → get inline documentation

This works because the SDKs are fully typed with comprehensive parameter docs.

API Reference – complete endpoint documentation
Error Responses – HTTP codes, error codes, retry patterns
Quickstart – build your first integration in five minutes

API Documentation

Tenants

Knowledge & Memories

Recall

Managing Data

SDKs – Node and Python

Installation

Client setup

Naming conventions

SDK method structure

Method reference

Tenants

Ingestion + Memories (under `upload`)

Recall

List + Fetch (under `fetch`)

Knowledge Deletion

Additional clients

Getting started

Create a tenant

Ingest knowledge

Add user memories

Recall

Browse and inspect

Type safety

Error handling

IDE-driven discovery

​Installation

​Client setup

​Naming conventions

​SDK method structure

​Method reference

​Tenants

​Ingestion + Memories (under upload)

​Recall

​List + Fetch (under fetch)

​Knowledge Deletion

​Additional clients

​Getting started

​Create a tenant

​Ingest knowledge

​Add user memories

​Recall

​Browse and inspect

​Type safety

​Error handling

​IDE-driven discovery

​Related sections

Installation

Client setup

Naming conventions

SDK method structure

Method reference

Tenants

Ingestion + Memories (under `upload`)

Recall

List + Fetch (under `fetch`)

Knowledge Deletion

Additional clients

Getting started

Create a tenant

Ingest knowledge

Add user memories

Recall

Browse and inspect

Type safety

Error handling

IDE-driven discovery

Related sections