docs(api): fold Observations API into Public API page#3056
docs(api): fold Observations API into Public API page#3056Lotte-Verheyden wants to merge 2 commits into
Conversation
Remove the standalone Observations API docs page and consolidate its conceptual overview into the Public API page under a new `#observations-api` section. Reference content (field groups, parameters, sample responses) now links out to the external API reference instead of being duplicated in docs. Add a redirect for the old URL and repoint all inbound links, and correct the v2/v1 Observations API reference URLs.
dosubot
Bot
added
the
size:L
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@claude review |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs-only restructure with mechanical link repointing and a redirect; the inline nit on FAQ link text is minor.
Extended reasoning...
Overview
This PR folds the standalone Observations API docs page into the Public API page, adds a redirect from the old URL to the new anchor, and mechanically repoints inbound links across 17 files (changelogs, blog posts, FAQ, marketing, SDK query guide, overview tables, metrics-api, v4 page, and one launch-week landing component). It also corrects two external API reference URLs to #tag/observations (v2) and #tag/legacyobservationsv1 (v1).
Security risks
None — this is documentation-only content with no code paths, auth, or data handling. The only non-content change is a redirect entry in lib/redirects.js mapping the old observations-api URL to the new anchored Public API URL, which follows the existing mainDocsReorder202507 pattern.
Level of scrutiny
Low. The scope is mechanical link substitution plus a small new section composed of summarized prose already present in the deleted file. The author verified the prettier/H1 checks and confirmed the redirect resolves and repointed pages render. None of the changed files are owned by code-only CODEOWNERS.
Other factors
One nit-level bug was flagged inline: the FAQ "Observations API v2 upgrade guidance" link text on content/faq/all/api-524-http-errors.mdx no longer matches the destination, because the dedicated v1→v2 endpoint replacement table was removed along with the standalone page. The link still resolves (the redirect handles it and an unmatched fragment is harmless) but the descriptive text overpromises. This is content-quality only and easy to fix in a follow-up; it does not block the structural cleanup.
Reintroduce the legacy trace/observation read migration mapping on the Public API page inside a collapsible accordion so it stays available (the FAQ 524-errors page links to it as upgrade guidance) without adding visual weight to the Observations API overview.
There was a problem hiding this comment.
Prior concern about the FAQ "upgrade guidance" link text is now addressed by the restored migration-table collapsible on the public-api page.
Extended reasoning...
Overview
This PR folds the standalone Observations API docs page (observations-api.mdx) into a new ### Observations API section on the Public API page, deletes the old file, adds a redirect, and repoints all 18 inbound links (changelogs, blog posts, FAQ, marketing, SDK docs, v4 page, overview, metrics-api, launch-week component). It also corrects the API reference anchors to #tag/observations (v2) and #tag/legacyobservationsv1 (v1).
Security risks
None — documentation-only changes. No runtime code paths, auth, crypto, or data flows are touched. The only non-content change is one entry added to the mainDocsReorder202507 block in lib/redirects.js, which is a permanent path-only redirect.
Level of scrutiny
Light. This is a documentation restructure with no logic changes. The PR is large (size:L) but mechanical: the same URL substitution applied across 18 files. The redirect is correctly placed within the existing permanent-redirects array (which the file comments note is append-only).
Other factors
My prior review flagged that the FAQ links text "Observations API v2 upgrade guidance" no longer matched the destination content because the v1→v2 migration table had been dropped. The follow-up commit ba22d3b restored that table in a collapsible Accordion under the upgrade-from-older-reads anchor on public-api.mdx, so the FAQ link text now matches what readers find at the destination.
The remaining inline bug is a separate minor nit on content/changelog/2026-05-15-v2-observations-trace-context.mdx: its prose still says "The full table is in the [Observations API v2 docs]" referring to the field-groups table (not the migration table), which is not present on the destination after this restructure. It's classified as a nit and the fix is a one-line prose tweak. Not blocking for approval.
| - **Render trace names** in an analytics view that paginates observations. | ||
|
|
||
| `trace_context` joins the existing groups (`core`, `basic`, `time`, `io`, `metadata`, `model`, `usage`, `prompt`, `metrics`) on the v2 endpoint. The full table is in the [Observations API v2 docs](/docs/api-and-data-platform/features/observations-api#v2). | ||
| `trace_context` joins the existing groups (`core`, `basic`, `time`, `io`, `metadata`, `model`, `usage`, `prompt`, `metrics`) on the v2 endpoint. The full table is in the [Observations API v2 docs](/docs/api-and-data-platform/features/public-api#observations-api). |
There was a problem hiding this comment.
🟡 The trace-context changelog at line 28 promises The full table is in the [Observations API v2 docs](/docs/api-and-data-platform/features/public-api#observations-api), but after this PR the destination section in public-api.mdx no longer contains a field-groups table — it only mentions "selective field retrieval" in one sentence and the only table in that section is the v1→v2 endpoint migration table. The follow-up sentence (usagePricingTierName also moved from trace_context to the usage group) likewise has no on-site reference. Fix by repointing the link to the external API reference (https://api.reference.langfuse.com/#tag/observations), restoring the field-groups table in another collapsible Accordion next to the migration table, or dropping the "full table" phrasing.
Extended reasoning...
What the bug is
The May 15 changelog content/changelog/2026-05-15-v2-observations-trace-context.mdx at line 28 reads:
trace_contextjoins the existing groups (core,basic,time,io,metadata,model,usage,prompt,metrics) on the v2 endpoint. The full table is in the Observations API v2 docs.
Before this PR that link resolved to the standalone observations-api.mdx page, which had an "Available Field Groups" markdown table enumerating every group (core, basic, time, io, metadata, model, usage, prompt, metrics, trace_context) and the fields each contains — exactly the "full table" the prose promises.
What the destination looks like after this PR
observations-api.mdx is deleted. The replacement ### Observations API [#observations-api] section folded into content/docs/api-and-data-platform/features/public-api.mdx (lines 244–291) contains: a one-paragraph intro; a single sentence at line 248 mentioning "selective field retrieval" without enumerating any groups; a collapsible Accordion whose only table is the v1→v2 endpoint migration table (columns: "Existing usage" / "Recommended replacement"); a Cloud-only/data-availability Callout; and links to the external API reference. Grepping the file for Field Groups, field group, trace_context, or usagePricingTierName returns only the single intro match at line 248.
Why this matters
The link itself still resolves (the redirect in lib/redirects.js and the new anchor are wired up correctly), but the destination does not contain the promised content. The follow-up sentence in the same changelog — usagePricingTierName also moved from trace_context to the usage group — depends on the field-groups table for a reader to verify which fields belong to which group. With the table removed and not relocated, the reader has no on-site reference and must navigate out to api.reference.langfuse.com to verify either claim.
Why existing code doesn't prevent it
There is no broken-link check that catches mismatches between prose promises and destination content; the URL resolves cleanly. This is the same class of issue as the existing PR review comment on content/faq/all/api-524-http-errors.mdx (link text promises content that no longer lives on the destination), but at a separate location not covered by that comment, so it is not a duplicate.
Step-by-step proof
- Open the changelog after this PR: line 28 promises
The full table is in the [Observations API v2 docs](/docs/api-and-data-platform/features/public-api#observations-api). - Open the destination
content/docs/api-and-data-platform/features/public-api.mdx, scroll to### Observations API [#observations-api](line 244). Read through line 291: intro paragraph, "selective field retrieval" sentence (line 248, no enumeration), Accordion containing the v1→v2 migration table only, Cloud-only Callout, and external API reference links. - Grep the file for
Field Groups|field group|trace_context|usagePricingTierName: only one hit, at line 248 (the intro paragraph). No enumeration, no table, no mention oftrace_contextorusagePricingTierName. - Conclusion: the changelog promises a "full table" the destination does not contain.
How to fix
Pick the cheapest option:
- Rewrite the prose on line 28 to drop "The full table is in the …" and instead point to the external API reference, e.g. "See the Observations API v2 reference for the full field-group schema."
- Restore the table to
public-api.mdxinside another collapsible Accordion next to the existing migration table, then keep the changelog link as-is. - Repoint the link in the changelog to
https://api.reference.langfuse.com/#tag/observations, where the field-group schema is documented.
1 participant
Summary
The standalone Observations API docs page mixed conceptual framing with exhaustive reference content. This restructures it per the principle that reference belongs in the external API reference, and one topic gets one canonical docs page.
content/docs/api-and-data-platform/features/observations-api.mdx.### Observations API [#observations-api]section: what it returns, summary-level v2 highlights (selective field retrieval, cursor pagination), the Cloud-only and data-availability caveats, and the Metrics API cross-link. The field-group/parameters tables, sample response, and curl examples are dropped in favor of links to the external API reference./docs/api-and-data-platform/features/public-api#observations-api.canonical:frontmatter of the v2 API changelog.#tag/observations(v2) and#tag/legacyobservationsv1(v1).Verification
format:checkand the H1 check pass.Greptile Summary
This PR folds the standalone Observations API docs page into the Public API page as a concise
### Observations API [#observations-api]section, drops the detailed field-group tables, sample responses, and curl examples in favour of links to the external API reference, and plumbs in a permanent redirect and repoints all 18 inbound links.public-api.mdxcovers the v2/v1 overview, cloud-only and data-availability caveats, and API reference links — matching the stated "overview-level only" intent.lib/redirects.jsadds a path-only permanent redirect (no fragment needed on the source since browsers strip fragments before the HTTP request); all previously fragment-based old links (#v2,#upgrade-from-older-reads) will correctly land at#observations-api.#tag/observationsfor v2 and#tag/legacyobservationsv1for v1.Confidence Score: 4/5
Safe to merge — purely a documentation restructuring with no runtime code changes; the redirect and link repointing look complete and correct.
The restructuring is thorough and consistent across all 18 changed files. The one minor concern is that two links in the FAQ 524-errors page keep the anchor text "upgrade guidance" but now point to a general overview section where the specific migration table no longer lives, which could slightly mislead readers who followed the old link for concrete upgrade steps.
content/faq/all/api-524-http-errors.mdx — the "upgrade guidance" link text no longer matches the destination content.
Flowchart
%%{init: {'theme': 'neutral'}}%% flowchart TD A["Old URL\n/docs/api-and-data-platform/\nfeatures/observations-api\n(#v2, #upgrade-from-older-reads, etc.)"] -->|"308 Permanent Redirect\n(lib/redirects.js)"| B["New URL\n/docs/api-and-data-platform/\nfeatures/public-api#observations-api"] C["All inbound links\n(changelogs, blog posts,\nFAQ, marketing, SDK docs,\nv4 page, overview)"] -->|"Repointed directly"| B B --> D["### Observations API section\nin public-api.mdx\n• v2 overview & caveats\n• Links to API reference"] D --> E["v2 API Reference\napi.reference.langfuse.com\n#tag/observations"] D --> F["v1 API Reference\napi.reference.langfuse.com\n#tag/legacyobservationsv1"]Prompt To Fix All With AI
Reviews (1): Last reviewed commit: "docs(api): fold Observations API into Pu..." | Re-trigger Greptile