feat!: remove endpoints deprecated in Langfuse v4 (#49)

Langfuse v4 moves to an observations-first data model, and the endpoints
built on the v3 model are deprecated: Langfuse Cloud serves them until
November 16, 2026, and self-hosted deployments lose them on upgrade to v4.
This prunes them from the generated client so it only exposes the API
surface that survives the cutover.

Removed entirely (every endpoint deprecated):

  ingestion         POST /ingestion
  observations      GET /observations, /observations/{id}
  metrics           GET /metrics (v1)
  sessions          GET /sessions, /sessions/{id}
  scorev2           GET /v2/scores, /v2/scores/{id}
  datasetrunitems   POST/GET /dataset-run-items

Pruned to the non-deprecated operations:

  trace       dropped get()/list(), kept delete()/deleteMultiple() — trace
              deletion is not deprecated and is now the documented way to
              delete experiment data
  datasets    dropped getRun()/deleteRun()/getRuns(), kept the /v2/datasets
              operations

Also drops the 34 types under resources/commons/types that the removal
orphaned (the v3-model read models: Trace*, Session*, Observation,
ObservationsView, the Score/ScoreV1 unions, DatasetRun*, Usage) and unwires
the six clients from LangfuseClient/AsyncLangfuseClient. Orphan status was
verified with an import-graph reachability pass and diffed against HEAD so
pre-existing orphans stayed out of scope.

Score writes are unaffected: POST /scores and DELETE /scores/{scoreId} stay
supported after the cutover. Only score reads move to /v3/scores.

The README now leads with OpenTelemetry as the recommended and going-forward
only supported path for tracing, and documents the per-endpoint migration
mapping. It also records that the prune has to be re-applied after each
regeneration, since the generator reproduces deprecated endpoints.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: Steffen911

README.md

@@ -3,9 +3,23 @@
 This repository contains an auto-generated Langfuse API client for Java based on our [API specification](https://github.com/langfuse/langfuse/tree/main/fern/apis/server).
 See the [Langfuse API reference](https://api.reference.langfuse.com) for more details on the available endpoints.
 
-**Note:** We recommend to solve tracing via the [OpenTelemetry Instrumentation](https://langfuse.com/docs/opentelemetry/get-started) instead of using the Ingestion API directly. You can use the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java) and export spans to the [Langfuse OTel endpoint](https://langfuse.com/integrations/native/opentelemetry).
-This allows for a more detailed and standardized tracing experience without the need to handle batching and updates internally.
-Check out our [Spring AI Example](https://langfuse.com/docs/integrations/spring-ai) for more details.
+## Use OpenTelemetry for tracing
+
+**OpenTelemetry is the recommended — and, going forward, the only supported — way to send tracing data to Langfuse from Java.**
+This client no longer exposes the legacy ingestion API; it is deprecated and is removed in [Langfuse v4](https://langfuse.com/docs/v4).
+
+Instrument your application with the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java) and export spans over OTLP/HTTP to the [Langfuse OTel endpoint](https://langfuse.com/integrations/native/opentelemetry):
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_STRING},x-langfuse-ingestion-version=4"
+```
+
+The `x-langfuse-ingestion-version: 4` header selects the v4 ingestion path. It is not sufficient on its own — spans also have to follow the v4 span format. Read [Migrate custom ingestion to Langfuse v4](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4) before switching production traffic; it covers the [v4-ready checklist](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4#v4-ready-ingestion-checklist), the [legacy event → OTel span mapping](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4#migrate-from-the-legacy-ingestion-api), and [propagating trace context to every observation](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4#propagate-trace-context-to-observations).
+
+Going through OpenTelemetry also means you do not have to handle batching, retries, or observation updates yourself. Check out our [Spring AI example](https://langfuse.com/integrations/frameworks/spring-ai) for a full setup.
+
+Use this client for everything that is *not* tracing ingestion: prompts, datasets, scores, models, comments, annotation queues, and the reading APIs.
 
 ## Installation
 
@@ -50,6 +64,30 @@ try {
 }
 ```
 
+## Langfuse v4: removed endpoints
+
+Langfuse v4 uses an [observations-first data model](https://langfuse.com/docs/v4). The endpoints built on the v3 model are deprecated: Langfuse Cloud serves them until **November 16, 2026**, and they become unavailable in self-hosted deployments as soon as those upgrade to v4.
+
+Those endpoints have been **removed from this client** so that it only exposes the API surface that survives the v4 cutover. The canonical, per-endpoint migration reference is [Migration of deprecated APIs](https://langfuse.com/faq/all/deprecated-api-migration); the [Versions & Compatibility matrix](https://langfuse.com/docs/compatibility) lists which endpoints work against which server version, and [Make your project ready for the upgrade to Langfuse v4](https://langfuse.com/faq/all/upgrade-to-langfuse-v4) is the step-by-step upgrade guide.
+
+| Removed from this client                                                          | Deprecated endpoint                                          | Replacement                                                                                                                                                       |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.ingestion().batch(...)`                                                   | `POST /api/public/ingestion`                                 | [OpenTelemetry ingestion](https://langfuse.com/faq/all/deprecated-api-migration#ingestion) — see above                                                            |
+| `client.observations().get(...)` / `.getMany(...)`                                | `GET /api/public/observations`, `/observations/{id}`         | `client.observationsV2().getMany(...)` ([Observations API v2](https://langfuse.com/faq/all/deprecated-api-migration#observations))                                |
+| `client.trace().get(...)` / `.list(...)`                                          | `GET /api/public/traces`, `/traces/{id}`                    | `client.observationsV2().getMany(...)` filtered by `traceId` ([Traces](https://langfuse.com/faq/all/deprecated-api-migration#traces))                             |
+| `client.sessions().get(...)` / `.list(...)`                                        | `GET /api/public/sessions`, `/sessions/{id}`                | `client.observationsV2().getMany(...)` filtered by `sessionId` ([Sessions](https://langfuse.com/faq/all/deprecated-api-migration#sessions))                       |
+| `client.metrics().metrics(...)`                                                   | `GET /api/public/metrics`                                    | `client.metricsV2().metrics(...)` ([Metrics API v2](https://langfuse.com/faq/all/deprecated-api-migration#metrics))                                               |
+| `client.scoreV2().get(...)` / `.getById(...)`                                      | `GET /api/public/v2/scores`, `/v2/scores/{id}`              | [Scores API v3](https://langfuse.com/faq/all/deprecated-api-migration#scores) — **not generated yet**, call `GET /api/public/v3/scores` directly for now          |
+| `client.datasets().getRuns(...)` / `.getRun(...)` / `.deleteRun(...)`              | `GET`/`DELETE /api/public/datasets/{name}/runs[/{runName}]` | [Experiments API](https://langfuse.com/faq/all/deprecated-api-migration#dataset-runs) — **not generated yet**, call `GET /api/public/experiments` directly for now |
+| `client.datasetRunItems().create(...)` / `.list(...)`                              | `POST`/`GET /api/public/dataset-run-items`                   | [Experiment Items API](https://langfuse.com/faq/all/deprecated-api-migration#dataset-runs) / OTel experiment attributes — **not generated yet**                    |
+
+Notes:
+
+- **Score writes are unaffected.** `client.score().create(...)` (`POST /api/public/scores`) and `client.score().delete(...)` stay supported after the v4 cutover. Only score *reads* move to v3.
+- **Trace deletion is not deprecated.** `client.trace().delete(...)` and `client.trace().deleteMultiple(...)` are kept; they are also how you delete experiment data now that `DELETE /datasets/{name}/runs/{runName}` is gone.
+- **Datasets themselves are not deprecated.** `client.datasets()` still exposes the `/api/public/v2/datasets` endpoints; only the dataset *run* endpoints were removed.
+- The `/api/public/v3/scores`, `/api/public/experiments`, and `/api/public/experiment-items` endpoints exist in the Langfuse API but are not part of this client yet. They will be picked up by the next regeneration; until then, call them directly.
+
 ## Testing
 
 ### Unit tests
@@ -117,4 +155,5 @@ To publish to Maven Central, you need to configure the following secrets in your
 4. Manually set the `package` across all files to `com.langfuse.client`.
 5. Verify that `LangfuseClientBuilder.setAuthentication()` uses `Basic` auth (not `Bearer`).
 6. Adjust Javadoc strings with HTML properties as the apidocs package does not support them.
-7. Commit the changes in langfuse-java and push them to the repository.
+7. Re-apply the deprecated-endpoint prune. Regeneration reintroduces every endpoint marked `availability: status: deprecated` in the API definition — the ones listed under [Langfuse v4: removed endpoints](#langfuse-v4-removed-endpoints). Drop those resource packages and methods again, remove the now-orphaned types under `resources/commons/types`, and unwire them from `LangfuseClient`/`AsyncLangfuseClient`.
+8. Commit the changes in langfuse-java and push them to the repository.

src/main/java/com/langfuse/client/AsyncLangfuseClient.java

@@ -9,16 +9,12 @@
 import com.langfuse.client.resources.blobstorageintegrations.AsyncBlobStorageIntegrationsClient;
 import com.langfuse.client.resources.comments.AsyncCommentsClient;
 import com.langfuse.client.resources.datasetitems.AsyncDatasetItemsClient;
-import com.langfuse.client.resources.datasetrunitems.AsyncDatasetRunItemsClient;
 import com.langfuse.client.resources.datasets.AsyncDatasetsClient;
 import com.langfuse.client.resources.health.AsyncHealthClient;
-import com.langfuse.client.resources.ingestion.AsyncIngestionClient;
 import com.langfuse.client.resources.llmconnections.AsyncLlmConnectionsClient;
 import com.langfuse.client.resources.media.AsyncMediaClient;
-import com.langfuse.client.resources.metrics.AsyncMetricsClient;
 import com.langfuse.client.resources.metricsv2.AsyncMetricsV2Client;
 import com.langfuse.client.resources.models.AsyncModelsClient;
-import com.langfuse.client.resources.observations.AsyncObservationsClient;
 import com.langfuse.client.resources.observationsv2.AsyncObservationsV2Client;
 import com.langfuse.client.resources.opentelemetry.AsyncOpentelemetryClient;
 import com.langfuse.client.resources.organizations.AsyncOrganizationsClient;
@@ -28,8 +24,6 @@
 import com.langfuse.client.resources.scim.AsyncScimClient;
 import com.langfuse.client.resources.score.AsyncScoreClient;
 import com.langfuse.client.resources.scoreconfigs.AsyncScoreConfigsClient;
-import com.langfuse.client.resources.scorev2.AsyncScoreV2Client;
-import com.langfuse.client.resources.sessions.AsyncSessionsClient;
 import com.langfuse.client.resources.trace.AsyncTraceClient;
 
 public class AsyncLangfuseClient {
@@ -43,28 +37,20 @@ public class AsyncLangfuseClient {
 
   protected final Supplier<AsyncDatasetItemsClient> datasetItemsClient;
 
-  protected final Supplier<AsyncDatasetRunItemsClient> datasetRunItemsClient;
-
   protected final Supplier<AsyncDatasetsClient> datasetsClient;
 
   protected final Supplier<AsyncHealthClient> healthClient;
 
-  protected final Supplier<AsyncIngestionClient> ingestionClient;
-
   protected final Supplier<AsyncLlmConnectionsClient> llmConnectionsClient;
 
   protected final Supplier<AsyncMediaClient> mediaClient;
 
   protected final Supplier<AsyncMetricsV2Client> metricsV2Client;
 
-  protected final Supplier<AsyncMetricsClient> metricsClient;
-
   protected final Supplier<AsyncModelsClient> modelsClient;
 
   protected final Supplier<AsyncObservationsV2Client> observationsV2Client;
 
-  protected final Supplier<AsyncObservationsClient> observationsClient;
-
   protected final Supplier<AsyncOpentelemetryClient> opentelemetryClient;
 
   protected final Supplier<AsyncOrganizationsClient> organizationsClient;
@@ -79,12 +65,8 @@ public class AsyncLangfuseClient {
 
   protected final Supplier<AsyncScoreConfigsClient> scoreConfigsClient;
 
-  protected final Supplier<AsyncScoreV2Client> scoreV2Client;
-
   protected final Supplier<AsyncScoreClient> scoreClient;
 
-  protected final Supplier<AsyncSessionsClient> sessionsClient;
-
   protected final Supplier<AsyncTraceClient> traceClient;
 
   public AsyncLangfuseClient(ClientOptions clientOptions) {
@@ -93,27 +75,21 @@ public AsyncLangfuseClient(ClientOptions clientOptions) {
     this.blobStorageIntegrationsClient = Suppliers.memoize(() -> new AsyncBlobStorageIntegrationsClient(clientOptions));
     this.commentsClient = Suppliers.memoize(() -> new AsyncCommentsClient(clientOptions));
     this.datasetItemsClient = Suppliers.memoize(() -> new AsyncDatasetItemsClient(clientOptions));
-    this.datasetRunItemsClient = Suppliers.memoize(() -> new AsyncDatasetRunItemsClient(clientOptions));
     this.datasetsClient = Suppliers.memoize(() -> new AsyncDatasetsClient(clientOptions));
     this.healthClient = Suppliers.memoize(() -> new AsyncHealthClient(clientOptions));
-    this.ingestionClient = Suppliers.memoize(() -> new AsyncIngestionClient(clientOptions));
     this.llmConnectionsClient = Suppliers.memoize(() -> new AsyncLlmConnectionsClient(clientOptions));
     this.mediaClient = Suppliers.memoize(() -> new AsyncMediaClient(clientOptions));
     this.metricsV2Client = Suppliers.memoize(() -> new AsyncMetricsV2Client(clientOptions));
-    this.metricsClient = Suppliers.memoize(() -> new AsyncMetricsClient(clientOptions));
     this.modelsClient = Suppliers.memoize(() -> new AsyncModelsClient(clientOptions));
     this.observationsV2Client = Suppliers.memoize(() -> new AsyncObservationsV2Client(clientOptions));
-    this.observationsClient = Suppliers.memoize(() -> new AsyncObservationsClient(clientOptions));
     this.opentelemetryClient = Suppliers.memoize(() -> new AsyncOpentelemetryClient(clientOptions));
     this.organizationsClient = Suppliers.memoize(() -> new AsyncOrganizationsClient(clientOptions));
     this.projectsClient = Suppliers.memoize(() -> new AsyncProjectsClient(clientOptions));
     this.promptVersionClient = Suppliers.memoize(() -> new AsyncPromptVersionClient(clientOptions));
     this.promptsClient = Suppliers.memoize(() -> new AsyncPromptsClient(clientOptions));
     this.scimClient = Suppliers.memoize(() -> new AsyncScimClient(clientOptions));
     this.scoreConfigsClient = Suppliers.memoize(() -> new AsyncScoreConfigsClient(clientOptions));
-    this.scoreV2Client = Suppliers.memoize(() -> new AsyncScoreV2Client(clientOptions));
     this.scoreClient = Suppliers.memoize(() -> new AsyncScoreClient(clientOptions));
-    this.sessionsClient = Suppliers.memoize(() -> new AsyncSessionsClient(clientOptions));
     this.traceClient = Suppliers.memoize(() -> new AsyncTraceClient(clientOptions));
   }
 
@@ -133,10 +109,6 @@ public AsyncDatasetItemsClient datasetItems() {
     return this.datasetItemsClient.get();
   }
 
-  public AsyncDatasetRunItemsClient datasetRunItems() {
-    return this.datasetRunItemsClient.get();
-  }
-
   public AsyncDatasetsClient datasets() {
     return this.datasetsClient.get();
   }
@@ -145,10 +117,6 @@ public AsyncHealthClient health() {
     return this.healthClient.get();
   }
 
-  public AsyncIngestionClient ingestion() {
-    return this.ingestionClient.get();
-  }
-
   public AsyncLlmConnectionsClient llmConnections() {
     return this.llmConnectionsClient.get();
   }
@@ -161,10 +129,6 @@ public AsyncMetricsV2Client metricsV2() {
     return this.metricsV2Client.get();
   }
 
-  public AsyncMetricsClient metrics() {
-    return this.metricsClient.get();
-  }
-
   public AsyncModelsClient models() {
     return this.modelsClient.get();
   }
@@ -173,10 +137,6 @@ public AsyncObservationsV2Client observationsV2() {
     return this.observationsV2Client.get();
   }
 
-  public AsyncObservationsClient observations() {
-    return this.observationsClient.get();
-  }
-
   public AsyncOpentelemetryClient opentelemetry() {
     return this.opentelemetryClient.get();
   }
@@ -205,18 +165,10 @@ public AsyncScoreConfigsClient scoreConfigs() {
     return this.scoreConfigsClient.get();
   }
 
-  public AsyncScoreV2Client scoreV2() {
-    return this.scoreV2Client.get();
-  }
-
   public AsyncScoreClient score() {
     return this.scoreClient.get();
   }
 
-  public AsyncSessionsClient sessions() {
-    return this.sessionsClient.get();
-  }
-
   public AsyncTraceClient trace() {
     return this.traceClient.get();
   }