feat(api): update API spec from langfuse/langfuse 966662e (#1508)

* feat(api): update API spec from langfuse/langfuse 966662e

* chore: support dataset versioning via SDK

* chore: support dataset versioning via SDK

---------

Co-authored-by: langfuse-bot <langfuse-bot@langfuse.com>
Co-authored-by: Marlies Mayerhofer <74332854+marliessophie@users.noreply.github.com>

Author: 3 people

langfuse/_client/client.py

@@ -2442,13 +2442,20 @@ def get_trace_url(self, *, trace_id: Optional[str] = None) -> Optional[str]:
         )
 
     def get_dataset(
-        self, name: str, *, fetch_items_page_size: Optional[int] = 50
+        self,
+        name: str,
+        *,
+        fetch_items_page_size: Optional[int] = 50,
+        version: Optional[datetime] = None,
     ) -> "DatasetClient":
         """Fetch a dataset by its name.
 
         Args:
             name (str): The name of the dataset to fetch.
             fetch_items_page_size (Optional[int]): All items of the dataset will be fetched in chunks of this size. Defaults to 50.
+            version (Optional[datetime]): Retrieve dataset items as they existed at this specific point in time (UTC).
+                If provided, returns the state of items at the specified UTC timestamp.
+                If not provided, returns the latest version. Must be a timezone-aware datetime object in UTC.
 
         Returns:
             DatasetClient: The dataset with the given name.
@@ -2465,6 +2472,7 @@ def get_dataset(
                     dataset_name=self._url_encode(name, is_url_param=True),
                     page=page,
                     limit=fetch_items_page_size,
+                    version=version,
                 )
                 dataset_items.extend(new_items.data)
 

langfuse/api/__init__.py

@@ -36,6 +36,7 @@
     Comment,
     CommentObjectType,
     ConfigCategory,
+    CorrectionScore,
     CreateAnnotationQueueAssignmentResponse,
     CreateAnnotationQueueItemRequest,
     CreateAnnotationQueueRequest,
@@ -85,9 +86,11 @@
     GetScoresResponseData,
     GetScoresResponseDataBoolean,
     GetScoresResponseDataCategorical,
+    GetScoresResponseDataCorrection,
     GetScoresResponseDataNumeric,
     GetScoresResponseData_Boolean,
     GetScoresResponseData_Categorical,
+    GetScoresResponseData_Correction,
     GetScoresResponseData_Numeric,
     GetScoresResponseTraceData,
     HealthResponse,
@@ -199,6 +202,7 @@
     ScoreV1_Numeric,
     Score_Boolean,
     Score_Categorical,
+    Score_Correction,
     Score_Numeric,
     SdkLogBody,
     SdkLogEvent,
@@ -293,6 +297,7 @@
     "Comment",
     "CommentObjectType",
     "ConfigCategory",
+    "CorrectionScore",
     "CreateAnnotationQueueAssignmentResponse",
     "CreateAnnotationQueueItemRequest",
     "CreateAnnotationQueueRequest",
@@ -342,9 +347,11 @@
     "GetScoresResponseData",
     "GetScoresResponseDataBoolean",
     "GetScoresResponseDataCategorical",
+    "GetScoresResponseDataCorrection",
     "GetScoresResponseDataNumeric",
     "GetScoresResponseData_Boolean",
     "GetScoresResponseData_Categorical",
+    "GetScoresResponseData_Correction",
     "GetScoresResponseData_Numeric",
     "GetScoresResponseTraceData",
     "HealthResponse",
@@ -456,6 +463,7 @@
     "ScoreV1_Numeric",
     "Score_Boolean",
     "Score_Categorical",
+    "Score_Correction",
     "Score_Numeric",
     "SdkLogBody",
     "SdkLogEvent",

langfuse/api/reference.md

@@ -1519,7 +1519,8 @@ client.dataset_items.get(
 <dl>
 <dd>
 
-Get dataset items
+Get dataset items. Optionally specify a version to get the items as they existed at that point in time.
+Note: If version parameter is provided, datasetName must also be provided.
 </dd>
 </dl>
 </dd>
@@ -1584,6 +1585,18 @@ client.dataset_items.list()
 <dl>
 <dd>
 
+**version:** `typing.Optional[dt.datetime]` 
+
+ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g., "2026-01-21T14:35:42Z").
+If provided, returns state of dataset at this timestamp.
+If not provided, returns the latest version. Requires datasetName to be specified.
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
 **page:** `typing.Optional[int]` — page number, starts at 1
 
 </dd>

langfuse/api/resources/__init__.py

@@ -67,6 +67,7 @@
     Comment,
     CommentObjectType,
     ConfigCategory,
+    CorrectionScore,
     CreateScoreValue,
     Dataset,
     DatasetItem,
@@ -101,6 +102,7 @@
     ScoreV1_Numeric,
     Score_Boolean,
     Score_Categorical,
+    Score_Correction,
     Score_Numeric,
     Session,
     SessionWithTraces,
@@ -268,9 +270,11 @@
     GetScoresResponseData,
     GetScoresResponseDataBoolean,
     GetScoresResponseDataCategorical,
+    GetScoresResponseDataCorrection,
     GetScoresResponseDataNumeric,
     GetScoresResponseData_Boolean,
     GetScoresResponseData_Categorical,
+    GetScoresResponseData_Correction,
     GetScoresResponseData_Numeric,
     GetScoresResponseTraceData,
 )
@@ -313,6 +317,7 @@
     "Comment",
     "CommentObjectType",
     "ConfigCategory",
+    "CorrectionScore",
     "CreateAnnotationQueueAssignmentResponse",
     "CreateAnnotationQueueItemRequest",
     "CreateAnnotationQueueRequest",
@@ -362,9 +367,11 @@
     "GetScoresResponseData",
     "GetScoresResponseDataBoolean",
     "GetScoresResponseDataCategorical",
+    "GetScoresResponseDataCorrection",
     "GetScoresResponseDataNumeric",
     "GetScoresResponseData_Boolean",
     "GetScoresResponseData_Categorical",
+    "GetScoresResponseData_Correction",
     "GetScoresResponseData_Numeric",
     "GetScoresResponseTraceData",
     "HealthResponse",
@@ -476,6 +483,7 @@
     "ScoreV1_Numeric",
     "Score_Boolean",
     "Score_Categorical",
+    "Score_Correction",
     "Score_Numeric",
     "SdkLogBody",
     "SdkLogEvent",

langfuse/api/resources/commons/__init__.py

@@ -10,6 +10,7 @@
     Comment,
     CommentObjectType,
     ConfigCategory,
+    CorrectionScore,
     CreateScoreValue,
     Dataset,
     DatasetItem,
@@ -41,6 +42,7 @@
     ScoreV1_Numeric,
     Score_Boolean,
     Score_Categorical,
+    Score_Correction,
     Score_Numeric,
     Session,
     SessionWithTraces,
@@ -68,6 +70,7 @@
     "Comment",
     "CommentObjectType",
     "ConfigCategory",
+    "CorrectionScore",
     "CreateScoreValue",
     "Dataset",
     "DatasetItem",
@@ -102,6 +105,7 @@
     "ScoreV1_Numeric",
     "Score_Boolean",
     "Score_Categorical",
+    "Score_Correction",
     "Score_Numeric",
     "Session",
     "SessionWithTraces",

langfuse/api/resources/commons/types/__init__.py

@@ -9,6 +9,7 @@
 from .comment import Comment
 from .comment_object_type import CommentObjectType
 from .config_category import ConfigCategory
+from .correction_score import CorrectionScore
 from .create_score_value import CreateScoreValue
 from .dataset import Dataset
 from .dataset_item import DatasetItem
@@ -29,7 +30,13 @@
 from .pricing_tier_condition import PricingTierCondition
 from .pricing_tier_input import PricingTierInput
 from .pricing_tier_operator import PricingTierOperator
-from .score import Score, Score_Boolean, Score_Categorical, Score_Numeric
+from .score import (
+    Score,
+    Score_Boolean,
+    Score_Categorical,
+    Score_Correction,
+    Score_Numeric,
+)
 from .score_config import ScoreConfig
 from .score_config_data_type import ScoreConfigDataType
 from .score_data_type import ScoreDataType
@@ -52,6 +59,7 @@
     "Comment",
     "CommentObjectType",
     "ConfigCategory",
+    "CorrectionScore",
     "CreateScoreValue",
     "Dataset",
     "DatasetItem",
@@ -83,6 +91,7 @@
     "ScoreV1_Numeric",
     "Score_Boolean",
     "Score_Categorical",
+    "Score_Correction",
     "Score_Numeric",
     "Session",
     "SessionWithTraces",

langfuse/api/resources/commons/types/correction_score.py

@@ -0,0 +1,53 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import datetime as dt
+import typing
+
+from ....core.datetime_utils import serialize_datetime
+from ....core.pydantic_utilities import deep_union_pydantic_dicts, pydantic_v1
+from .base_score import BaseScore
+
+
+class CorrectionScore(BaseScore):
+    value: float = pydantic_v1.Field()
+    """
+    The numeric value of the score. Always 0 for correction scores.
+    """
+
+    string_value: str = pydantic_v1.Field(alias="stringValue")
+    """
+    The string representation of the correction content
+    """
+
+    def json(self, **kwargs: typing.Any) -> str:
+        kwargs_with_defaults: typing.Any = {
+            "by_alias": True,
+            "exclude_unset": True,
+            **kwargs,
+        }
+        return super().json(**kwargs_with_defaults)
+
+    def dict(self, **kwargs: typing.Any) -> typing.Dict[str, typing.Any]:
+        kwargs_with_defaults_exclude_unset: typing.Any = {
+            "by_alias": True,
+            "exclude_unset": True,
+            **kwargs,
+        }
+        kwargs_with_defaults_exclude_none: typing.Any = {
+            "by_alias": True,
+            "exclude_none": True,
+            **kwargs,
+        }
+
+        return deep_union_pydantic_dicts(
+            super().dict(**kwargs_with_defaults_exclude_unset),
+            super().dict(**kwargs_with_defaults_exclude_none),
+        )
+
+    class Config:
+        frozen = True
+        smart_union = True
+        allow_population_by_field_name = True
+        populate_by_name = True
+        extra = pydantic_v1.Extra.allow
+        json_encoders = {dt.datetime: serialize_datetime}

langfuse/api/resources/commons/types/score.py

@@ -204,4 +204,69 @@ class Config:
         json_encoders = {dt.datetime: serialize_datetime}
 
 
-Score = typing.Union[Score_Numeric, Score_Categorical, Score_Boolean]
+class Score_Correction(pydantic_v1.BaseModel):
+    value: float
+    string_value: str = pydantic_v1.Field(alias="stringValue")
+    id: str
+    trace_id: typing.Optional[str] = pydantic_v1.Field(alias="traceId", default=None)
+    session_id: typing.Optional[str] = pydantic_v1.Field(
+        alias="sessionId", default=None
+    )
+    observation_id: typing.Optional[str] = pydantic_v1.Field(
+        alias="observationId", default=None
+    )
+    dataset_run_id: typing.Optional[str] = pydantic_v1.Field(
+        alias="datasetRunId", default=None
+    )
+    name: str
+    source: ScoreSource
+    timestamp: dt.datetime
+    created_at: dt.datetime = pydantic_v1.Field(alias="createdAt")
+    updated_at: dt.datetime = pydantic_v1.Field(alias="updatedAt")
+    author_user_id: typing.Optional[str] = pydantic_v1.Field(
+        alias="authorUserId", default=None
+    )
+    comment: typing.Optional[str] = None
+    metadata: typing.Any
+    config_id: typing.Optional[str] = pydantic_v1.Field(alias="configId", default=None)
+    queue_id: typing.Optional[str] = pydantic_v1.Field(alias="queueId", default=None)
+    environment: str
+    data_type: typing.Literal["CORRECTION"] = pydantic_v1.Field(
+        alias="dataType", default="CORRECTION"
+    )
+
+    def json(self, **kwargs: typing.Any) -> str:
+        kwargs_with_defaults: typing.Any = {
+            "by_alias": True,
+            "exclude_unset": True,
+            **kwargs,
+        }
+        return super().json(**kwargs_with_defaults)
+
+    def dict(self, **kwargs: typing.Any) -> typing.Dict[str, typing.Any]:
+        kwargs_with_defaults_exclude_unset: typing.Any = {
+            "by_alias": True,
+            "exclude_unset": True,
+            **kwargs,
+        }
+        kwargs_with_defaults_exclude_none: typing.Any = {
+            "by_alias": True,
+            "exclude_none": True,
+            **kwargs,
+        }
+
+        return deep_union_pydantic_dicts(
+            super().dict(**kwargs_with_defaults_exclude_unset),
+            super().dict(**kwargs_with_defaults_exclude_none),
+        )
+
+    class Config:
+        frozen = True
+        smart_union = True
+        allow_population_by_field_name = True
+        populate_by_name = True
+        extra = pydantic_v1.Extra.allow
+        json_encoders = {dt.datetime: serialize_datetime}
+
+
+Score = typing.Union[Score_Numeric, Score_Categorical, Score_Boolean, Score_Correction]