How to Use API Results

POST /query retrieves context for your question. By default, data.llm_prompt contains the question, matching passages, source references, and citation instructions in one Markdown string. Pass this string to your model and ask it to answer using the supplied context.

Choose a response format

Set response_format on the query request. The result is under data in the response envelope.

`response_format`	Returned `data`
Omitted, the default	Object containing `llm_prompt` and individual results.
`"markdown"`	The same Markdown text returned directly as `data`.
`"structured"`	Object containing individual results, without `llm_prompt`.

Send context to your model

In SDK 2.1.7 or later, build_string(result) in Python and buildString(result) in TypeScript read data.llm_prompt into the context variable below. The model call then includes context and the original question in the same message.

import os
from hydra_db import HydraDB
from hydra_db.helpers import build_string
from openai import OpenAI

hydra = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])
openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

question = "How does authentication work?"

result = hydra.query(
    database="your-database",
    collection="your-collection",
    query=question,
    type="knowledge",
    query_by="hybrid",
    mode="fast",
    graph_context=True,
)

context = build_string(result)

completion = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
        },
        {
            "role": "user",
            "content": f"Context:\n{context}\n\nQuestion: {question}",
        },
    ],
)

print(completion.choices[0].message.content)

import { HydraDBClient } from "@hydradb/sdk";
import { buildString } from "@hydradb/sdk/helpers";
import OpenAI from "openai";

const hydra = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const question = "How does authentication work?";

const result = await hydra.query({
  database: "your-database",
  collection: "your-collection",
  query: question,
  type: "knowledge",
  queryBy: "hybrid",
  mode: "fast",
  graphContext: true,
});

const context = buildString(result);

const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
    },
    {
      role: "user",
      content: `Context:\n${context}\n\nQuestion: ${question}`,
    },
  ],
});

console.log(completion.choices[0].message.content);

import asyncio
import os

from hydra_db import AsyncHydraDB
from hydra_db.helpers import build_string
from openai import AsyncOpenAI

hydra = AsyncHydraDB(token=os.environ["HYDRA_DB_API_KEY"])
openai_client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

question = "How does authentication work?"

async def main():
    result = await hydra.query(
        database="your-database",
        collection="your-collection",
        query=question,
        type="knowledge",
        query_by="hybrid",
        mode="fast",
        graph_context=True,
    )

    context = build_string(result)

    completion = await openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
            },
            {
                "role": "user",
                "content": f"Context:\n{context}\n\nQuestion: {question}",
            },
        ],
    )

    print(completion.choices[0].message.content)

asyncio.run(main())

Use HTTP without the SDK

Read data.llm_prompt from the JSON response. Use that string as context in the model call above.

import os
import httpx

response = httpx.post(
    "https://api.hydradb.com/query",
    headers={"Authorization": f"Bearer {os.environ['HYDRA_DB_API_KEY']}", "API-Version": "2"},
    json={"database": "acme_corp", "query": "What is our refund policy?"},
    timeout=60,
)
response.raise_for_status()
context = response.json()["data"]["llm_prompt"]

const response = await fetch("https://api.hydradb.com/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HYDRA_DB_API_KEY}`,
    "API-Version": "2",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ database: "acme_corp", query: "What is our refund policy?" }),
});
if (!response.ok) throw new Error(`Query failed with HTTP ${response.status}`);
const result = await response.json();
const context = result.data.llm_prompt;

curl --fail-with-body '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":"What is our refund policy?"}'

Request Markdown only

Set response_format: "markdown" to return the same context text directly as data, instead of inside data.llm_prompt. The SDK helpers above handle both formats.

{
  "database": "acme_corp",
  "query": "What is our refund policy?",
  "response_format": "markdown"
}

Read citations and content labels

The prompt numbers ranked results as [1], [2], and so on. Explicitly linked results use [R1], [R2], and so on. Ask your model to keep these labels when citing the context. A result can contain Original content, the source text, Enriched content, context HydraDB added, or both. Sections for related facts, dated facts, and sources appear when relevant. A query with no matches returns a no-results message rather than an empty prompt, including any filters that constrained the search.

Work with structured results

Use response_format: "structured" to omit llm_prompt when your application formats the results itself. Individual passages, scores, and source details are available in both the default and structured responses.

result = hydra.query(
    database="your-database",
    collection="your-collection",
    query="How does authentication work?",
    response_format="structured",
)

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

const result = await hydra.query({
  database: "your-database",
  collection: "your-collection",
  query: "How does authentication work?",
  responseFormat: "structured",
});

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 --fail-with-body 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "your-database",
    "collection": "your-collection",
    "query": "How does authentication work?",
    "response_format": "structured"
  }'

Response fields and graph data

chunks contains matching passages, scores, source IDs, and titles. Preserve the returned order.
graph_context.query_paths contains relationships relevant to the query. See Context Graphs.
graph_context.chunk_relations groups relationships by group_id. Use chunk_id_to_group_ids to connect them to chunks.
additional_context maps extra_context_ids to related chunks.

See Query for the full response schema and examples.

Combine knowledge and memories

Use one POST /query with type: "all". HydraDB queries both stores in parallel and returns one merged, ranked result set. This example searches shared documents in company_docs and the user’s memories in user_123. Use the collections you ingested into; both must exist. For restricted documents, also send the caller’s identity as acl. Use the printed context in the model call shown above.

import os
from hydra_db import HydraDB
from hydra_db.helpers import build_string

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

question = "What is our refund policy?"

result = hydra.query(
    database="acme_corp",
    collections=["company_docs", "user_123"],
    query=question,
    type="all",
    query_by="hybrid",
    mode="thinking",
)

print(build_string(result))

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

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

const question = "What is our refund policy?";

const result = await hydra.query({
  database: "acme_corp",
  collections: ["company_docs", "user_123"],
  query: question,
  type: "all",
  queryBy: "hybrid",
  mode: "thinking",
});

console.log(buildString(result));

import asyncio
import os

from hydra_db import AsyncHydraDB
from hydra_db.helpers import build_string

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

question = "What is our refund policy?"

async def main():
    result = await hydra.query(
        database="acme_corp",
        collections=["company_docs", "user_123"],
        query=question,
        type="all",
        query_by="hybrid",
        mode="thinking",
    )

    print(build_string(result))

asyncio.run(main())

If knowledge and memories need different search terms, make separate POST /query requests with type: "knowledge" and type: "memory".

Common mistakes

Mistake	What goes wrong	Fix
Reading `data.llm_prompt` with `response_format: "structured"`	The prompt field is omitted	Read the structured fields, or omit `response_format` to get both.
Passing the raw result object to the LLM	Wastes tokens on IDs and metadata	Use `build_string` / `buildString`.
Not including `collection` (formerly `sub_tenant_id`) when querying memories	Queries the default collection instead of the user’s	Always pass the same `collection` used at ingestion.
Including too many chunks	Token overflow or answer quality drops	Start at `max_results: 10`; reduce if needed.
Re-sorting chunks client-side	Overrides HydraDB’s ranking	Preserve the server-returned order.
Missing a grounding instruction	The model invents answers when retrieval is thin	System prompt: answer only from the provided context.
Setting `graph_context: false` and expecting graph fields	Graph context will be omitted (in fast mode; thinking always returns it)	`graph_context` is on by default; only set it to `false` when you explicitly don’t want graph data.
Using `query_forceful_relations` with `mode: "fast"`	Flag is ignored	`query_forceful_relations` only takes effect when `mode: "thinking"` (or `"auto"` routed to thinking).
Looking up `chunk_relations` without `chunk_id_to_group_ids`	The right relations don’t attach to the right chunk	Use `chunk_id_to_group_ids[chunk_uuid]` to find the `group_id`s, then filter `chunk_relations` by them.

Query: request parameters and response shape
Memories: what POST /query with type: "memory" queries
Knowledge: what POST /query with type: "knowledge" queries
Context Graphs: what graph_context fields contain

Get Started

Usage

Organize

Understand

Plugins

For Agents

How to Use API Results

Choose a response format

Send context to your model

Request Markdown only

Read citations and content labels

Work with structured results

Combine knowledge and memories

Common mistakes

​Choose a response format

​Send context to your model

​Request Markdown only

​Read citations and content labels

​Work with structured results

​Combine knowledge and memories

​Common mistakes

​Related

Choose a response format

Send context to your model

Request Markdown only

Read citations and content labels

Work with structured results

Combine knowledge and memories

Common mistakes

Related