docs: add versions & compatibility overview page

[maxdeichmann]

What

Adds /docs/compatibility as a single reference for how Langfuse server, SDK, and API versions relate across Langfuse Cloud and self-hosted, plus a few cross-links to it.

New page sections:

• GA versions — current server / Python / JS-TS majors (with live version badges).
• SDK ↔ server compatibility — minimum self-hosted server per SDK version, status, and per-version upgrade guides.
• Server versions — v1–v4 (incl. v4 "Fast Preview"), with a dedicated security-patches column (v3 + v4 supported; v1 + v2 end of life).
• API versions — ingestion (OTel vs legacy) and a single read-APIs table covering current / legacy / deprecated endpoints plus the /api/public/mcp MCP server (v4-only).
• Evaluations & integrations — current vs deprecated versions for evals (observation vs trace level) and the PostHog / blob-storage-export / Mixpanel integrations (enriched vs legacy).
• How versioning works — semver policy + release-note links.

Cross-links added from the SDK overview, the self-hosting versioning page, and the compatibility FAQ.

Notes for reviewers

• All version facts were ground-truthed against the langfuse, langfuse-python, and langfuse-js source (not just docs).
• A couple of items intentionally follow product intent over the current spec/docs and are worth a sanity check:
  • observations/{id}, traces/{id}, and sessions are shown Deprecated (not yet flagged in the OpenAPI/Fern spec).
  • Trace-level evals are shown deprecated, which conflicts with a line in llm-as-a-judge-migration.mdx ("not a deprecation") — that FAQ line likely needs updating for consistency.
  • The /docs/v4 MCP note says "v4 only"; the existing mcp-server.mdx says the MCP server is available today for prompt management — may need reconciling.

🤖 Generated with Claude Code

Greptile Summary

This PR adds a new /docs/compatibility reference page consolidating Langfuse server, SDK, and API version information in one place, with cross-links added from three existing pages (SDK overview, versioning page, and the compatibility FAQ).

• The new page covers GA versions with live badges, an SDK ↔ server compatibility matrix, server version history, API endpoint status (ingestion + read APIs), and an evaluations/integrations table.
• Two factual inconsistencies with existing docs exist that need resolving before merge: the MCP server is labeled "v4 only" while mcp-server.mdx lists it as available on all Cloud regions today; and trace-level evaluations are labeled "Deprecated" while llm-as-a-judge-migration.mdx explicitly says it is "not a deprecation."

Confidence Score: 3/5

The page itself is purely documentation with no runtime risk, but two of its factual claims directly contradict existing live pages, which would mislead users about what is available today.

The new compatibility page conflicts with two existing docs: the MCP server page shows Cloud endpoints are live today while this page labels the endpoint 'v4 only', and the LLM-as-a-judge migration FAQ explicitly says trace-level evaluation is 'an upgrade path, not a deprecation' while this page labels it Deprecated. Both conflicts are acknowledged in the PR description but left unresolved.

content/docs/compatibility.mdx — the MCP server row and the trace-level evaluation row both need to be reconciled with their source-of-truth pages before merge.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User / SDK] -->|OTel OTLP| B["POST /api/public/otel/v1/traces\n(Recommended)"]
    A -->|Legacy batch| C["POST /api/public/ingestion\n(Deprecated)"]

    B --> D[Langfuse Server v3 GA]
    C --> D

    D --> E["GET /api/public/v3/scores\n(Current - GA)"]
    D --> F["GET /api/public/v2/observations\n(Current - v4 preview opt-in)"]
    D --> G["GET /api/public/v2/metrics\n(Current - v4 preview opt-in)"]
    D --> H["Legacy endpoints\n(observations, scores, metrics)\n(Still work)"]
    D --> I["Deprecated endpoints\n(observations/{id}, traces/{id}, sessions)\n(Will be removed)"]

    D --> J{v4 Fast Preview?}
    J -->|Cloud GA / self-hosted opt-in| F
    J -->|Cloud GA / self-hosted opt-in| G
    J -->|Cloud| K["/api/public/mcp\n(MCP Server)"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User / SDK] -->|OTel OTLP| B["POST /api/public/otel/v1/traces\n(Recommended)"]
    A -->|Legacy batch| C["POST /api/public/ingestion\n(Deprecated)"]

    B --> D[Langfuse Server v3 GA]
    C --> D

    D --> E["GET /api/public/v3/scores\n(Current - GA)"]
    D --> F["GET /api/public/v2/observations\n(Current - v4 preview opt-in)"]
    D --> G["GET /api/public/v2/metrics\n(Current - v4 preview opt-in)"]
    D --> H["Legacy endpoints\n(observations, scores, metrics)\n(Still work)"]
    D --> I["Deprecated endpoints\n(observations/{id}, traces/{id}, sessions)\n(Will be removed)"]

    D --> J{v4 Fast Preview?}
    J -->|Cloud GA / self-hosted opt-in| F
    J -->|Cloud GA / self-hosted opt-in| G
    J -->|Cloud| K["/api/public/mcp\n(MCP Server)"]

Loading

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
content/docs/compatibility.mdx:78
**MCP server availability contradicts existing docs**

The table marks `/api/public/mcp` as "v4 ([Fast Preview](/docs/v4)) only", but `content/docs/api-and-data-platform/features/mcp-server.mdx` lists active endpoints for Cloud EU, Cloud US, Cloud Japan, and HIPAA today with no v4 prerequisite. Users reading this page will incorrectly conclude the MCP server is unavailable to them, while the dedicated MCP page will tell them it is. The PR description flags this as needing reconciliation — one of the two pages needs to be authoritative before this goes live.

### Issue 2 of 3
content/docs/compatibility.mdx:96
**"Deprecated" label for trace-level evals directly contradicts existing FAQ**

`content/faq/all/llm-as-a-judge-migration.mdx` explicitly states: *"Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation."* Labeling trace-level evaluation as **Deprecated** here contradicts that page and will confuse users who read both. The PR description acknowledges this conflict. Both pages will be live simultaneously, so one of them needs to be corrected before this merges — either the FAQ line should be updated or the deprecation label here should be softened to "Legacy".

### Issue 3 of 3
content/docs/compatibility.mdx:76-77
**Misleading replacement endpoint for `traces/{id}` and `sessions`**

Both `GET /api/public/traces/{id}` and `GET /api/public/sessions` point users to `GET /api/public/v2/observations` as their replacement. Observations, traces, and sessions are conceptually distinct resources; a user migrating from the sessions list endpoint to an observations list endpoint would get fundamentally different data. If the v4 data model intentionally collapses these, a brief note explaining the conceptual change would reduce confusion — otherwise readers may assume the replacement is a straightforward semantic equivalent.

_{Reviews (1): Last reviewed commit: "docs: add versions & compatibility overv..." | Re-trigger Greptile}

Greptile also left 3 inline comments on this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	Jul 8, 2026 9:39pm

[github-actions]

@claude review

[greptile-apps]

MCP server availability contradicts existing docs

The table marks /api/public/mcp as "v4 (Fast Preview) only", but content/docs/api-and-data-platform/features/mcp-server.mdx lists active endpoints for Cloud EU, Cloud US, Cloud Japan, and HIPAA today with no v4 prerequisite. Users reading this page will incorrectly conclude the MCP server is unavailable to them, while the dedicated MCP page will tell them it is. The PR description flags this as needing reconciliation — one of the two pages needs to be authoritative before this goes live.

Prompt To Fix With AI

This is a comment left during a code review.
Path: content/docs/compatibility.mdx
Line: 78

Comment:
**MCP server availability contradicts existing docs**

The table marks `/api/public/mcp` as "v4 ([Fast Preview](/docs/v4)) only", but `content/docs/api-and-data-platform/features/mcp-server.mdx` lists active endpoints for Cloud EU, Cloud US, Cloud Japan, and HIPAA today with no v4 prerequisite. Users reading this page will incorrectly conclude the MCP server is unavailable to them, while the dedicated MCP page will tell them it is. The PR description flags this as needing reconciliation — one of the two pages needs to be authoritative before this goes live.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

"Deprecated" label for trace-level evals directly contradicts existing FAQ

content/faq/all/llm-as-a-judge-migration.mdx explicitly states: "Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation." Labeling trace-level evaluation as Deprecated here contradicts that page and will confuse users who read both. The PR description acknowledges this conflict. Both pages will be live simultaneously, so one of them needs to be corrected before this merges — either the FAQ line should be updated or the deprecation label here should be softened to "Legacy".

Prompt To Fix With AI

This is a comment left during a code review.
Path: content/docs/compatibility.mdx
Line: 96

Comment:
**"Deprecated" label for trace-level evals directly contradicts existing FAQ**

`content/faq/all/llm-as-a-judge-migration.mdx` explicitly states: *"Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation."* Labeling trace-level evaluation as **Deprecated** here contradicts that page and will confuse users who read both. The PR description acknowledges this conflict. Both pages will be live simultaneously, so one of them needs to be corrected before this merges — either the FAQ line should be updated or the deprecation label here should be softened to "Legacy".

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Misleading replacement endpoint for traces/{id} and sessions

Both GET /api/public/traces/{id} and GET /api/public/sessions point users to GET /api/public/v2/observations as their replacement. Observations, traces, and sessions are conceptually distinct resources; a user migrating from the sessions list endpoint to an observations list endpoint would get fundamentally different data. If the v4 data model intentionally collapses these, a brief note explaining the conceptual change would reduce confusion — otherwise readers may assume the replacement is a straightforward semantic equivalent. Is there a v2 sessions or traces endpoint planned, or is the intent that users query the observations endpoint and filter by type? A one-line note clarifying the data-model reason for this would help readers understand the migration.

Prompt To Fix With AI

This is a comment left during a code review.
Path: content/docs/compatibility.mdx
Line: 76-77

Comment:
**Misleading replacement endpoint for `traces/{id}` and `sessions`**

Both `GET /api/public/traces/{id}` and `GET /api/public/sessions` point users to `GET /api/public/v2/observations` as their replacement. Observations, traces, and sessions are conceptually distinct resources; a user migrating from the sessions list endpoint to an observations list endpoint would get fundamentally different data. If the v4 data model intentionally collapses these, a brief note explaining the conceptual change would reduce confusion — otherwise readers may assume the replacement is a straightforward semantic equivalent. Is there a v2 sessions or traces endpoint planned, or is the intent that users query the observations endpoint and filter by type? A one-line note clarifying the data-model reason for this would help readers understand the migration.

How can I resolve this? If you propose a fix, please make it concise.

[claude]

🔴 The 'Deprecated' column on line 96 lists trace-level evaluations, but content/faq/all/llm-as-a-judge-migration.mdx line 24 explicitly promises 'Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation.' The compatibility page's own definition on line 92 says deprecated versions 'will be removed' — directly contradicting that promise. Fix by relabeling the column to 'Legacy' / 'Superseded' (matching the FAQ language), or update the FAQ with product sign-off if this really is a deprecation. The PR description already flags this as an unresolved reconciliation.

Extended reasoning...

The contradiction\n\nTwo docs pages shipping together on this repo now make mutually incompatible claims about the lifecycle of trace-level evaluators:\n\n- content/docs/compatibility.mdx:96 places "Trace-level (Python SDK v2+ / JS SDK v3+)" under the Deprecated column of the Evaluations & integrations table.\n- The same file, line 92, defines the Deprecated column's semantics for that section: "Each has a current version (built on the v4 data model) and a deprecated version that still works but will be removed."\n- content/faq/all/llm-as-a-judge-migration.mdx:24 states verbatim: "Trace-level evaluators will continue to work. This is an upgrade path, not a deprecation." The same FAQ reiterates on line 176: "No changes needed—trace-level evaluators will continue to work."\n\nSo the compatibility page tells the reader trace-level evals will be removed; the FAQ tells the reader they will continue to work and are explicitly not a deprecation.\n\nStep-by-step proof of the contradiction\n\n1. A user planning around trace-level evals opens /docs/compatibility (the new page this PR introduces).\n2. They read the Evaluations & integrations intro: "deprecated version … will be removed."\n3. They see "Trace-level (Python SDK v2+ / JS SDK v3+)" in the Deprecated column → they conclude their setup is scheduled for removal.\n4. They open the FAQ linked from the LLM-as-a-Judge docs (/faq/all/llm-as-a-judge-migration) to plan the migration.\n5. Line 24 tells them: "This is an upgrade path, not a deprecation." Line 176 says: "No changes needed—trace-level evaluators will continue to work."\n6. The two statements cannot both be true under the compatibility page's own definitions.\n\nWhy the existing wording doesn't prevent it\n\nThe compatibility page uses "Deprecated" for API endpoints (line 64: "Deprecated endpoints will be removed in a future version") and reuses the same label — with the same removal semantics — for evals in the section intro on line 92. There is no local softening of the label for this specific row. Meanwhile the FAQ deliberately picked the word "Legacy" (see FAQ line 65, "Find evaluators marked 'Legacy'") precisely to avoid the removal connotation. Mixing the two labels across two shipping docs pages is what creates the contradiction.\n\nImpact\n\nThis is externally visible lifecycle guidance on a new reference page. A user relying on trace-level evaluators is left with two incompatible answers to "will my setup keep working?" and could either (a) prematurely rework working evaluators believing removal is imminent, or (b) delay migration because the FAQ reassured them nothing is changing. Either outcome is a real product cost driven by the docs themselves. The PR author acknowledged this in the PR description ("Trace-level evals are shown deprecated, which conflicts with a line in llm-as-a-judge-migration.mdx … that FAQ line likely needs updating for consistency") but left both files in a contradictory state.\n\nHow to fix\n\nDecision needed from the product owner — pick one and apply consistently:\n\n1. Relabel on the compatibility page (recommended, lower risk): change the column header or the trace-level row to use "Legacy" / "Superseded" instead of "Deprecated", matching the FAQ's existing wording, and add a note that trace-level evals continue to work. This preserves the public commitment.\n2. Update the FAQ (only if product genuinely intends removal): revise llm-as-a-judge-migration.mdx lines 24 and 174–177 to acknowledge a real deprecation and, ideally, name a removal window. This is a public-commitment change and should not be made without explicit product sign-off.

[claude]

🔴 The compatibility table marks /api/public/mcp as "v4 (Fast Preview) only" (line 78), but mcp-server.mdx already documents this endpoint as generally available today on Cloud EU/US/Japan/HIPAA and Self-Hosted — no v4 or preview qualifier. Readers of this new canonical reference page will be misled into thinking MCP is unavailable outside the v4 preview. Please reconcile the two pages (e.g. mark MCP as GA for prompt management/existing tools, and call out any specific v4-only tools separately).

Extended reasoning...

The contradiction

content/docs/compatibility.mdx line 78 renders this row in the Read APIs table:

| `/api/public/mcp` | Preview | [MCP server](/docs/api-and-data-platform/features/mcp-server); v4 ([Fast Preview](/docs/v4)) only |

But the linked page — content/docs/api-and-data-platform/features/mcp-server.mdx — documents /api/public/mcp as available today across five environments (lines 29–75):

• Cloud EU: https://cloud.langfuse.com/api/public/mcp
• Cloud US: https://us.cloud.langfuse.com/api/public/mcp
• Cloud Japan: https://jp.cloud.langfuse.com/api/public/mcp
• HIPAA US: https://hipaa.cloud.langfuse.com/api/public/mcp
• Self-Hosted: https://your-domain.com/api/public/mcp (with reverse-proxy guidance and LANGFUSE_MCP_ALLOWED_HOSTS env var)

Nowhere on that page is v4, Fast Preview, or a preview opt-in mentioned as a prerequisite. It is presented as a generally-available capability, and is already the recommended way to do prompt management via MCP on v3 self-hosted deployments today.

Why this misleads readers

The compatibility page is a new canonical reference that this same PR cross-links from three other places (SDK overview, self-hosting versioning, and the compatibility FAQ). A reader on v3 self-hosted who is already using /api/public/mcp for prompt management, or evaluating adopting it, will land on this table and reasonably conclude they need to opt into v4 Fast Preview first. That is not true for the currently-documented MCP surface.

Step-by-step proof

1. A v3 self-hosted user reads the new compatibility FAQ addition and clicks through to /docs/compatibility.
2. They scan the Read APIs table and see /api/public/mcp marked "Preview" with the qualifier "v4 (Fast Preview) only."
3. They click the inline link to /docs/api-and-data-platform/features/mcp-server.
4. That page shows a Self-Hosted tab with a working configuration, no mention of v4 or preview flags, and links to Prompt Management with MCP as an existing use case.
5. The two pages contradict each other; the reader either (a) doesn't try MCP because they trust the compatibility table, or (b) tries it, it works, and is confused about which page is correct.

The author flagged this

The PR description explicitly calls this out under "Notes for reviewers": "The /docs/v4 MCP note says 'v4 only'; the existing mcp-server.mdx says the MCP server is available today for prompt management — may need reconciling." So this is a known unresolved gap in the PR as submitted.

Suggested fix

Update the compatibility row to reflect actual availability. Two reasonable options:

• Drop the "v4 only" qualifier: /api/public/mcp | GA | MCP server (simplest, matches mcp-server.mdx today).
• Or split the story if some tools really are v4-gated: mark the endpoint GA, and add a note that certain newer tools (name them) require v4 Fast Preview.

[claude]

🔴 The new compatibility page contradicts itself and other docs about v4 self-hosted availability. The Read APIs table (lines 68, 71) and bullet at line 80 tell self-hosted operators they can enable v2 Observations/Metrics via a preview opt-in and env var LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN, but the Server versions row (line 49) marks v4 as "Cloud-only preview" and the bullet at line 81 tells them to "use the legacy observations and metrics resources until their v2 APIs are GA there". The env var also appears nowhere else in the repo (not in the self-hosting configuration reference, not in /docs/v4, not in any changelog), and /docs/v4 line 146 explicitly states the OSS migration path is still being worked on. Please either drop the "self-hosted via the v4 preview opt-in" notes and the env var reference (aligning with the /docs/v4 stance), or document the opt-in path in /docs/v4 and the self-hosting config surface.

Extended reasoning...

What the bug is

The new content/docs/compatibility.mdx page contains internally contradictory guidance about whether the v4 Observations/Metrics v2 APIs are available on self-hosted deployments today, and it references an env variable (LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN) that is not documented anywhere else in the repository.

Where the contradictions live

On the same page:

• Line 49 (Server versions table): v4 (Fast Preview) | ... Cloud-only preview.
• Line 68 (Read APIs table): GET /api/public/v2/observations | Current | Cloud (GA); self-hosted via the v4 preview opt-in
• Line 71 (Read APIs table): same phrasing for GET /api/public/v2/metrics.
• Line 80 (bullet): Self-hosted Observations/Metrics v2 require the v4 preview opt-in (\LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN`).`
• Line 81 (bullet): On self-hosted, use the legacy observations and metrics resources until their v2 APIs are GA there.

Lines 49 and 81 say self-hosted has no v2 API access today; lines 68, 71, and 80 say it does via an opt-in env var. Both cannot be right.

Cross-referencing other docs

content/docs/v4.mdx lines 144–146 ("OSS and self-hosting") explicitly says: "This preview is currently available on Langfuse Cloud. We are working on the migration path for OSS deployments and will share updates here, in the changelog, and in the dedicated GitHub Discussion as they become available." This confirms there is no self-hosted opt-in path today.

content/docs/api-and-data-platform/features/observations-api.mdx line 25 similarly states: "Cloud-only: The v2 Observations API is only available on Langfuse Cloud."

The phantom env variable

A repo-wide grep for LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN (and MIGRATION_V4 / PREVIEW_OPT_IN variants) returns exactly one file: the new compatibility.mdx. It is not in the self-hosting configuration reference (content/self-hosting/configuration/index.mdx), not in /docs/v4, and not in any changelog.

Step-by-step proof of impact

1. A self-hosted operator lands on /docs/compatibility (linked from the SDK overview, self-hosting versioning page, and the compatibility FAQ).
2. They read the Read APIs table and see v2/observations is "Cloud (GA); self-hosted via the v4 preview opt-in".
3. They read the bullet on line 80 and try to set LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN on their deployment.
4. They search the self-hosting configuration reference and /docs/v4 for how to configure this variable, find nothing, and get blocked.
5. Alternatively they read line 81 or the "Cloud-only preview" row on line 49 and are left uncertain which statement is correct.

How to fix

Either:

• Drop the two "self-hosted via the v4 preview opt-in" notes from the Read APIs table rows and remove the bullet on line 80 (aligning with the "Cloud-only preview" row and /docs/v4); or
• If the opt-in path is real and about to ship, document LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN alongside /docs/v4 and in the self-hosting configuration reference before merging this page.

[claude]

🟡 The self-hosting requirements callout still names Python SDK v3 and TypeScript SDK v4 as if current, but the top of this same file (lines 17–18) and the new /docs/compatibility page identify Python v4 / JS-TS v5 as current. The numeric minimums (≥ 3.125.0 and ≥ 3.95.0) happen to match v4/v5 too, so the copy is out of date rather than wrong — but since this PR now cross-links this callout to a page that visibly lists v4/v5, a one-line update to say "Python SDK v4" / "JS-TS SDK v5" (or drop the version-specific sentence in favor of the new compatibility link) would remove the mismatch. Pre-existing copy — not a merge blocker.

Extended reasoning...

What the bug is. In content/docs/observability/sdk/overview.mdx, the <Details>Requirements for self-hosted Langfuse</Details> callout at lines 40–44 reads: "the Python SDK v3 requires Langfuse platform version ≥ 3.125.0 and the TypeScript SDK v4 requires Langfuse platform version ≥ 3.95.0". But the file's own header at lines 17–18 advertises Python SDK v4 and JS/TS SDK v5 as the SDKs to install, and the second <Details> block right below ("Legacy documentation") explicitly labels Python v3 and TypeScript v4 as legacy. So the same file, within a ~40-line window, both calls v3/v4 legacy and names them in an active self-hosting requirement.\n\nWhy the PR now surfaces this. The PR adds a new line inside this exact callout: "See the full versions & compatibility overview …". The linked page's SDK↔server matrix lists Python v4 and JS/TS v5 as GA / current and Python v3 / JS-TS v4 as Legacy. So a reader who follows the newly-added link immediately sees v4/v5 as current, then looks back at the sentence above the link and sees only v3/v4 named. The PR made the mismatch more visible without fixing the underlying stale copy.\n\nWhy it's not factually wrong (just stale). Per the new compatibility.mdx, Python SDK v4 shares the same ≥ 3.125.0 minimum as v3, and JS/TS v5 shares the same ≥ 3.95.0 minimum as v4. So the numbers still hold for a self-hoster on the current SDKs — the requirement bound is correct. The problem is framing: someone reading this on Python v4 or JS-TS v5 does not see their major called out at all, and has to infer that the constraint stated for the legacy version transfers to them.\n\nImpact. Low. A self-hoster on the current SDKs might briefly wonder whether the requirement applies to them, then follow the new /docs/compatibility link and confirm it does. Nothing breaks; the constraint is preserved. This is a documentation polish issue, not a correctness issue — hence nit severity.\n\nStep-by-step proof.\n1. Open content/docs/observability/sdk/overview.mdx line 17: "Python SDK v4".\n2. Line 18: "JS/TS SDK v5".\n3. Line 40 (inside <Details>Requirements for self-hosted Langfuse</Details>): "the Python SDK v3 requires Langfuse platform version ≥ 3.125.0 and the TypeScript SDK v4 requires Langfuse platform version ≥ 3.95.0".\n4. Line 42 (added by this PR): "See the full versions & compatibility overview …".\n5. Open content/docs/compatibility.mdx — the "SDK ↔ server compatibility" table lists Python SDK v4 → GA / ≥ 3.125.0, Python SDK v3 → Legacy, JS/TS SDK v5 → GA / ≥ 3.95.0, JS/TS SDK v4 → Legacy.\n6. Result: the callout the PR just cross-linked names only the legacy majors as if they were current.\n\nHow to fix. Either (a) update the sentence to "the Python SDK v4 requires Langfuse platform version ≥ 3.125.0 and the JS/TS SDK v5 requires Langfuse platform version ≥ 3.95.0", or (b) drop the version-specific sentence entirely and let the newly added /docs/compatibility link carry the details (that page already lists both current and legacy majors with their minimums). Option (b) also removes the need to keep two places in sync going forward.\n\nSeverity. Nit — pre-existing copy the PR only touches to append a link. Numeric constraint is still accurate; only the version-name framing is out of date. Not a merge blocker.