feat(api): update API spec from langfuse/langfuse 8cdf8a4

[langfuse-bot]

Greptile Summary

This auto-generated API spec sync adds media reference support for dataset items and makes trace_id optional on the media upload URL endpoint to support dataset item media uploads alongside trace/observation uploads.

• New types: DatasetItemMediaReference, DatasetItemMediaReferenceField, and DatasetItemMediaReferenceMedia are introduced; DatasetItem gains a required media_references field pointing to resolved media records found in input, expectedOutput, and metadata.
• get_upload_url signature change: trace_id becomes optional and two new optional params (dataset_id, dataset_item_id) are added, allowing callers to associate media with a dataset item instead of a trace.
• Sessions docstrings: list and get endpoints now recommend the v2 observations endpoint for new data-extraction workflows.

Confidence Score: 3/5

The media upload signature change and new types are safe, but the required media_references field on DatasetItem will break deserialization for any user whose server has not yet been updated to return mediaReferences.

The core concern is media_references being a required field with no default in DatasetItem. Any SDK user who upgrades the Python client before upgrading their server will get a Pydantic ValidationError on every DatasetItem response, effectively making the SDK unusable for dataset operations. The get_upload_url signature change is cleanly backward-compatible, and the new type files are well-structured.

langfuse/api/commons/types/dataset_item.py — the required media_references field warrants a second look to confirm the server guarantees this field in all responses before this SDK version ships.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client as Python SDK Client
    participant Server as Langfuse Server

    Note over Client,Server: Dataset Item Media Upload (new path)
    Client->>Server: POST /api/public/media (datasetId, datasetItemId, field, contentType, ...)
    Server-->>Client: GetMediaUploadUrlResponse (presigned URL)
    Client->>Server: PUT presigned URL (media bytes)

    Note over Client,Server: Fetch Dataset Item with Media References
    Client->>Server: "GET /api/public/dataset-items/{id}"
    Server-->>Client: "DatasetItem { ..., mediaReferences: [{ field, referenceString, jsonPath, media: { mediaId, url, urlExpiry } }] }"
    Client->>Client: Parse DatasetItem (media_references now required field)

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 Client as Python SDK Client
    participant Server as Langfuse Server

    Note over Client,Server: Dataset Item Media Upload (new path)
    Client->>Server: POST /api/public/media (datasetId, datasetItemId, field, contentType, ...)
    Server-->>Client: GetMediaUploadUrlResponse (presigned URL)
    Client->>Server: PUT presigned URL (media bytes)

    Note over Client,Server: Fetch Dataset Item with Media References
    Client->>Server: "GET /api/public/dataset-items/{id}"
    Server-->>Client: "DatasetItem { ..., mediaReferences: [{ field, referenceString, jsonPath, media: { mediaId, url, urlExpiry } }] }"
    Client->>Client: Parse DatasetItem (media_references now required field)

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
langfuse/api/commons/types/dataset_item.py:56-61
**Required field with no default breaks older-server compatibility**

`media_references` is declared as a required `List[DatasetItemMediaReference]` with `pydantic.Field()` (no default). If any server instance being talked to hasn't yet been updated to include `mediaReferences` in its `DatasetItem` responses, every call that deserializes a `DatasetItem` will raise a Pydantic `ValidationError`. This affects all SDK users who upgrade the Python client before upgrading their server. Consider using `pydantic.Field(default_factory=list)` or typing it as `Optional[List[DatasetItemMediaReference]]` with `default=None` so the field degrades gracefully on older responses.

### Issue 2 of 2
langfuse/api/commons/types/dataset_item_media_reference_field.py:16-26
**`visit()` silently returns `None` on unknown enum values**

The `visit()` method uses three `if self is ...` branches with no `else` or `raise`. If the server returns a new field value not yet present in this SDK version (forward-compatibility scenario), none of the branches match and the method returns `None` implicitly — while the return annotation promises `T_Result`. Callers will get a `None` typed as `T_Result` and may encounter a `TypeError` or silent data corruption well after the call site.

_{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