docs: context is the ingest list field everywhere, regenerate the v2 spec (PRO-1618)

[SohamRatnaparkhi]

Stacked on #299.

What

• api-reference/v2/openapi.json is a verbatim copy of application/docs/openapi.json from hydra-db/hydradb-application staging at commit a8a9f5787fe1f40ffb3c67cd4f3288050feb9208 (merge of hydra-db/hydradb-application#1660; the spec file last changed in 39a51a48d and ef1f3c783), the same copy the auto-generate workflow makes. cmp against git show origin/staging:application/docs/openapi.json is clean. It publishes context as the only ingest list field, in the JSON body and in the multipart form, with no items.
• Docs pages match the ingest contract that is on app staging now (hydra-db/hydradb-application#1653 and its follow-ups, #1655 for relation properties, #1657 and #1660).

Contract the pages now describe

• context is the one list name, in the JSON body and the multipart form field. items is removed, with no alias, and no page mentions it as accepted.
• Strict decoding: an unknown key on the body, an item, a conversation turn or inside forceful_relations is a 400 that names the key and lists the accepted fields. The pages that said unknown keys are ignored or dropped are corrected.
• forceful_relations is { context_ids, properties }. properties is a flat map of string, number or boolean values, at most 1 KiB as compact JSON, with no empty key and no reserved key (id, created_at, relation_type, tenant_id, sub_tenant_id).
• A conversation turn is { role, content }. The speaker is the item's user_name (default "User"), so the examples move the per-turn name there. is_markdown is removed.
• Caps: 100 items, 1 MiB of text per item, 8 MiB per request, title at most 1,024 bytes, instructions at most 4,000 characters on the request and on each item. A conversation's system turns count against that budget when they become the item's instructions.
• On the form, upsert and enrich accept true, false, 1 or 0; anything else is a 400. The SDK methods take enrich and instructions as form fields.
• context_category stays undocumented on visible pages.
• Since the previous copy (1d405fdf3): type is published deprecated on every operation and a unified database refuses type: "all" (the docs never teach type); the unified ingest body accepts tenant_id and sub_tenant_id as deprecated aliases, and a non-string tenancy key is a 400; the unified ingest body is capped at 16 MiB (JSON body or context form field), 413 beyond it; query chunks carry received_at, when HydraDB received the item (RFC 3339, not happened_at, omitted when unrecorded).
• Naming: Bring Your Own Graph is the ingest graph_payload page (essentials/v2/bring-your-own-graph); Cypher Graph Collections is the Cypher page (essentials/v2/graph-collections-byog). Paths are unchanged.

Pages changed

• api-reference/v2/endpoint/ingest-context.mdx: examples, SDK param note, item table, limits, unknown-key rule
• essentials/v2/ingest.mdx: SDK note, item table, limits, text and conversation examples, declared relations, common mistakes
• AGENTS.mdx: examples, item table, conversations, limits, SDK section
• api-reference/v2/sdks.mdx, api-reference/v2/error-responses.mdx, api-reference/v2/endpoint/sources-overview.mdx
• get-started/v2/quickstart.mdx, get-started/v2/core-concepts.mdx
• latest commit: essentials/v2/query.mdx, api-reference/v2/endpoint/query.mdx, essentials/v2/api-results.mdx, plugins/cli.mdx (received_at); essentials/v2/databases-and-collections.mdx (non-string tenancy key); essentials/v2/graph-collections-byog.mdx, essentials/v2/bring-your-own-graph.mdx, plugins/mcp.mdx (rename); spaced hyphens used as dashes replaced on the API reference pages; mintlify-hygiene.toml no longer excludes the Cypher page, which is in nav
• hidden: essentials/v2/split-databases.mdx (a unified database accepts no split aliases), essentials/v2/context-categories.mdx (turn name example)

Earlier commits on this branch also renamed the SDK examples to context across the other pages.

Checks

• all 27 pages bound with openapi: "api-reference/v2/openapi.json ..." resolve against the new spec
• npx mint@latest validate: passed
• npx mint@latest broken-links: no broken links
• mintlify-hygiene check (v0.3.0): no findings
• docs.json parses; no em or en dashes added

Once this lands, close the auto-update PR #297; this PR carries a newer copy of the same file.

🤖 Generated with Claude Code

[openhack-agent]

✅ OpenHack Summary

Security review of docs: context is the ingest list field everywhere, regenerate the v2 spec (PRO-1618). 66 changed files; 0 findings at or above the low reporting threshold.

0   0   0   0

Confidence Score: 5/5

No reportable security findings were detected in this scan.

Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage.

Files Needing Attention: None

Important Files Changed

• AGENTS.mdx (modified)
• api-reference/v2/endpoint/add-connector-resource.mdx (modified)
• api-reference/v2/endpoint/configure-connector.mdx (modified)
• api-reference/v2/endpoint/connector-resources.mdx (modified)
• api-reference/v2/endpoint/connectors-overview.mdx (modified)
• api-reference/v2/endpoint/create-connector.mdx (modified)
• api-reference/v2/endpoint/create-tenant.mdx (modified)
• api-reference/v2/endpoint/delete-collection.mdx (modified)
• api-reference/v2/endpoint/delete-connector-resource.mdx (modified)
• api-reference/v2/endpoint/delete-connector.mdx (modified)
• api-reference/v2/endpoint/delete-source.mdx (modified)
• api-reference/v2/endpoint/delete-tenant.mdx (modified)
• api-reference/v2/endpoint/discover-connector-resources.mdx (modified)
• api-reference/v2/endpoint/fetch-content.mdx (modified)
• api-reference/v2/endpoint/get-connector-provider.mdx (modified)
• api-reference/v2/endpoint/get-connector.mdx (modified)
• api-reference/v2/endpoint/ingest-context.mdx (modified)
• api-reference/v2/endpoint/list-connector-providers.mdx (modified)
• api-reference/v2/endpoint/list-connectors.mdx (modified)
• api-reference/v2/endpoint/list-documents.mdx (modified)
• api-reference/v2/endpoint/list-sub-tenants.mdx (modified)
• api-reference/v2/endpoint/list-tenants.mdx (modified)
• api-reference/v2/endpoint/list-webhook-deliveries.mdx (modified)
• api-reference/v2/endpoint/query-overview.mdx (modified)
• api-reference/v2/endpoint/query.mdx (modified)

View all 66 changed files

Last reviewed commit: 8760089 · View review on OpenHack

---

TIP: Mention @openhack-agent in a PR comment to request a review or ask a question. Use @openhack-agent fix all for every finding, or @openhack-agent fix unresolved threads for open review threads only.

[openhack-agent]

OpenHack reviewed this commit. See the OpenHack Summary for the confidence score and fix actions.

[greptile-apps]

Confidence Score: 4/5

The PR is not yet safe to merge because the published feedback schema permits request shapes that the documented server contract rejects.

Summary

The PR republishes the unified v2 API contract and updates documentation to use context consistently for ingestion, alongside revised query, graph, tenancy, and SDK guidance.

• Regenerates the machine-readable v2 OpenAPI specification from the application documentation view.
• Aligns ingest examples and validation guidance with the strict unified context contract.
• Updates query results with received_at and removes the non-public temporal_intent field.
• Renames graph documentation concepts and adjusts SDK examples.
• One feedback-request validation contract was lost during the latest regeneration.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Application v2 contract] --> B[Regenerated OpenAPI specification]
  B --> C[Mintlify endpoint reference]
  B --> D[Generated SDK types and validation]
  C --> E[Application developers]
  D --> E
  E --> F[HydraDB v2 API]

Loading

_{Reviews (10) · Last reviewed commit: "docs: API reference renders the linted d..."}

[SohamRatnaparkhi]

@greptileai review. The one P1 (keep items/contexts as aliases) is answered in the thread: they were removed on purpose by the API owner, and this spec is a verbatim copy of app staging, which refuses them.

[github-actions]

✅ Mintlify Hygiene

No issues found.

[greptile-apps]

Comments Outside Diff

These findings sit on lines the diff does not cover, so they could not be posted inline. Each one leaves this list once its file changes.

•  Feedback constraints were dropped api-reference/v2/openapi.json:306 ▶

  The regenerated schema now requires only request_id. It therefore allows requests with no usable feedback or ground_truth, empty ground truth, and collection without database, even though the endpoint documentation says the server rejects these requests with 400. Generated SDKs and schema-based validators will accept payloads that fail at runtime. Restore the conditional validation rules in the published contract.

[SohamRatnaparkhi]

@greptile-apps On "Feedback constraints were dropped": this is deliberate. api-reference/v2/openapi.json is now the docs view that hydradb-application builds for the reference site (docs/openapi.docs.json, app PR #1669). The SDKs are not generated from it; they use the app's docs/openapi.json, which still carries every rule on feedback.SubmitRequest (the feedback/ground_truth anyOf and the dependentSchemas). Mintlify draws validation-only unions as untitled "Option 1 / Option 2" tabs with nothing in them, so the docs view drops them and states the rule on the body instead: "Send feedback, ground_truth, or both. A request with neither is rejected with 400." The server enforces the rules either way.

[greptile-apps]

You're right — this is intentional and matches the docs-view design in hydradb-application#1669. The published spec is a rendering-oriented view, while the SDK/server spec retains the feedback/ground_truth anyOf and dependentSchemas; the server still enforces those constraints, and the body description documents the requirement for the reference page. I'll withdraw the “Feedback constraints were dropped” finding.