feat(api): update API spec from langfuse/langfuse b8db8b6

[langfuse-bot]

Greptile Summary

This is an auto-generated API spec sync (from langfuse/langfuse b8db8b6) that updates docstrings across blob-storage integration, dataset-item, scores v1/v3 clients — no functional Python logic changes are included.

• Blob storage integrations: exportFieldGroups now documented as applying to all export sources (previously excluded from LEGACY_TRACES_OBSERVATIONS); a new integration-level deprecation gate (effective 2026-06-22) prohibits creating new integrations with legacy export sources on Cloud.
• Dataset items: id field docstring gains a 255-character cap that is not enforced by a Pydantic max_length constraint, so violations only surface as server errors.
• Scores v1: Deprecation notices added pointing callers to v3; Scores v3: core removed from the "Allowed" field-group list while the HTTP 400 warning for unknown names is retained, which could silently break callers passing fields="core".

Confidence Score: 3/5

Mostly documentation changes, but two spots deserve attention before merging: the fields allowed-values change in scores_v3 may break existing callers, and the response-shape change for LEGACY_TRACES_OBSERVATIONS in the blob storage integration response type removes a previously guaranteed null without explaining what replaces it.

The removal of core from the allowed fields list in scores_v3, combined with the retained "unknown names return HTTP 400" warning, creates a plausible regression for any caller that was explicitly requesting fields="core". The blob storage exportFieldGroups response docstring strips the null-for-legacy-source guarantee without clarifying the new shape, which could confuse code that branches on None. Both issues stem from behavioral API changes that are only surfaced through docstring updates.

langfuse/api/scores_v3/client.py and raw_client.py (the fields allowed-values change), and langfuse/api/blob_storage_integrations/types/blob_storage_integration_response.py (the missing null/empty-list clarification).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Create Blob Storage Integration] --> B{Cloud or Self-hosted?}
    B -->|Self-hosted| C[exportSource omitted → LEGACY_TRACES_OBSERVATIONS]
    B -->|Langfuse Cloud| D{exportSource provided?}
    D -->|Omitted| E[Default to OBSERVATIONS_V2]
    D -->|LEGACY_TRACES_OBSERVATIONS or LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS| F{Project created before 2026-05-20?}
    F -->|Yes| G{Integration created before 2026-06-22?}
    F -->|No| H[HTTP 400 — use OBSERVATIONS_V2]
    G -->|Yes — existing integration| I[Accepted]
    G -->|No — new integration| J[HTTP 400 — use OBSERVATIONS_V2]
    D -->|OBSERVATIONS_V2| K[Accepted]
    K --> L{exportFieldGroups provided?}
    I --> L
    C --> L
    E --> L
    L -->|Yes, must include core| M[Export selected field groups]
    L -->|Omitted| N[Export all groups by default]

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
langfuse/api/scores_v3/client.py:80-81
**Potential breaking change: `core` removed from allowed `fields` values**

The previous spec listed `"core"` as an allowed field group value ("Allowed: core, details, subject, annotation"). The new description removes it, listing only `details, subject, annotation`, while keeping the statement "Unknown group names return HTTP 400". Any caller currently passing `fields="core"` (as was recommended by the old default-of-`"core"` language) could now receive an HTTP 400 from the server. The same change is mirrored in `raw_client.py` and their async variants. Is there a server-side migration path or is `"core"` silently accepted as a no-op?

### Issue 2 of 3
langfuse/api/dataset_items/types/create_dataset_item_request.py:25-28
**`id` max-length constraint documented but not validated client-side**

The docstring now says the `id` field "must be at most 255 characters", but the Pydantic field declaration (`pydantic.Field(default=None)`) has no `max_length=255` constraint. A caller who supplies a 300-character ID will pass client-side validation and only get a server-side error. Adding `pydantic.Field(default=None, max_length=255)` would provide earlier, friendlier feedback — though since this file is auto-generated from the Fern spec, the fix may need to propagate from the API definition instead.

### Issue 3 of 3
langfuse/api/blob_storage_integrations/types/blob_storage_integration_response.py:133-135
**Response shape for `LEGACY_TRACES_OBSERVATIONS` is now undocumented**

The old docstring explicitly stated that `exportFieldGroups` is "always `null` when exportSource is `LEGACY_TRACES_OBSERVATIONS`". The replacement text ("An empty list is treated as all groups during export") omits any mention of what callers should expect when the source is `LEGACY_TRACES_OBSERVATIONS`. If the response shape has actually changed (e.g., null → empty list), deserialisation code that checked for `None` to detect the legacy source will silently misbehave.

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

Greptile also left 2 inline comments on this PR.

[github-actions]

@claude review

[claude]

LGTM — auto-generated API spec sync, docstring-only changes.

Extended reasoning...

Overview

This PR is an automated Fern-generated API spec sync from langfuse/langfuse at commit b8db8b6, touching 13 auto-generated client files under langfuse/api/. All changes are docstring/comment updates: clarifying the blob storage export source deprecation gates (adding a new 2026-06-22 integration-level gate and noting cloud defaults to OBSERVATIONS_V2), broadening exportFieldGroups to apply to all export sources, adding a 255-char limit note to dataset item id, marking the v2 scores endpoints as deprecated in favor of v3, and expanding the v3 scores fields parameter documentation.

Security risks

None. No executable code paths, request shapes, or auth logic are modified — only docstrings and class-level descriptions in auto-generated Fern files. The HTTP request bodies, URL paths, and parameter serialization are unchanged.

Level of scrutiny

Minimal. These are auto-generated SDK files that mirror an upstream OpenAPI/Fern spec; the project does not own this code by convention, and any behavioral changes happen server-side at langfuse/langfuse. The only thing to verify is that the diff is in fact docstring-only, which it is.

Other factors

No bugs reported by the bug hunting system. No outstanding human reviewer comments. The PR follows the established pattern of feat(api): update API spec from langfuse/langfuse <sha> commits that have been routinely merged in this repo. Safe to shadow-approve.

[marliessophie]

@niklassemmler could you please take a look at the changes in this PR?

Context: as stated in contributing guide: whenever we change our API documentation, we use fern to generate our python and typescript clients. The langfuse-bot opens PRs in the repos respectively.

As the diff in this PR is much larger than my docs change to POST /dataset-item API, I'd appreciate if you take a look. Thanks!

Same question applies to JS PR: langfuse/langfuse-js#831

[niklassemmler]

@niklassemmler could you please take a look at the changes in this PR?

Context: as stated in contributing guide: whenever we change our API documentation, we use fern to generate our python and typescript clients. The langfuse-bot opens PRs in the repos respectively.

As the diff in this PR is much larger than my docs change to POST /dataset-item API, I'd appreciate if you take a look. Thanks!

Same question applies to JS PR: langfuse/langfuse-js#831

Sure will do

[niklassemmler]

Context: as stated in contributing guide: [...] The langfuse-bot opens PRs in the repos respectively.

Where is this stated in the doc? I see no reference to updating the SDK repos.

[niklassemmler]

@marliessophie I approved my changes, do you want to approve yours?