API Reference - HydraDB SDK

Use this reference to look up request fields and response formats. Every request carries Authorization: Bearer <your_api_key> and API-Version: 2 against https://api.hydradb.com; the SDKs set both for you. If you are making your first call, follow the Quickstart. AI agents can start from the Agent Integration Guide and the v2 OpenAPI spec. Context means the documents, passages, and memories your model uses to answer a question; HydraDB stores and retrieves them, while your model writes the answer.

The four calls

Most integrations are these four requests, in this order. Everything else in this reference manages what they create.

Create Database: POST /databases. One isolated workspace per customer, environment, or product. Creation runs in the background, so poll Database Status until ready_for_ingestion is true.
Ingest Context: POST /context/ingest. Files, app sources, or memories, in one multipart request.
Ingestion Status: GET /context/status. Poll the returned ids until indexing_status is completed, or register a webhook instead.
Query: POST /query. Retrieve the context your model needs, from knowledge, memories, or both.

Endpoint groups

Group	Purpose	When to reach for it
Databases	Create, monitor, and manage isolated workspaces	First step in any integration, and any time you need usage stats, provisioning status, or to tear down a workspace
Context	Ingest, list, fetch, delete, and inspect knowledge or memories	Every time data flows into HydraDB: document uploads, app sources, user memories, and lifecycle ops
Query	Retrieve context with hybrid or text query, and send feedback on the results	Find relevant passages to include in your model prompt
Connectors	Connect, configure, sync, and manage app connectors such as Slack, GitHub, Google Drive, and Supabase	When you want app data synced into a database without writing ingest code
Webhooks	Register a URL that receives a `POST` when indexing finishes, and inspect or retry deliveries	When you would rather be notified than poll `/context/status`

Core concepts

Concept	What it means	When you use it
`database`	Your isolated workspace for data, metadata schema, and query.	Send it on database-scoped calls such as ingestion and query. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).
`collection`	Optional partition inside a database, often a user, team, account, or customer.	Send the same collection on writes and reads. Omitting it uses the default collection, not all collections. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated). Read more about our multi-tenant architecture
Knowledge	Source material such as PDFs, docs, app pages, tickets, Slack threads, or webpages.	Use `type=knowledge` to search documents and app content.
Memory	Preferences, conversation history, notes, and saved facts.	Use `type=memory` when the content should personalize answers for a specific user or collection.
`database_metadata_schema`	Database-level fields you define up front so metadata can be filtered or queried consistently.	Use it for stable fields like department, customer, region, plan, category, or compliance label.
`document_metadata`	JSON-stringified per-document metadata array sent during file ingestion.	Use it to attach a source `id`, schema-backed `metadata`, free-form `additional_metadata`, and relations to other sources to each uploaded file, in the same order as `documents`.
`ids`	IDs returned by ingestion or visible from `/context/list`.	Use them when polling processing status, inspecting content, listing a specific subset, deleting sources, or inspecting relations.

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. The SDKs are generated from the OpenAPI contract and set API-Version: 2 automatically. The SDK method names below are the Python names; TypeScript camelCases multi-word names (for example, delete_collection is deleteCollection).

Full endpoint inventory

Endpoint	Method	SDK method	Purpose	Use when
`/databases`	`POST`	`databases.create`	Create a database	You are setting up a new isolated workspace and optional metadata schema.
`/databases/{database}/metadata-schema`	`PATCH`	`databases.update_metadata_schema`	Add metadata schema fields	You need to add filterable metadata fields after database creation.
`/databases`	`GET`	`databases.list`	List databases	You need to discover database IDs available to the current API key.
`/databases`	`DELETE`	`databases.delete`	Delete a database	You need to permanently remove a workspace and its data.
`/databases/status`	`GET`	`databases.status`	Check provisioning readiness	You just created a database and need to wait before ingesting data.
`/databases/collections`	`GET`	`databases.collections`	List active collections	You partition data by user, team, customer, or account and need to inspect those partitions.
`/databases/collections`	`DELETE`	`databases.delete_collection`	Delete a collection	You need to permanently remove one collection and its data without deleting the database.
`/databases/stats`	`GET`	`databases.stats`	Get usage statistics	You want to monitor object counts for a database.
`/context/ingest`	`POST`	`context.ingest`	Ingest knowledge or memories	You are uploading documents, app sources, or user memories.
`/context/status`	`GET`	`context.status`	Check processing status	You have IDs from ingestion and need to know when they are queryable.
`/context/inspect`	`GET`	`context.inspect`	Inspect original source content or presigned URL	You need to display or inspect the original ingested content.
`/context/list`	`POST`	`context.list`	Browse knowledge or memories	You need pagination, filters, field projection, or a specific subset by `ids`.
`/context/{id}/metadata`	`PATCH`	`context.update_source_metadata`	Update source metadata	You need to merge `metadata` or `additional_metadata` onto one existing source without re-ingesting.
`/context`	`DELETE`	`context.delete`	Delete sources or memories	You need to remove one or more knowledge sources or memories by ID.
`/context/relations`	`GET`	`context.relations`	Inspect entity relationships	You need graph relations for a source or collection.
`/context/{id}/subgraph`	`GET`	`context.subgraph`	Get the connected subgraph	You need the connected subgraph around one source.
`/query`	`POST`	`query`	Unified query over knowledge, memories, or both	You need retrieval with `hybrid` or `text` query across `type: "knowledge"`, `type: "memory"`, or `type: "all"`.
`/feedback`	`POST`	`feedback.submit`	Submit query feedback	You want to tell HydraDB whether a query returned what you needed.
`/connectors/providers`	`GET`	`list_providers`	List connector providers	You need the providers you can connect, or the credentials one provider needs.
`/connectors`	`POST`	`connectors.create`	Create a connector	You are storing credentials for one provider account.
`/connectors/{id}/discover`	`GET`	`connectors.discover`	Discover resources	You need the resources the connector’s credentials can reach.
`/connectors/{id}/configure`	`POST`	`connectors.configure`	Configure a connector	You are activating resources and starting the first sync.
`/connectors/{id}/status`	`GET`	`connectors.status`	Get connector status	You need to know whether the connector and each resource are working.
`/connectors`	`GET`	`connectors.list`	List connectors	You need your connectors and their sync state.
`/connectors/{id}`	`GET`	`connectors.get`	Get a connector	You need one connector’s settings.
`/connectors/{id}/resources`	`GET`	`connectors.list_resources`	List connector resources	You need each resource’s settings.
`/connectors/{id}/sync`	`POST`	`connectors.sync`	Sync a connector	You want to sync now instead of waiting for the schedule.
`/connectors/{id}/pause`	`POST`	`connectors.pause`	Pause a connector	You want to turn scheduled syncs off.
`/connectors/{id}/resume`	`POST`	`connectors.resume`	Resume a connector	You want to turn scheduled syncs back on.
`/connectors/{id}`	`PATCH`	`connectors.update`	Update a connector	You need to change the sync interval, connector-level instructions, or credentials.
`/connectors/{id}/resources/{resource_id}`	`PATCH`	`connectors.update_resource_acl`	Update a connector resource	You need to change one resource’s instructions or access rule.
`/connectors/{id}/resources`	`POST`	`connectors.create_resource`	Add a connector resource	You want to add one new resource to an existing connector.
`/connectors/{id}/resources/{resource_id}`	`DELETE`	`connectors.delete_resource`	Delete a connector resource	You want to stop syncing one resource.
`/connectors/{id}`	`DELETE`	`connectors.delete`	Delete a connector	You need to remove a connector.
`/webhooks/indexing`	`POST`	`webhooks.register`	Register a webhook	You want a `POST` to your URL when indexing finishes, instead of polling.
`/webhooks/indexing`	`GET`	`webhooks.get`	Get the webhook	You need the current webhook configuration.
`/webhooks/indexing`	`DELETE`	`webhooks.delete`	Delete the webhook	You want to stop receiving indexing notifications.
`/webhooks/indexing/test`	`POST`	`webhooks.test`	Send a test delivery	You want to check that your endpoint receives and verifies deliveries.
`/webhooks/indexing/deliveries`	`GET`	`webhooks.list_deliveries`	List deliveries	You need recent delivery attempts and their status.
`/webhooks/indexing/deliveries/{delivery_id}`	`GET`	`webhooks.get_delivery`	Get a delivery	You need the details of one delivery.
`/webhooks/indexing/deliveries/{delivery_id}/retry`	`POST`	`webhooks.retry_delivery`	Retry a delivery	You want to resend a `failed` or `permanently_failed` delivery.

Conventions

Authentication: Every endpoint requires Authorization: Bearer <your_api_key> in the request header. Get your key at app.hydradb.com. Versioning: Send API-Version: 2 with every request.

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "my_first_database",
    "query": "What are the pricing tiers?",
    "type": "knowledge",
    "query_by": "hybrid"
  }'

Response envelope: Core v2 endpoints (/databases, /context/*, /query, /feedback, and /webhooks/indexing*) return a consistent envelope. Endpoint pages show the full envelope; the resource-specific payload lives under data. Connector endpoints (/connectors*) and PATCH /databases/{database}/metadata-schema are the exception: they return their success body without the envelope.

{
  "success": true,
  "data": {},
  "error": null,
  "meta": {
    "request_id": "request-id",
    "latency_ms": 12.3
  }
}

Errors use the same envelope on every endpoint, including the exceptions above, with success: false, data: null, and an error object containing code and message. meta may also include a deprecation list when a request uses a legacy /tenants route or a deprecated field (tenant_id/sub_tenant_id, or sub_tenant_ids on /query); each entry carries deprecated, a message, and deprecated_since (field-level notices also add deprecated_field and preferred_field). It is a non-breaking migration nudge (the status code is unchanged) and is accompanied by a Deprecation: true response header. See Migrating from tenant_id and sub_tenant_id.

Database scoping: Most database-scoped endpoints require a database (formerly tenant_id). Many source and query endpoints also accept an optional collection (formerly sub_tenant_id) for finer-grained scoping. If omitted, the default collection is used. The old tenant_id/sub_tenant_id names (and the old /tenants routes) remain accepted as deprecated aliases; sending a canonical name and its alias with different values returns 400. See Migrating from tenant_id and sub_tenant_id.
Async operations: Database creation, database and collection 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 (/context/list) return pagination fields for browsing large result sets.
Parameter casing: The REST API uses snake_case (database, max_results). The TypeScript SDK uses camelCase keys and method names (maxResults, deleteCollection) and ignores request keys it does not recognize, including snake_case ones. The Python SDK uses snake_case throughout. See SDKs.
Query modes: POST /query supports query_by: "hybrid" or "text" and type: "knowledge", "memory", or "all". The same type enum is used across ingestion, listing, deletion, and query; query additionally accepts "all".

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
`402`	Your plan does not allow the request
`403`	Forbidden
`404`	Resource not found
`409`	Conflict (e.g., database already exists)
`413`	Request body too large
`415`	Unsupported content type
`422`	Validation error, or a query sent before the database is ready
`429`	Rate limit exceeded
`500`	Internal server error
`503`	Service unavailable

See Error Responses for response shapes, error codes, and retry patterns.

Rate limits

Rate limits apply per API key. For production deployments, build retry logic with exponential backoff against the 429 response. Contact founders@hydradb.com for current limit values.

Next steps

Existing v1 endpoints remain available under the v1 API Reference.

Build something: Quickstart walks through your first integration in five minutes
Understand the model: Core Concepts explains databases, collections, content categories, and query results
Go deeper: Usage covers each primitive in depth
Install an SDK: Python · TypeScript

​The four calls

​Endpoint groups

​Core concepts

​SDKs

​Full endpoint inventory

​Conventions

​Rate limits

​Next steps