Knowledge

Knowledge is what your AI reasons over: product docs, policy PDFs, runbooks, wiki pages, Slack threads, tickets, and emails. There are three ways to add it:

Files: upload PDF, DOCX, Markdown, CSV, or TXT files, and HydraDB reads them for you.
App sources: send records your application already parsed from an app, such as a Slack message or a Jira ticket.
Connectors: connect an app such as Slack, Google Drive, Notion, or GitHub once, and HydraDB keeps it in sync. There are 70 to choose from.

Files and app sources go to POST /context/ingest with type=knowledge. Each file or record is a source. HydraDB splits it into searchable passages called chunks, builds a context graph from it, and returns the relevant chunks through POST /query. Preferences, decisions, and past conversations are memories, not knowledge. For a company brain, ingest everything into one collection and use metadata filters to narrow results. In this guide:

Upload files: PDFs, Word documents, Markdown, CSV, and text.
Ingest app sources: records from Slack, Jira, Notion, Gmail, and other apps.
Wait for indexing: polling until a source is searchable.
Retrieve knowledge: querying what you ingested.
Add metadata for filtering.
Link documents that belong together.
Field reference and common mistakes.

1. Upload files

This request uploads two PDFs. HydraDB accepts PDF, DOCX, Markdown, CSV, and TXT files. The request is multipart/form-data with these fields:

Form field	What to send
`type`	`knowledge`
`database`	An existing database
`collection`	Optional. Leave it out to use the database’s default collection. A query that names another collection does not read the default one.
`documents`	One or more files
`document_metadata`	One item per file, in the same order, as a JSON string. Optional, but this is where a file’s `id` and `metadata` go.
`upsert`	Leave it out. It defaults to `true`, so a file sent again with the same `id` replaces the saved one.

Upload files: Python, TypeScript, or cURL

Set up your SDK client before running the Python or TypeScript example.

import json

with open("/path/to/policy.pdf", "rb") as f1, open("/path/to/runbook.pdf", "rb") as f2:
    result = client.context.ingest(
        type="knowledge",
        database="acme_corp",
        documents=[
            ("policy.pdf", f1, "application/pdf"),
            ("runbook.pdf", f2, "application/pdf"),
        ],
        document_metadata=json.dumps([
            {"id": "policy_v2", "metadata": {"document_type": "policy", "status": "approved"}},
            {"id": "runbook_deploy", "metadata": {"document_type": "runbook"}},
        ]),
    )

const result = await client.context.ingest({
  type: "knowledge",
  database: "acme_corp",
  documents: [
    { path: "/path/to/policy.pdf", filename: "policy.pdf", contentType: "application/pdf" },
    { path: "/path/to/runbook.pdf", filename: "runbook.pdf", contentType: "application/pdf" },
  ],
  documentMetadata: JSON.stringify([
    { id: "policy_v2", metadata: { document_type: "policy", status: "approved" } },
    { id: "runbook_deploy", metadata: { document_type: "runbook" } },
  ]),
});

curl -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=knowledge" \
  -F "database=acme_corp" \
  -F "documents=@/path/to/policy.pdf" \
  -F "documents=@/path/to/runbook.pdf" \
  -F 'document_metadata=[
    { "id": "policy_v2", "metadata": { "document_type": "policy", "status": "approved" } },
    { "id": "runbook_deploy", "metadata": { "document_type": "runbook" } }
  ]'

The response lists each file in data.results with its id and a status of queued. The payload is wrapped in the standard envelope, so read it from response.data:

{
  "success": true,
  "data": {
    "success": true,
    "message": "Knowledge uploaded successfully",
    "results": [
      { "id": "policy_v2", "filename": "policy.pdf", "status": "queued", "error": null },
      { "id": "runbook_deploy", "filename": "runbook.pdf", "status": "queued", "error": null }
    ],
    "success_count": 2,
    "failed_count": 0
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

What each property in `document_metadata` means

Property	What it is
`id`	Your stable ID for the file. Send the same `id` later to replace the file, or use it to check status and delete. Leave it out to have one generated; the response returns it either way.
`metadata`	Values you filter on at query time, such as `document_type`. Declare the keys in the database metadata schema. Up to 16 KiB as compact JSON.
`additional_metadata`	Free-form values for display and bookkeeping. Up to 1 KiB as compact JSON.
`relations`	Other sources this file belongs with, as `{ "ids": [...] }`. Section 6 explains it.

The key list is closed. Any other key, including title, type, url, and timestamp, returns 400.

2. Ingest app sources

When your application already holds the text and fields of a Slack message, a Jira ticket, a Notion page, or a CRM record, send it as an app source instead of a file. HydraDB keeps the app’s structure: the author, the thread, the ticket’s status, and the links between items. See App Sources for every class and a ready-to-use pattern for each app. The request goes to the same endpoint, with app_knowledge in place of documents. One request can carry both. An app source can also carry an acl, the list of people allowed to retrieve it; see Access Control.

Ingest a Slack message: Python, TypeScript, or cURL

import json

result = client.context.ingest(
    type="knowledge",
    database="acme_corp",
    app_knowledge=json.dumps([
        {
            "id": "slack_C01_1716213600_000100",
            "title": "Pricing discussion - Slack #product",
            "kind": "message",
            "provider": "slack",
            "external_id": "1716213600.000100",
            "fields": {
                "kind": "message",
                "body": "We agreed on three tiers: Starter at $29, Pro at $79, Enterprise at $199.",
                "author": "alice",
                "thread_id": "1716213600.000100",
                "created_at": "2026-05-20T10:00:00Z",
            },
            "metadata": {"channel": "product", "status": "finalized"},
            "additional_metadata": {"slack_ts": "1716213600.000100"},
        }
    ]),
)

const result = await client.context.ingest({
  type: "knowledge",
  database: "acme_corp",
  appKnowledge: JSON.stringify([
    {
      id: "slack_C01_1716213600_000100",
      title: "Pricing discussion - Slack #product",
      kind: "message",
      provider: "slack",
      external_id: "1716213600.000100",
      fields: {
        kind: "message",
        body: "We agreed on three tiers: Starter at $29, Pro at $79, Enterprise at $199.",
        author: "alice",
        thread_id: "1716213600.000100",
        created_at: "2026-05-20T10:00:00Z",
      },
      metadata: { channel: "product", status: "finalized" },
      additional_metadata: { slack_ts: "1716213600.000100" },
    },
  ]),
});

curl -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=knowledge" \
  -F "database=acme_corp" \
  -F 'app_knowledge=[
    {
      "id": "slack_C01_1716213600_000100",
      "title": "Pricing discussion - Slack #product",
      "kind": "message",
      "provider": "slack",
      "external_id": "1716213600.000100",
      "fields": {
        "kind": "message",
        "body": "We agreed on three tiers: Starter at $29, Pro at $79, Enterprise at $199.",
        "author": "alice",
        "thread_id": "1716213600.000100",
        "created_at": "2026-05-20T10:00:00Z"
      },
      "metadata": { "channel": "product", "status": "finalized" },
      "additional_metadata": { "slack_ts": "1716213600.000100" }
    }
  ]'

The response has the same shape as a file upload, with one entry per app source in data.results.

3. Wait for indexing

Ingestion runs in the background: HydraDB parses each source, splits it into chunks, finds the people, teams, and topics it mentions and how they relate (see Context Graphs), and builds the search indexes. The response returns 202 Accepted with each source’s id. Poll GET /context/status with those ids and the same collection until every source reaches completed or errored.

Poll until indexed: Python, TypeScript, or cURL

import time

ids = ["policy_v2", "runbook_deploy"]
terminal = {"completed", "errored"}

while True:
    status = client.context.status(
        database="acme_corp",
        collection="default",
        ids=ids,
    )
    if all(s.indexing_status in terminal for s in status.data.statuses):
        break
    time.sleep(5)

const ids = ["policy_v2", "runbook_deploy"];
const terminal = new Set(["completed", "errored"]);

let status;
while (true) {
  status = await client.context.status({
    database: "acme_corp",
    collection: "default",
    ids: ids,
  });

  const allDone = status.data.statuses.every((s) => terminal.has(s.indexingStatus));
  if (allDone) break;

  await new Promise((r) => setTimeout(r, 5_000));
}

while true; do
  response=$(curl -s -G 'https://api.hydradb.com/context/status' \
    -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
    -H "API-Version: 2" \
    --data-urlencode "database=acme_corp" \
    --data-urlencode "collection=default" \
    --data-urlencode "ids=policy_v2" \
    --data-urlencode "ids=runbook_deploy")

  statuses=$(echo "$response" | jq -r '.data.statuses[].indexing_status')
  if echo "$statuses" | grep -qv '^\(completed\|errored\)$'; then
    sleep 5
    continue
  fi
  echo "$response" | jq
  break
done

Each status in the data payload looks like this:

{
  "statuses": [
    {
      "id": "policy_v2",
      "indexing_status": "completed",
      "success": true
    }
  ]
}

Status values move forward through queued, processing, graph_creation, and completed, or land in errored on failure. A source is already searchable at graph_creation; wait for completed only when you need full graph traversal. Poll every few seconds; most documents complete in 1 to 5 minutes. The full table is on Ingestion Status. If you would rather not poll, register a webhook.

4. Retrieve knowledge

Search with POST /query, using type: "knowledge". Use type: "all" to search a user’s memories in the same call. Both stores are read from the same collection, so if the documents live in their own collection, list it next to the user’s in collections. App sources are searched too; query_apps (on by default) adds thread and link expansion for them. If some documents carry an acl, from a connector or an app source, send the caller’s identity as acl on every query. A query without it ignores those permissions, and a metadata filter does not replace it. See Access Control.

Query knowledge: Python, TypeScript, or cURL

result = client.query(
    database="acme_corp",
    query="How do I rotate API keys?",
    type="knowledge",
)

for chunk in result.data.chunks:
    print(chunk.source_title, chunk.chunk_content)

const result = await client.query({
  database: "acme_corp",
  query: "How do I rotate API keys?",
  type: "knowledge",
});

if (!result.data || typeof result.data === "string") throw new Error("Expected structured query results");
for (const chunk of result.data.chunks) {
  console.log(chunk.sourceTitle, chunk.chunkContent);
}

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "query": "How do I rotate API keys?",
    "type": "knowledge"
  }'

Matching chunks come back in data.chunks, ranked by relevance, each with its source_title and text. See How to Use API Results to turn the response into a prompt, and Query for mode, alpha, and recency_bias.

5. Add metadata for filtering

Metadata is how you bridge structured filters and semantic search. Attach metadata at ingestion, and narrow a query to matching sources with metadata_filters.

Filter by metadata: ingest, then query

On the document_metadata item or app source:

{
  "metadata": { "document_type": "runbook", "environment": "production" }
}

Then at query time:

{
  "query": "How do I rotate API keys?",
  "metadata_filters": {
    "document_type": { "equals": "runbook" },
    "environment": { "equals": "production" }
  }
}

Declare the metadata keys you filter on in the database metadata schema. A database with a schema rejects undeclared keys at ingest, so a filter on one returns nothing. To filter on additional_metadata, nest the keys under additional_metadata in metadata_filters, for example {"metadata_filters": {"additional_metadata": {"author": "Alice"}}}. document_metadata is accepted only as a legacy alias for that nested filter namespace. See Metadata for schema design, filter examples, and the metadata vs additional_metadata decision rule. See Create Database for the schema field configuration (enable_dense_embedding, enable_sparse_embedding).

6. Link documents that belong together

Forceful relations let you declare links between knowledge sources at ingestion time. When a query matches a source that has forceful relations attached, HydraDB pulls the linked sources into the additional_context field of the query response alongside the primary chunks. This is separate from the context graph HydraDB builds on its own. Forceful relations are declared by you, for documents that belong together when the text does not say so: a contract and its addendum, or a runbook and its troubleshooting guide. They link whole sources. To declare the entity and relation graph within one document, replacing extraction for it, use Bring Your Own Graph. On a file, set relations.ids on its document_metadata item. On an app source, set relations.ids the same way, and name the relationship in app_relations so the link also carries a predicate. relations.ids is what makes the linked text come back with query results; a named relationship alone connects the sources without requesting their text. App Sources covers typed targets in full.

Link a runbook to its troubleshooting guide: Python, TypeScript, or cURL

This Notion guide links to a troubleshooting page already ingested with the HydraDB id auth-troubleshooting. Ingest that page first and wait for completed.

client.context.ingest(
    type="knowledge",
    database="acme_corp",
    app_knowledge=json.dumps([
        {
            "id": "auth-guide",
            "title": "Authentication Guide",
            "kind": "knowledge_base",
            "provider": "notion",
            "external_id": "AUTH-GUIDE",
            "fields": {"kind": "knowledge_base", "title": "Authentication Guide", "body": "..."},
            "relations": {"ids": ["auth-troubleshooting"]},
            "app_relations": [
                {"predicate": "linked_to", "target": {"source_id": "auth-troubleshooting"}},
            ],
        }
    ]),
)

await client.context.ingest({
  type: "knowledge",
  database: "acme_corp",
  appKnowledge: JSON.stringify([
    {
      id: "auth-guide",
      title: "Authentication Guide",
      kind: "knowledge_base",
      provider: "notion",
      external_id: "AUTH-GUIDE",
      fields: { kind: "knowledge_base", title: "Authentication Guide", body: "..." },
      relations: { ids: ["auth-troubleshooting"] },
      app_relations: [
        { predicate: "linked_to", target: { source_id: "auth-troubleshooting" } },
      ],
    },
  ]),
});

curl -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=knowledge" \
  -F "database=acme_corp" \
  -F 'app_knowledge=[
    {
      "id": "auth-guide",
      "title": "Authentication Guide",
      "kind": "knowledge_base",
      "provider": "notion",
      "external_id": "AUTH-GUIDE",
      "fields": { "kind": "knowledge_base", "title": "Authentication Guide", "body": "..." },
      "relations": { "ids": ["auth-troubleshooting"] },
      "app_relations": [
        { "predicate": "linked_to", "target": { "source_id": "auth-troubleshooting" } }
      ]
    }
  ]'

query_forceful_relations defaults to true; set it to false to skip the linked sources.

Knowledge sources, thinking mode only: Forceful relations stay within one store, so pointing a knowledge source at a memory ID silently returns nothing. Linked context is fetched only when mode: "thinking" is set on the query, or when mode: "auto" routes to thinking. In fast mode, query_forceful_relations is ignored even if set to true.

Field reference

Request fields

Field	Default	Description
	None	Selects the knowledge store.
	None	Target database.
	default collection	Scope this knowledge to a collection. If omitted, knowledge goes to the database’s default collection, which a query naming another `collection` does not read.
	None	Files for HydraDB to parse: PDF, DOCX, Markdown, CSV, TXT.
	None	One item per file in `documents`, in the same order. The item count must match the file count.
	None	App source items. See the App Sources field reference.
	`true`	Replace existing items with the same `id`.

document_metadata item fields

Field	Description
	Optional stable identifier. Used as the upsert key when `upsert: true`.
	Filterable fields. Keys must match the database metadata schema. Up to 16 KiB as compact JSON.
	Free-form fields for display and bookkeeping. Filterable only when nested under `additional_metadata` in `metadata_filters`. Up to 1 KiB as compact JSON.
	Forcefully connect this source to others with `{ "ids": [...] }`.

App sources accept title, url, and timestamp.

Common mistakes

Mistake	What goes wrong	Fix
Querying knowledge with `type: "memory"`	Nothing returned: wrong store	Use `type: "knowledge"` (or `"all"`) on `POST /query`.
Using `additional_metadata` for hot filterable fields	Filters work only with nested syntax and are less efficient than schema-backed metadata filters	Put hot filter keys in `metadata` and declare them in the database schema, or filter under `metadata_filters: {"additional_metadata": {...}}` for occasional/free-form fields. See Metadata.
Not polling `/context/status` before querying	Chunks aren’t indexed yet, so query results are empty	Wait for `indexing_status: completed` (or `graph_creation` for partial availability).
Sending `document_metadata` as a JSON object instead of a JSON string	`multipart/form-data` validation fails	Stringify `document_metadata` before sending in the `-F` field.
Omitting `database`	`400` error (`database is required`)	Required on every call.

App Sources: ingesting records from apps
Memories: the per-user counterpart to knowledge
Query: how POST /query retrieves knowledge
Metadata: designing filterable schemas
Context Graphs: how the graph layer enriches retrieval
Ingest Context: API Reference
Ingestion Status: API Reference

Get Started

Usage

Organize

Understand

Plugins

For Agents

1. Upload files

What each property in `document_metadata` means

2. Ingest app sources

3. Wait for indexing

4. Retrieve knowledge

5. Add metadata for filtering

6. Link documents that belong together

Field reference

Common mistakes

​1. Upload files

​What each property in document_metadata means

​2. Ingest app sources

​3. Wait for indexing

​4. Retrieve knowledge

​5. Add metadata for filtering

​6. Link documents that belong together

​Field reference

​Common mistakes

​Related

1. Upload files

What each property in `document_metadata` means

2. Ingest app sources

3. Wait for indexing

4. Retrieve knowledge

5. Add metadata for filtering

6. Link documents that belong together

Field reference

Common mistakes

Related