docs: unified ingest and query contract (PRO-1618), stacked on #296

[SohamRatnaparkhi]

Stacked on #296 (tushar/pro-1618-unified-docs). Documents the PRO-1618 unified API contract for POST /context/ingest and POST /query exactly as implemented (app #1625 and the ingest-contract PR stacked on it), and moves every split-era field on unified pages into a "Split databases" section. No page was added or removed; docs.json is unchanged and every touched page is still in the nav.

Pages changed

Ingest

• essentials/v2/ingest.mdx: request body with the context list key (aliases noted, context is what to send), both item shapes, every item field with a one-line meaning, request-level enrich / upsert / instructions defaults, graph_payload keyed by context_id, limits (100 items, 1 MiB per item, 8 MiB per request, context[N] errors), the refused split-era fields, the multipart items form-field note for SDK users, the real 202 response (message is Context queued for ingestion successfully plus the poll-status hint; result items carry source_id, title, status, infer, error, error_code), declared relations, and a before/now table from the Linear field-level diffs.
• api-reference/v2/endpoint/ingest-context.mdx: unified head (JSON body, item field table with context_category returned on query as enrichment_kind, limits, refused fields, 202 response with the real message) with the existing documents / app_knowledge / memories reference kept verbatim under a demoted ## Split databases section.
• api-reference/v2/endpoint/sources-overview.mdx: endpoint table and concepts lead with context[]; split shapes moved to their own section.

Query

• essentials/v2/query.mdx: rewritten. Request without type, with attributes (operator filter), follow_forceful_relations (alias query_forceful_relations), titles, ids, acl, temporal fields; the response as exactly chunks, graph, forceful_relations, llm_prompt with every field described and one complete example (a real server-rendered envelope, request_id and latency_ms placeholders); each chunk (and forceful_relations[].chunk) carries enrichment as a plain string, omitted when empty, and the declared context_category beside it as enrichment_kind (user_preference, business_knowledge or decision_trace; omitted when none was declared, present even without enrichment), enrichmentKind in the TypeScript SDK; llm_prompt documented as the markdown document the server emits (# Query results, ## Results, ## Forceful relations, ## Related facts, ## Temporal facts, ## Sources), its labels [1] / [R1] / [P1] (P in graph[] order), each related fact's relevance after reranking ((query path, relevance 0.81), omitted when a path has no reranked score), the temporal evidence phrase set apart after ;, web-only source links (never s3://...), path_summary never empty (narrated from the hops when the server wrote none, and then not repeated under the chain), a chunk_relation path returned only when one of its hops came from a returned or forceful_relations chunk, how a multi-hop chain reads, and that the SDK build_string helpers return it verbatim, with a two-line inject snippet; the note that chunks carry no source details and GET /context/inspect?database=..&id=<context_id> returns them; old fields only in the "Split databases" section.
• api-reference/v2/endpoint/query.mdx: unified request example, request-body table, four-key ResponseExample (the same real envelope, with enrichment a string and enrichment_kind beside it), behavior notes; type, query_forceful_relations, metadata_filters and the old response shape moved to ## Split databases.
• api-reference/v2/endpoint/query-overview.mdx: decisions are now scope / match / mode; attributes and follow_forceful_relations in the parameter table; response summary is the four keys, with llm_prompt described as markdown.
• essentials/v2/api-results.mdx: build_string guidance removed from the unified path (the server builds llm_prompt, and build_string returns it verbatim there); inject snippets, the verbatim markdown prompt with a section and label table, structured reads (enrichment and enrichment_kind, enrichmentKind in the TypeScript loop), GET /context/inspect for source details; build_string kept in a "Split databases" section.
• essentials/v2/context-graphs.mdx: graph[] paths with triplets ({ entity_id, name } entities, { predicate, context, temporal_details, relationship_id, chunk_id } relations) and path_summary; query_paths / chunk_relations / chunk_id_to_group_ids only in the split section; prompt section now shows the ## Related facts section of llm_prompt (- [P1] **A** -pred→ **B** (query path, relevance 0.81) [1] lines, an exact excerpt of the real envelope) and how a multi-hop chain reads.

Get started and concepts

• get-started/v2/quickstart.mdx: cURL body uses context; SDK tabs keep the items form field with a comment; results read content, path_summary and llm_prompt, with the inject snippet.
• get-started/v2/core-concepts.mdx, get-started/v2/introduction.mdx: context list key, four-key response, no auto-classification.
• essentials/v2/context-categories.mdx: auto means no label (nothing infers a category, per the contract); JSON examples use context; decision-trace graph example in the contract shape; the label comes back as enrichment_kind beside a string enrichment.
• essentials/v2/split-databases.mdx: items -> context; full split-to-item and split-to-unified response field mappings (chunk_content maps to content plus a string enrichment and enrichment_kind; including follow_forceful_relations, forceful_relations[], llm_prompt, and build_string returning llm_prompt verbatim on a unified database); dropped the graph.paths[], forceful_relations.declared and is_memory claims that contradicted the contract; section 6 now separates /query (context_id, no attributes) from list/inspect/PATCH names.
• essentials/v2/architecture.mdx, essentials/v2/databases-and-collections.mdx, essentials/v2/semantic-search.mdx: type removed from flows and examples, weighted collections for personalization, attributes instead of metadata_filters, four-key response.
• essentials/v2/access-control.mdx: acl shown on a context item instead of app_knowledge.
• essentials/v2/attributes.mdx: lead-in note mapping attributes / custom_attributes / attributes filter to the metadata / additional_metadata / metadata_filters names the body still uses (body unchanged).
• essentials/v2/glossary.mdx: "Context item" and "Unified and split databases" entries.
• api-reference/v2/index.mdx: concept and inventory rows for context items and the unified query.

Checks

• mintlify broken-links: no broken links. npx mint@latest validate: build validation passed.
• Every llm_prompt shown (both JSON examples, the unescaped copies on Query and How to Use API Results) is the server test's rendered prompt character for character; the Context graphs excerpt is an exact substring of it.
• No em or en dashes in any changed file.
• Every touched page is referenced in docs.json (no nav changes needed).
• npm run hygiene could not run: the installer's checksum step fails on macOS (sha256sum flag mismatch), unrelated to these docs.

Not in this PR

• api-reference/v2/openapi.json is generated from the application repo and still carries the split-era /query response and multipart ingest schemas; the auto-rendered request/response panels on the two endpoint pages will follow the next spec sync. The prose on those pages is the contract.
• AGENTS.mdx, plugins/*, cookbooks/* still describe the split flow and need their own pass.

🤖 Generated with Claude Code

[openhack-agent]

✅ OpenHack Summary

Security review of docs: unified ingest and query contract (PRO-1618), stacked on #296. 20 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

• api-reference/v2/endpoint/ingest-context.mdx (modified)
• api-reference/v2/endpoint/query-overview.mdx (modified)
• api-reference/v2/endpoint/query.mdx (modified)
• api-reference/v2/endpoint/sources-overview.mdx (modified)
• api-reference/v2/index.mdx (modified)
• essentials/v2/access-control.mdx (modified)
• essentials/v2/api-results.mdx (modified)
• essentials/v2/architecture.mdx (modified)
• essentials/v2/attributes.mdx (modified)
• essentials/v2/context-categories.mdx (modified)
• essentials/v2/context-graphs.mdx (modified)
• essentials/v2/databases-and-collections.mdx (modified)
• essentials/v2/glossary.mdx (modified)
• essentials/v2/ingest.mdx (modified)
• essentials/v2/query.mdx (modified)
• essentials/v2/semantic-search.mdx (modified)
• essentials/v2/split-databases.mdx (modified)
• get-started/v2/core-concepts.mdx (modified)
• get-started/v2/introduction.mdx (modified)
• get-started/v2/quickstart.mdx (modified)

Last reviewed commit: c42b52c · 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: 5/5

The documentation changes appear safe to merge, with no new actionable issues and the previously reported generated-panel conflict resolved.

Summary

Updates the v2 documentation to describe the unified context ingestion and query contracts while retaining legacy behavior in clearly separated split-database sections.

• Documents JSON context ingestion, unified item fields, validation limits, asynchronous status polling, and response fields.
• Documents the unified four-part query response: chunks, graph, forceful_relations, and llm_prompt.
• Updates guides, examples, terminology, filtering, context categories, graph paths, and migration mappings across the v2 documentation.
• Removes stale OpenAPI bindings from the ingest and query endpoint pages, addressing the previously reported generated-panel conflict.
• Greptile automatically discovered a related ticket that helped explain the purpose of this PR: removing the knowledge/memory fork from the unified API while retaining compatibility for existing split-layout databases.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  I[POST /context/ingest] --> U[Unified context items]
  U --> S[Asynchronous indexing]
  S --> Q[POST /query]
  Q --> C[chunks]
  Q --> G[graph]
  Q --> F[forceful_relations]
  Q --> L[llm_prompt]
  D[Split database] --> X[Legacy ingest and query shapes]

Loading

_{Reviews (7) · Last reviewed commit: "docs(unified): enrichment is a string wi..."}

[github-actions]

✅ Mintlify Hygiene

No issues found.