docs(api): versioned V5 API reference (draft — overlaps #1690, not for review)

[Aswin-Ram-K]

What this draft contains

Seven new pages under apps/docs/v5/api-reference/ (overview, ingest, search, content-management, namespaces, organization, profiles) plus apps/docs/docs.json nav entries: a V5 API reference organised by workflow, with a "Legacy API Reference" anchor beside the V5 one.

Grounding rules used throughout: every documented operation traces to real in-repo code (packages/validation/api.ts zod .openapi() schemas, packages/validation/schemas.ts, packages/lib/api.ts, packages/tools/src/...) or to the served OpenAPI documents at /v3/openapi and /v4/openapi (verified byte-identical, 166,681 bytes). No /v5/openapi URL is asserted anywhere — it returns 404.

Relationship to open work — read this first

This draft covers the same ground as #1690 by @sohamd22 (identical title, same 8-file shape), which is open, non-draft, and part of an active stacked PR set. It was produced independently, but it is not submitted for review and should not be treated as a competing contribution: #1690 is the canonical work. It is kept as a draft with this disclosure posted on purpose.

If any of the fact fixes here are useful, they are offered as input to #1690 rather than as a replacement:

• request-level containerTag is singular in the live spec; the plural containerTags is marked deprecated + x-hidden on POST /v3/documents, POST /v3/documents/batch, the multipart file route, and the PATCH /v3/documents/{id} body (it remains correct per-document as documents[].containerTags);
• documentThreshold is marked deprecated in the served spec with no effect on search;
• the by-ids by parameter has no default;
• POST /v3/documents/file multipart uses containerTag (in-repo precedent: apps/docs/ingestion/add-memories.mdx, apps/docs/install.md).

Validation

Structure verified: docs.json parses, all nav entries and internal links resolve, frontmatter terminated on all 7 pages, code fences balanced, git diff --check clean. 14 operations spot-checked against the in-repo zod schemas and the served spec with exact default/enum/deprecation agreement. Independently re-validated by three separate models before this draft was finalised.

[Aswin-Ram-K]

Disclosure (deliberate, from the author): this draft overlaps the open, non-draft PR #1690 by @sohamd22 — same title and the same 8-file scope. #1690 is the canonical work. This draft is intentionally left un-submitted (draft state) and is not offered for review. If any fact fix here is useful to #1690, it is offered as review input only: request-level containerTag is singular in the served spec (plural containerTags is deprecated + x-hidden on POST /v3/documents, /batch, the multipart file route, and the PATCH /v3/documents/{id} body; it stays correct per-document as documents[].containerTags), documentThreshold is deprecated with no effect on search, and the by-ids by parameter has no default.

[MaheshtheDev]

🤖 AI-assisted triage, reviewed by @MaheshtheDev.

Closing, as you noted. #1690 is the main PR for this.