API Reference

Quick links

New to HydraDB? Start with the Quickstart
Prefer SDKs? See the Python and TypeScript SDKs below
Authentication: Every endpoint requires Authorization: Bearer $HYDRA_DB_API_KEY
Base URL: https://api.hydradb.com
Errors: See Error Responses

Endpoint groups

Group	What it does	Pages
Tenants	Create, monitor, and manage isolated workspaces	6 endpoints
Ingestion	Upload knowledge sources (files, app content)	2 endpoints
Memories	Add and remove user-specific context	2 endpoints
Recall	Retrieve context with semantic or keyword search	3 endpoints
List	Browse stored content and inspect graph relationships	2 endpoints
Fetch	Retrieve original file content	1 endpoint
Knowledge Deletion	Remove knowledge sources	1 endpoint

End-to-end lifecycle

SDKs

HydraDB publishes official SDKs for Python and TypeScript/Node. They wrap every endpoint in this reference with typed methods and IDE autocomplete.

Language	Package	Install
Python	`hydradb-sdk` on PyPI	`pip install hydradb-sdk`
TypeScript / Node	`@hydradb/sdk` on npm	`npm install @hydradb/sdk`

Quick init:

import os
from hydra_db import HydraDB, AsyncHydraDB

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

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

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

SDK methods mirror the API: client.<group>.<method>() maps to the corresponding endpoint. Every per-endpoint page below includes Python and TypeScript tabs alongside the cURL example. See the full reference at SDKs.

Full endpoint inventory

Tenants

Endpoint	Method	Purpose
`/tenants/create`	`POST`	Create a new isolated workspace
`/tenants/infra/status`	`GET`	Check provisioning readiness
`/tenants/monitor`	`GET`	Get object counts
`/tenants/sub_tenant_ids`	`GET`	List active sub-tenants
`/tenants/tenant_ids`	`GET`	List all tenants for the organization
`/tenants/delete`	`DELETE`	Permanently delete a tenant

Ingestion

Endpoint	Method	Purpose
`/ingestion/upload_knowledge`	`POST`	Ingest files and/or app sources
`/ingestion/verify_processing`	`POST`	Check processing status

Memories

Endpoint	Method	Purpose
`/memories/add_memory`	`POST`	Ingest user memories
`/memories/delete_memory`	`DELETE`	Delete a single memory

Recall

Endpoint	Method	Purpose
`/recall/full_recall`	`POST`	Hybrid recall over knowledge
`/recall/recall_preferences`	`POST`	Hybrid recall over user memories
`/recall/boolean_recall`	`POST`	Exact-match full-text search

List

Endpoint	Method	Purpose
`/list/data`	`POST`	Paginated browse of knowledge or memories
`/list/graph_relations_by_id`	`GET`	Inspect entity relationships for a source

Fetch

Endpoint	Method	Purpose
`/fetch/content`	`POST`	Retrieve original file content or presigned URL

Knowledge Deletion

Endpoint	Method	Purpose
`/knowledge/delete_knowledge`	`POST`	Bulk delete sources by IDs

Conventions

Authentication. Every endpoint requires Authorization: Bearer $HYDRA_DB_API_KEY in the request header (substitute the actual key value). Get your key at app.hydradb.com. Tenant scoping. Every endpoint requires a tenant_id. Most endpoints also accept an optional sub_tenant_id for finer-grained scoping. If omitted, the default sub-tenant is used. Async operations. Tenant creation, deletion, and content ingestion are asynchronous. They return immediately after queuing. Use the relevant status endpoint to confirm completion before downstream operations. Pagination. Listing endpoints (/list/data) return a pagination object with page, page_size, total, total_pages, has_next, and has_previous. Parameter casing. The REST API uses snake_case (tenant_id). The TypeScript SDK accepts the same snake_case keys; method names are camelCase (fullRecall, addMemory). The Python SDK uses snake_case throughout. Status codes. Successful responses return 200 (or 202 for async accepts). Errors follow standard HTTP semantics:

Code	Meaning
`200`	Success
`202`	Accepted (async operation queued)
`400`	Invalid parameters
`401`	Authentication required
`403`	Forbidden
`404`	Resource not found
`409`	Conflict (e.g., tenant already exists)
`422`	Validation error
`429`	Rate limit exceeded
`500`	Internal server error
`503`	Service unavailable

See Error Responses for response shapes and error codes.

Rate limits

Rate limits apply per API key. For production deployments, build retry logic with exponential backoff against the 429 response. Contact [email protected] for current limit values.

Next steps

Build something: Quickstart walks through your first integration in five minutes
Understand the model: Core Concepts explains tenants, memories, recall, and metadata
Go deeper: Essentials covers each primitive in depth
Install an SDK: Python · TypeScript

API Documentation

Tenants

Knowledge & Memories

Recall

Managing Data

Quick links

Endpoint groups

End-to-end lifecycle

SDKs

Full endpoint inventory

Tenants

Ingestion

Memories

Recall

List

Fetch

Knowledge Deletion

Conventions

Rate limits

Next steps

​Quick links

​Endpoint groups

​End-to-end lifecycle

​SDKs

​Full endpoint inventory

​Tenants

​Ingestion

​Memories

​Recall

​List

​Fetch

​Knowledge Deletion

​Conventions

​Rate limits

​Next steps

Quick links

Endpoint groups

End-to-end lifecycle

SDKs

Full endpoint inventory

Tenants

Ingestion

Memories

Recall

List

Fetch

Knowledge Deletion

Conventions

Rate limits

Next steps