feat(api): update API spec from langfuse/langfuse 43a10b5

[langfuse-bot]

Greptile Summary

This PR updates JSDoc comments on the Sessions API client to add deprecation guidance for both list() and get(), pointing developers toward the v2 observations endpoint for new data-extraction workflows. The change is documentation-only and was generated from the upstream langfuse/langfuse spec at commit 43a10b5.

• The list() doc now labels the sessions endpoint as "legacy" and recommends grouping v2 observation rows by sessionId, but that endpoint returns observation records — not session metadata — so callers would silently lose session-level fields if they followed this migration path literally.
• The get() doc replaces the concrete GET /api/public/traces?sessionId=<id> example with a v2 observations URL using an opaque filter=<sessionId filter> placeholder, leaving the required filter format undocumented.

Confidence Score: 4/5

Safe to merge — no runtime code is changed, only JSDoc comments are updated.

The two updated doc blocks recommend a v2 observations endpoint as the migration target, but that endpoint returns individual observation rows rather than session-level records, so the guidance for list() could mislead callers into losing session metadata. The get() alternative also leaves the filter parameter format unspecified. Both are documentation accuracy issues with no impact on compiled behaviour.

packages/core/src/api/api/resources/sessions/client/Client.ts — the new deprecation guidance in JSDoc may mislead callers about data equivalence with the suggested v2 alternative.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Dev as Developer
    participant Sessions as GET /api/public/sessions (legacy)
    participant V2Obs as GET /api/public/v2/observations

    Note over Dev: Existing flow (list)
    Dev->>Sessions: list() — returns session metadata
    Sessions-->>Dev: "{sessions: [{id, createdAt, bookmarked, ...}]}"

    Note over Dev: Suggested migration (list)
    Dev->>V2Obs: "?fromStartTime=..&toStartTime=.."
    V2Obs-->>Dev: "{observations: [{sessionId, ...}]}"
    Note over Dev: Group by sessionId client-side (session-level metadata not present)

    Note over Dev: Existing flow (get)
    Dev->>Sessions: get(sessionId) — returns session + traces
    Sessions-->>Dev: "{id, traces: [...]}"

    Note over Dev: Suggested migration (get)
    Dev->>V2Obs: "?filter=<sessionId filter>&fromStartTime=..&toStartTime=.."
    V2Obs-->>Dev: "{observations: [{sessionId, ...}]}"

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"}}}%%
sequenceDiagram
    participant Dev as Developer
    participant Sessions as GET /api/public/sessions (legacy)
    participant V2Obs as GET /api/public/v2/observations

    Note over Dev: Existing flow (list)
    Dev->>Sessions: list() — returns session metadata
    Sessions-->>Dev: "{sessions: [{id, createdAt, bookmarked, ...}]}"

    Note over Dev: Suggested migration (list)
    Dev->>V2Obs: "?fromStartTime=..&toStartTime=.."
    V2Obs-->>Dev: "{observations: [{sessionId, ...}]}"
    Note over Dev: Group by sessionId client-side (session-level metadata not present)

    Note over Dev: Existing flow (get)
    Dev->>Sessions: get(sessionId) — returns session + traces
    Sessions-->>Dev: "{id, traces: [...]}"

    Note over Dev: Suggested migration (get)
    Dev->>V2Obs: "?filter=<sessionId filter>&fromStartTime=..&toStartTime=.."
    V2Obs-->>Dev: "{observations: [{sessionId, ...}]}"

Loading

Prompt To Fix All With AI

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

---

### Issue 1 of 2
packages/core/src/api/api/resources/sessions/client/Client.ts:66-69
**Suggested alternative returns observations, not sessions**

The replacement workflow (`v2/observations` grouped by `sessionId`) returns individual observation rows, not session-level records. The existing `list()` endpoint returns session metadata (e.g. `createdAt`, `bookmarked`, user-level aggregates) that do not exist on observations. Callers who follow this guidance to migrate will silently lose that data, or will need to perform additional joins themselves that aren't mentioned here.

### Issue 2 of 2
packages/core/src/api/api/resources/sessions/client/Client.ts:222-224
**Vague `filter` placeholder in suggested alternative**

The replacement URL uses `filter=<sessionId filter>` without specifying the exact wire format. The v2 observations endpoint likely expects a structured or JSON-encoded filter value (e.g. `[{"column":"sessionId","operator":"=","value":"<id>"}]`), and a developer reading only this comment won't know how to construct it. The original wording (`GET /api/public/traces?sessionId=<sessionId>`) was immediately actionable; the new suggestion requires knowing the undocumented filter schema to be equally useful.

_{Reviews (1): Last reviewed commit: "feat(api): update API spec from langfuse..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
langfuse-js	Ready	Preview	Jun 18, 2026 3:50pm

[github-actions]

@claude review

[claude]

LGTM — doc-only update to auto-generated client.

Extended reasoning...

Overview

This PR is a Fern auto-generated update to a single file: packages/core/src/api/api/resources/sessions/client/Client.ts. The diff only modifies two JSDoc comment blocks on list() and get() to recommend the v2 observations endpoint for new data extraction workflows. There are no changes to types, signatures, request construction, error handling, or runtime behavior.

Security risks

None. Comments do not affect execution. No new URLs are constructed in code from these strings; the example URLs only appear in JSDoc.

Level of scrutiny

Minimal. This is a documentation-only change in an auto-generated file (header explicitly notes "auto-generated by Fern"). The PR title also matches the typical feat(api): update API spec from langfuse/langfuse <sha> pattern used for spec syncs.

Other factors

No reviewer comments to address. Bug hunting system found nothing. The change is mechanical and self-contained.

[greptile-apps]

Suggested alternative returns observations, not sessions

The replacement workflow (v2/observations grouped by sessionId) returns individual observation rows, not session-level records. The existing list() endpoint returns session metadata (e.g. createdAt, bookmarked, user-level aggregates) that do not exist on observations. Callers who follow this guidance to migrate will silently lose that data, or will need to perform additional joins themselves that aren't mentioned here.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/core/src/api/api/resources/sessions/client/Client.ts
Line: 66-69

Comment:
**Suggested alternative returns observations, not sessions**

The replacement workflow (`v2/observations` grouped by `sessionId`) returns individual observation rows, not session-level records. The existing `list()` endpoint returns session metadata (e.g. `createdAt`, `bookmarked`, user-level aggregates) that do not exist on observations. Callers who follow this guidance to migrate will silently lose that data, or will need to perform additional joins themselves that aren't mentioned here.

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