The reference is structurally complete (tenants, ingestion, recall, memories, webhooks all have pages), but multiple high-impact contradictions across pages, a broken auth example, and undocumented rate limits leave both humans and coding agents reasoning over conflicting source-of-truth.
1. additional_metadata filterability contradicts itself across four pages (critical)
Problem: The same field is documented two opposite ways. In /api-reference/endpoint/upload-knowledge under file_metadata: "additional_metadata — object — Document-level metadata. Filterable in recall queries." But in /essentials/knowledge for the identical structure: "additional_metadata — Free-form fields for display and bookkeeping. Not filterable." And /essentials/architecture agrees with the second: "Flexible source-level metadata attached to a source; not matchable at recall time." /essentials/memories also says "Not matchable." Even within upload-knowledge itself, app_knowledge says additional_metadata is "not filterable at recall time" while file_metadata says it is filterable.
Consequence: A developer (or an agent) reading the API reference will write recall queries that filter on additional_metadata, then debug why filters return empty results because the recall engine actually only filters tenant-level metadata. The /api-reference/endpoint/full-recall page confirms the engine matches against additional_metadata only inside a nestedadditional_metadata filter — but that nuance is invisible if you trusted the upload-knowledge field table.
The fix: Pick one contract. Either (a) make additional_metadata not filterable everywhere and remove the "filterable" wording from upload-knowledge, or (b) document the actual nested-key filter mechanism uniformly across all four pages, with one canonical example. Don't have the file-metadata table and the recall-filters page disagree.
2. Tenant provisioning time contradicts itself on the same endpoint page (critical)
Location:/api-reference/endpoint/infra-status (and mirrored in )
Problem: Two adjacent paragraphs on the same page give different answers. First: "Tenant creation typically takes 1–2 minutes for Free and Ship plans. For Enterprise plans, provisioning can take 4–5 minutes due to complete physical isolation." Then, under "Polling pattern": "Typical provisioning time: 10–30 seconds." That's a 10x gap between two statements about the exact same operation.
Consequence: Developers building polling logic don't know whether to expect 30 seconds or 5 minutes. An agent generating retry/backoff code will either time out prematurely (using 30s) or wait far too long before surfacing errors (using 5 min). Either way the first integration looks broken.
The fix: Replace the "10–30 seconds" line with the per-plan numbers, or split them clearly: "Cold-path provisioning: 1–2 min (Free/Ship), 4–5 min (Enterprise). Warm-path repeat polls: 10–30 s." Stop quoting two different SLAs three paragraphs apart.
3. Authorization: Bearer example is missing its placeholder (critical)
Location:/api-reference/index
Problem: The Authentication line reads literally: "Every endpoint requires Authorization: Bearer " — ending with a trailing space and nothing else. There is no <API_KEY>, $HYDRADB_API_KEY, or your-api-key-here token shown. The 401 error reference page also references "Missing Authorization: Bearer header" with the same dangling format.
Consequence: Copy-paste from the reference produces a header with no token. Coding agents that extract auth patterns by regex (Bearer\s+\S+) will not match, and may emit a header with literally Bearer and an empty token. The 401 page can't tell users they sent an empty token because the canonical example is an empty token.
The fix: Render the placeholder explicitly — Authorization: Bearer <HYDRADB_API_KEY> — and use that exact form on every page that mentions auth. Make sure your Mintlify component for the API key isn't being stripped from the rendered HTML.
4. sub_tenant_id default behavior differs between Memories and Knowledge (critical)
Problem: Three different defaults for omitting sub_tenant_id:
/essentials/knowledge: "If omitted, knowledge is available to all sub-tenants."
/essentials/memories: "If omitted, HydraDB uses the tenant's default sub-tenant."
/api-reference/endpoint/verify-processing: "If omitted or null, the default sub-tenant is used."
Consequence: This is a tenancy/isolation contract. A developer who reads the memories page and assumes the same default applies to knowledge ingestion will accidentally upload knowledge that's visible across all sub-tenants — exactly the cross-tenant leakage the product markets against ("strict no cross-tenant data aggregation policy"). This is the worst class of contradiction: the bug it creates is silent and isolation-breaking.
The fix: Either (a) make Knowledge match Memories (sub_tenant_id omitted → default sub-tenant) and update the page, or (b) make this asymmetry explicit with a callout on both pages: "⚠ Memories and Knowledge differ on the meaning of omitted sub_tenant_id." Don't leave the same field with two opposite defaults across primitives.
5. tenant_metadata_schema has different types in TypeScript and Python (significant)
Location:/api-reference/endpoint/create-tenant
Problem: The parameter table reads: "tenant_metadata_schema — Type: array (TypeScript) / object (Python) — No — Defines tenant-level metadata fields."
Consequence: The same logical field has two structurally different shapes depending on which SDK you use. There's no link to the two distinct schemas, no example showing the difference, and no explanation of why. Cross-language teams sharing config can't share this. An OpenAPI-driven client generator will emit one shape; the other SDK won't accept it.
The fix: Document both shapes with side-by-side examples, link to the schema for each, and explain whether the array-of-objects (TS) and object-keyed-by-name (Python) are isomorphic. If they aren't, fix the SDKs to match. The OpenAPI spec can only describe one — say which one.
6. Rate limits are an email address, not a document (significant)
Location:/api-reference/index
Problem: "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."
Consequence: No numbers. Not per-endpoint, not per-plan, not even an order of magnitude. Developers can't size workers, can't write meaningful backoff strategies, and can't decide whether to ship without a private email exchange. Agents writing client code will guess — usually wrong. For a product positioned on sub-200ms latency, the absence of throughput numbers is conspicuous.
The fix: Publish per-plan numerical limits for each endpoint group (ingestion, recall, list/fetch), the Retry-After header behavior on 429s, and any burst allowances. If limits are negotiated per-customer, publish the default tier values and say "Enterprise customers can request higher limits."
7. llm.txt is at a non-standard path and is the wrong filename (significant)
Location:/get-started/introduction
Problem: The intro says: "For developers using LLMs or IDEs, we have compiled an uploadable summary of the docs here llm.txt (/assets/llm.txt)." The emerging convention is llms.txt and llms-full.txt served from the site root (i.e., docs.hydradb.com/llms.txt). HydraDB's file is named llm.txt (singular) and lives under /assets/.
Consequence: Agents and crawlers that look for the conventional /llms.txt and /llms-full.txt (Cursor, Claude, future IDE integrations) won't find it. This nullifies the indexing benefit you were trying to provide.
The fix: Publish both llms.txt (index) and llms-full.txt (full corpus) at the docs root. Keep /assets/llm.txt as a redirect if you must, but the canonical locations should be /llms.txt and /llms-full.txt.
8. success and completed are both valid processing statuses with the same meaning (significant)
Problem: The status enum table lists six values including: "completed — Fully indexed and graphed. Ready for all recall modes." and "success — Alias for completed. May appear in some legacy responses."
Consequence: A developer or agent writing if status == "completed" will silently miss the legacy success responses and report items as still-processing when they're actually done. Both branches need to be hardcoded, but nothing in the OpenAPI enum signals that.
The fix: Either retire the success value server-side (recommended — it's described as legacy), or list it as a first-class enum member in OpenAPI and tell developers to treat {"success","completed"} as a single set in their checks. Don't half-deprecate it in prose only.
9. verify-processing query parameters are all optional with nonsensical defaults (significant)
Problem: The page states: "Per api-reference/openapi.json, all query parameters below are optional in the spec (each has a default)." The defaults shown: file_ids defaults to [], tenant_id defaults to "". There's no description of what happens when you call this endpoint with no tenant_id and no file_ids — does it return nothing, error, or query the universe?
Consequence: Coding agents that generate from OpenAPI will treat the call as parameterless and call it with empty defaults. The actual behavior is undocumented. tenant_id="" as a "valid" default is almost certainly a server-side accident — empty-string tenants shouldn't exist given the strong multi-tenancy claims elsewhere.
The fix: Mark tenant_id as required (or document the cross-tenant fallback explicitly), document the empty-file_ids behavior (return all in-flight items? error? a 400?), and remove the deprecated file_id from the public reference now that file_ids supersedes it.
10. client.passthrough.fetch() collides conceptually with client.fetch.* (minor)
Location:/api-reference/sdks
Problem: The SDK overview groups /list/* and /fetch/* under client.fetch, then lists an "additional client" client.passthrough.fetch() for POST /passthrough/fetch. So there are two unrelated .fetch entry points on the client. The doc never explains what "passthrough" is or when to use it instead of client.fetch.*.
Consequence: Autocomplete and agent code generation will pick whichever name appeared first in training data. There's no disambiguating description for passthrough anywhere in the scraped pages.
The fix: Add a one-sentence description of passthrough (what it proxies, when it's needed) and either rename one of the two fetch entry points or add a "When to use" note next to each. A client.passthrough.fetch that does something completely different from client.fetch.* is a footgun.
What they do well
The retrieval ranking model is documented with real specifics: alpha blending, metadata_filters semantics, the explicit "no $gte / $in / $regex" disclaimer, and the OpenAPI cross-reference on RecallSearchRequest.metadata_filters.
Asynchronous tenant provisioning is honestly surfaced — the accepted status, the polling pattern, and vectorstore_status[0] vs [1] for Memories vs Knowledge are spelled out.
Webhooks are documented with the right headers (X-HydraDB-Signature, X-HydraDB-Delivery-ID, X-HydraDB-Event) at the level an integrator needs.
Top 3 recommendations
Fix the four-page contradiction on additional_metadata filterability and the three-page split on sub_tenant_id defaults. These are the two contradictions most likely to cause silent isolation/filter bugs in production.
Publish real rate-limit numbers and a non-empty Authorization: Bearer <key> example. Both of these are blocking for anyone shipping without a sales call.
Move llms.txt and llms-full.txt to the docs root with conventional names, and reconcile the two provisioning-time numbers on the infra-status page so agents and humans see one SLA.
Fixed
0
Skip
92
Fail
0
Summary
Verified 108 runnable snippets across 15 HydraDB documentation pages. The provided API key authenticates successfully, but the associated account is already at its 2-tenant plan limit (existing tenants: trial-1234, trial-2). The documentation examples use placeholder tenant IDs (my_first_tenant, acme_corp, my_embeddings_tenant) that cannot be provisioned on this account, so almost every tenant-scoped snippet is SKIPped as "setup unavailable" rather than executed against substitute IDs (per instructions, snippets are run as written).
Snippets that PASSed cover account-scoped or tenant-agnostic operations: the /tenants/infra/status endpoint (which returns a structured response even for nonexistent tenants), the entire /webhooks/indexing surface, the TypeScript SDK install + client construction, and the bash export env-var snippet. No FAIL rows: every non-success outcome traced to (a) plan-limit / missing tenant setup, (b) missing local file fixtures (/path/to/contract.pdf), (c) literal <placeholder> strings in template URLs, or (d) the Python SDK requiring Python ≥3.10 while only 3.9 is available in this environment.
Note: user-supplied [REDACTED] does not exist on the account; actual tenants are trial-1234 and trial-2. This did not change any verification outcome because snippets are run as written using their documented placeholder IDs.
Required credentials
HYDRA_DB_API_KEY (user-provided HydraDB API key, used for every Authorization: Bearer … header)
ts withRetry helper around client.recall.fullRecall
SKIP
Partial fragment: utility function whose only invocation targets a non-existent tenant; cannot observe documented retry behavior without injecting a 429/500.
python with_retry helper
SKIP
Runtime unavailable.
js raw retryRequest(url, options) helper
SKIP
Partial fragment: undefined url/options; no invocation in snippet.
ts try/catch w/ HydraDBError switch
SKIP
Partial fragment: pattern code; underlying fullRecall would 404 (tenant absent) not exercise the documented TENANT_NOT_FOUND / RATE_LIMITED / UNAUTHORIZED branches.
Returned {"registered":true,"signing_secret_configured":true,...}.
bash curl GET webhook registration
PASS
Returned the registered URL + event_types.
bash curl edit webhook (re-POST)
PASS
Returned updated registration.
bash curl POST /webhooks/indexing/test
PASS
API call succeeded (HTTP 200); body explained delivered:false because the example URL api.example.com resolves to a non-public address — documented behavior of the endpoint, not a snippet error.
bash curl DELETE /webhooks/indexing
PASS
Returned {"deleted":true}.
bash curl list deliveries ?limit=20
PASS
Returned 6 deliveries with documented fields.
bash curl filter deliveries ?status=failed
PASS
Returned {"deliveries":[],"count":0}.
bash curl paginate ?cursor=<next_cursor>
SKIP
Partial fragment: <next_cursor> is a literal placeholder; API responded "Invalid cursor".