> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-docs-pro-2457-api-response-cleanup.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> The four calls most integrations are built on, then every v2 endpoint.

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](/api-reference/v2/sdks) set both for you. If you are making your first call, follow the [Quickstart](/get-started/v2/quickstart). AI agents can start from the [Agent Integration Guide](/AGENTS) and the [v2 OpenAPI spec](/api-reference/v2/openapi.json). **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.

1. [Create Database](/api-reference/v2/endpoint/create-tenant): `POST /databases`. One isolated workspace per customer, environment, or product. Creation runs in the background, so poll [Database Status](/api-reference/v2/endpoint/tenant-status) until `ready_for_ingestion` is `true`.
2. [Ingest Context](/api-reference/v2/endpoint/ingest-context): `POST /context/ingest`. Files, app sources, or memories, in one multipart request.
3. [Ingestion Status](/api-reference/v2/endpoint/source-status): `GET /context/status`. Poll the returned ids until `indexing_status` is `completed`, or [register a webhook](/essentials/v2/webhooks) instead.
4. [Query](/api-reference/v2/endpoint/query): `POST /query`. Retrieve the context your model needs, from knowledge, memories, or both.

```mermaid theme={"dark"}
flowchart LR

    subgraph Database Lifecycle [" "]
      direction LR
      A([Create Database])-->B([Wait for Provisioning])
      B-->C([Ingest Knowledge / Memories])
      C-->D([Verify Processing])
      D-->E([Query Context])
      E-->F([Pass to LLM])
      E-->G([List / Fetch / Inspect])
    end

    style A fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style B fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style C fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style D fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style E fill:#FF571A,stroke:#334155,stroke-width:2px,color:#f8fafc
    style F fill:#0f172a,stroke:#334155,stroke-width:2px,color:#f8fafc
    style G fill:#0f172a,stroke:#334155,stroke-width:2px,color:#f8fafc
```

## Endpoint groups

| Group | Purpose | When to reach for it |
| - | - | - |
| [Databases](/api-reference/v2/endpoint/tenants-overview) | 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](/api-reference/v2/endpoint/sources-overview) | 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](/api-reference/v2/endpoint/query-overview) | Retrieve context with hybrid or text query, and send feedback on the results | Find relevant passages to include in your model prompt |
| [Connectors](/api-reference/v2/endpoint/connectors-overview) | 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](/essentials/v2/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](/essentials/v2/multi-tenant) |
| [Knowledge](/essentials/v2/knowledge) | Source material such as PDFs, docs, app pages, tickets, Slack threads, or webpages. | Use `type=knowledge` to search documents and app content. |
| [Memory](/essentials/v2/memories) | 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](https://pypi.org/project/hydradb-sdk/) | `pip install hydradb-sdk` |
| **TypeScript / Node** | [`@hydradb/sdk` on npm](https://www.npmjs.com/package/@hydradb/sdk) | `npm install @hydradb/sdk` |

**Quick init:**

<CodeGroup>
  ```python Python theme={"dark"}
  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"])
  ```

  ```typescript TypeScript theme={"dark"}
  import { HydraDBClient } from "@hydradb/sdk";

  const client = new HydraDBClient({
    token: process.env.HYDRA_DB_API_KEY,
  });
  ```
</CodeGroup>

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

**Versioning:** Send `API-Version: 2` with every request.

```bash theme={"dark"}
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.

```json theme={"dark"}
{
  "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`](/essentials/v2/multi-tenant#7-migrating-from-the-legacy-tenant-and-sub-tenant-fields).

* **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`](/essentials/v2/multi-tenant#7-migrating-from-the-legacy-tenant-and-sub-tenant-fields).

* **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](/api-reference/v2/sdks#naming-conventions).

* **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](/api-reference/v2/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](mailto:founders@hydradb.com) for current limit values.

## Next steps

Existing v1 endpoints remain available under the v1 API Reference.

* **Build something:** [Quickstart](/get-started/v2/quickstart) walks through your first integration in five minutes
* **Understand the model:** [Core Concepts](/get-started/v2/core-concepts) explains databases, collections, content categories, and query results
* **Go deeper:** [Usage](/essentials/v2/query) covers each primitive in depth
* **Install an SDK:** [Python](https://pypi.org/project/hydradb-sdk/) · [TypeScript](https://www.npmjs.com/package/@hydradb/sdk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.