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

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

Author: 3 people

packages/core/src/api/api/resources/blobStorageIntegrations/types/BlobStorageExportFieldGroup.ts

@@ -3,7 +3,7 @@
  */
 
 /**
- * Field group for the OBSERVATIONS_V2 and LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS export.
+ * Field group selecting which observation columns are included in the export. Applies to all export sources; groups without a counterpart in the legacy data model (e.g. `trace_context`) are omitted from the legacy observations export.
  */
 export type BlobStorageExportFieldGroup =
   | "core"

packages/core/src/api/api/resources/blobStorageIntegrations/types/BlobStorageExportSource.ts

@@ -4,9 +4,9 @@
 
 /**
  * What data the integration exports.
- * - `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables with a fixed column set. The `exportFieldGroups` field is not applicable.
+ * - `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables. Observation columns are controlled by `exportFieldGroups`; field groups without a counterpart in this data model (e.g. `trace_context`) are omitted.
  * - `OBSERVATIONS_V2`: same data model as the `/api/public/v2/observations` endpoint, plus scores. Columns are controlled by `exportFieldGroups`.
- * - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. For the `OBSERVATIONS_V2` portion, columns are controlled by `exportFieldGroups`.
+ * - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation columns of both portions are controlled by `exportFieldGroups`.
  *
  * **Note:** `OBSERVATIONS_V2` and the enriched-observations portion of `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` rely on the enriched observations table (Langfuse Fast Preview / v4), which is currently available on Langfuse Cloud only. See https://langfuse.com/docs/v4.
  */

packages/core/src/api/api/resources/blobStorageIntegrations/types/BlobStorageIntegrationResponse.ts

@@ -21,7 +21,7 @@ export interface BlobStorageIntegrationResponse {
   exportStartDate: string | null;
   compressed: boolean;
   exportSource: LangfuseAPI.BlobStorageExportSource;
-  /** Field groups included in each exported row for `OBSERVATIONS_V2` / `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` sources. Always `null` when exportSource is `LEGACY_TRACES_OBSERVATIONS` (the field does not apply to that source; any legacy DB value is hidden from the public surface). */
+  /** Field groups included in each exported observation row. An empty list is treated as all groups during export. */
   exportFieldGroups: LangfuseAPI.BlobStorageExportFieldGroup[] | null;
   nextSyncAt: string | null;
   lastSyncAt: string | null;

packages/core/src/api/api/resources/blobStorageIntegrations/types/CreateBlobStorageIntegrationRequest.ts

@@ -32,17 +32,15 @@ export interface CreateBlobStorageIntegrationRequest {
   /** Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true. */
   compressed?: boolean;
   /**
-   * Data to export. When omitted on update, the existing value is preserved. When omitted on create: pre-cutoff Cloud projects and self-hosted deployments fall back to `LEGACY_TRACES_OBSERVATIONS`; post-cutoff Cloud projects (created on or after 2026-05-20) auto-default to `OBSERVATIONS_V2`. Required when `exportFieldGroups` is provided.
+   * Data to export. When omitted on update, the existing value is preserved. When omitted on create: integrations on Langfuse Cloud default to `OBSERVATIONS_V2`; self-hosted deployments fall back to `LEGACY_TRACES_OBSERVATIONS`. Required when `exportFieldGroups` is provided.
    *
-   * **Cloud-only deprecation gate (effective 2026-05-20):** For projects created on or after 2026-05-20 on Langfuse Cloud, `LEGACY_TRACES_OBSERVATIONS` and `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP 400. Omitting `exportSource` on these projects silently defaults to `OBSERVATIONS_V2` rather than the schema column default. Use `OBSERVATIONS_V2` for all new integrations. Projects created before 2026-05-20 and self-hosted deployments are unaffected.
+   * **Cloud-only project deprecation gate (effective 2026-05-20):** For projects created on or after 2026-05-20 on Langfuse Cloud, `LEGACY_TRACES_OBSERVATIONS` and `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP 400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted deployments are unaffected.
+   *
+   * **Cloud-only integration deprecation gate (effective 2026-06-22):** On Langfuse Cloud, legacy export sources are only accepted for blob storage integrations created before 2026-06-22, regardless of project age. Requests that would create a new integration with `LEGACY_TRACES_OBSERVATIONS` or `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP 400. Use `OBSERVATIONS_V2` instead. Self-hosted deployments are unaffected.
    */
   exportSource?: LangfuseAPI.BlobStorageExportSource;
   /**
-   * Field groups to include in each exported row.
-   *
-   * For exportSource `OBSERVATIONS_V2` or `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: must include `core` if provided. When omitted on create, the column default (all groups) applies. When omitted on update, the existing value is preserved.
-   *
-   * For exportSource `LEGACY_TRACES_OBSERVATIONS`: this field must be omitted or null. Sending an array (including an empty array) returns 400, because that source uses a fixed column set and does not honor field groups.
+   * Field groups to include in each exported observation row. Applies to all export sources; must include `core` if provided. When omitted on create, the column default (all groups) applies. When omitted on update, the existing value is preserved.
    *
    * `exportFieldGroups` requires `exportSource` to be provided in the same request.
    */

packages/core/src/api/api/resources/datasetItems/types/CreateDatasetItemRequest.ts

@@ -11,7 +11,7 @@ export interface CreateDatasetItemRequest {
   metadata?: unknown;
   sourceTraceId?: string;
   sourceObservationId?: string;
-  /** Dataset items are upserted on their id. Id needs to be unique (project-level) and cannot be reused across datasets. */
+  /** Dataset items are upserted on their id. Id needs to be unique (project-level), cannot be reused across datasets, and must be at most 255 characters. */
   id?: string;
   /** Defaults to ACTIVE for newly created items */
   status?: LangfuseAPI.DatasetStatus;

packages/core/src/api/api/resources/scores/client/Client.ts

@@ -61,6 +61,9 @@ export class Scores {
   }
 
   /**
+   * **Deprecated.** Use `GET /api/public/v3/scores` instead. This endpoint
+   * is no longer available on Langfuse v4 and later.
+   *
    * Get a list of scores (supports both trace and session scores)
    *
    * @param {LangfuseAPI.GetScoresRequest} request
@@ -301,6 +304,9 @@ export class Scores {
   }
 
   /**
+   * **Deprecated.** Use `GET /api/public/v3/scores` with the `id` filter
+   * instead. This endpoint is no longer available on Langfuse v4 and later.
+   *
    * Get a score (supports both trace and session scores)
    *
    * @param {string} scoreId - The unique langfuse identifier of a score

packages/core/src/api/api/resources/scoresV3/client/Client.ts

@@ -63,15 +63,22 @@ export class ScoresV3 {
   /**
    * Get a list of scores with a polymorphic `value` field (v3).
    *
-   * This endpoint requires Langfuse v4 or later.
-   *
    * The `value` field type depends on `dataType`:
    * - `NUMERIC` → number
    * - `BOOLEAN` → boolean
    * - `CATEGORICAL`, `TEXT`, `CORRECTION` → string
    *
-   * Use the `fields` parameter to include optional field groups beyond the
-   * default `core`. Unknown group names return HTTP 400.
+   * The response always includes the core fields: id, projectId, name,
+   * value, dataType, source, timestamp, environment, createdAt, updatedAt.
+   *
+   * Additional field groups can be requested via the `fields` parameter:
+   * - `details` — adds comment, configId, metadata
+   * - `subject` — adds the subject object describing the entity the score
+   *   is attached to: kind (trace, observation, session, or experiment),
+   *   id, and traceId for observation-level scores
+   * - `annotation` — adds authorUserId, queueId
+   *
+   * Unknown group names return HTTP 400.
    *
    * @param {LangfuseAPI.GetScoresV3Request} request
    * @param {ScoresV3.RequestOptions} requestOptions - Request-specific configuration.

packages/core/src/api/api/resources/scoresV3/client/requests/GetScoresV3Request.ts

@@ -11,7 +11,7 @@ export interface GetScoresV3Request {
   limit?: number;
   /** URL-safe base64 (base64url) cursor for pagination. Use the cursor from the previous response to get the next page. Absent on the final page. */
   cursor?: string;
-  /** Comma-separated field groups to include. Allowed: core, details, subject, annotation. Defaults to "core". Unknown names return HTTP 400. */
+  /** Comma-separated field groups to include in addition to the always-returned core fields. Allowed: details, subject, annotation — see the endpoint description for the fields each group adds. Unknown names return HTTP 400. */
   fields?: string;
   /** Comma-separated list of score IDs to filter by (OR within, AND across filters). */
   id?: string;