---
title: "philter-sdk-java 2.0.0: Built for Philter 4.0.0"
description: "philter-sdk-java 2.0.0 is on Maven Central and targets the Philter 4.0.0 API: API-key auth, full endpoint coverage, and Java 11 bytecode."
url: "https://philterd.ai/blog/philter-sdk-java-2-0-0/"
---

[← All posts](https://philterd.ai/blog/)

# philter-sdk-java 2.0.0: Built for Philter 4.0.0

By [Jeff Zemerick](https://philterd.ai/authors/jeff-zemerick/) June 12, 2026 [Philter](https://philterd.ai/categories/philter/) · [Redaction](https://philterd.ai/categories/redaction/)

[philter-sdk-java](https://github.com/philterd/philter-sdk-java) 2.0.0 has been released and is available now on [Maven Central](https://central.sonatype.com/artifact/ai.philterd/philter-sdk-java) as `ai.philterd:philter-sdk-java:2.0.0`. This is the official Java client for the [Philter](https://philterd.ai/philter/) API, and it is the recommended way to call Philter from a JVM application. The headline of this release is compatibility: **2.0.0 targets the Philter 4.0.0 API**, and it covers that API in full.

This is a major version because it is not backward compatible with earlier clients. If you run Philter 4.0.0, you need philter-sdk-java 2.0.0 or later. If you are still on Philter 1.x through 3.x, stay on the 1.x client until you upgrade the server.

![Compatibility diagram: philter-sdk-java 2.0.0 and later targets the Philter 4.0.0 API, while the 1.x client targets Philter 1.x through 3.x](https://philterd.ai/images/philter-sdk-java-2-0-0-compatibility.svg)

philter-sdk-java targets a single major version of the Philter API. Upgrade the client and the server together.

## Built for Philter 4.0.0

| philter-sdk-java | Philter API |
| --- | --- |
| 2.0.0 and later | 4.0.0 |
| 1.x | 1.x – 3.x |

The Philter 4.0.0 API changed in ways that an older client cannot speak to, so 2.0.0 was rebuilt against it rather than patched. The most visible differences:

- **API-key authentication.** Philter 4.0.0 expects an `Authorization` header on nearly every endpoint. The client builder gains `withApiKey(...)` for this. The value is sent verbatim on every request, so include any scheme prefix (for example `"Bearer "`) if your deployment requires one. The new unauthenticated `health()` endpoint is the exception.
- **Server-assigned document IDs.** The document ID request parameter was dropped from `filter` and `explain`. Philter now assigns the document ID itself and returns it in the `x-document-id` response header.
- **Synchronous text filtering.** A text `filter` request now forces synchronous processing, so the filtered text comes back directly in the response instead of requiring a follow-up fetch.
- **Structured status, plus a health check.** The old `status()` string is replaced by a structured `StatusResponse`, and the new unauthenticated `health()` endpoint gives you a lightweight liveness probe.

## Full API coverage

Beyond filtering text, 2.0.0 exposes the complete Philter 4.0.0 API surface, so the operational parts of Philter are now reachable from Java without hand-rolling HTTP calls:

- **Policies**, including versions, diff, rollback, and compilation.
- **Contexts** and context entries (create, update, delete, export, import).
- **Documents**: list, retrieve, delete, and status.
- **Legal holds.**
- **The redaction ledger.**
- **Custom lists and redact lists.**
- **Re-identification** of redacted values.

Alerts support was removed because alerts are no longer part of the Philter API.

## What it looks like

With a running Philter instance, filtering text is three lines:

```java
PhilterClient client = new PhilterClient.PhilterClientBuilder()
        .withEndpoint("https://127.0.0.1:8080")
        .withApiKey("your-api-key")
        .build();

FilterResponse filterResponse = client.filter("context", "default", text);
```

When you need to know not just what was redacted but why each span was identified, use `explain`:

```java
ExplainResponse explainResponse = client.explain("context", "default", text);
```

The [Developer Guide](https://github.com/philterd/philter-sdk-java/blob/main/DEVELOPER.md) in the repository walks through the rest of the API, from managing policies to working with contexts and the redaction ledger.

## Build and tooling

- **Java 11 bytecode.** The client targets Java 11 (via `<release>11</release>`) for broad consumer compatibility, while building with a current JDK. You do not need a recent runtime to depend on it.
- **Published to Maven Central.** Artifact publishing moved to Maven Central, so no extra repository configuration is required.
- **Tested against a real and a mocked server.** Mocked unit tests (OkHttp `MockWebServer`) cover the full client surface on every build, and env-gated live integration tests run against a real Philter instance when `PHILTER_ENDPOINT` is set.

Dependencies were refreshed as part of the release, including an OkHttp upgrade (3.14.9 to 4.9.2) and updates to `commons-lang3`, `commons-io`, and `log4j-core`.

## Upgrading

Bump the Maven coordinate:

```xml
<dependency>
    <groupId>ai.philterd</groupId>
    <artifactId>philter-sdk-java</artifactId>
    <version>2.0.0</version>
</dependency>
```

Then adjust call sites for the breaking changes above: add `withApiKey(...)` to the builder, stop passing a document ID to `filter` and `explain` (read it from the `x-document-id` response header if you need it), and switch any code that read the old `status()` string to the new `StatusResponse`. If you relied on mTLS client certificates (`withSslConfiguration(...)`), note that mTLS support and the `ayza` dependency were removed in this release; it may return in a future version if there is demand.

The full list of changes is in the [release notes](https://github.com/philterd/philter-sdk-java/blob/main/RELEASE_NOTES.md). For language other than Java, call the Philter HTTP API directly using the [Philter OpenAPI specification](https://github.com/philterd/philter/blob/main/docs/docs/api_and_sdks/openapi.json): every running Philter instance also serves the spec with interactive Swagger UI, so you can generate a typed client in any language.

* * *

**Related posts:**

- [Phileas 4.0.0](https://philterd.ai/blog/phileas-4-0-0/)
- [Redact PII Before Sending It to an LLM](https://philterd.ai/blog/redact-pii-before-sending-to-an-llm/)

## Got a redaction problem that looks like this in your own pipeline?

Spend 30 minutes with Jeff (the engineer behind Philter) and walk away with a clear view of the architecture that fits your stack. No sales pitch.

[← Older post: Cutting False Positives on National IDs with Checksum Validation](https://philterd.ai/blog/checksum-validation-national-id-redaction/)

[Newer post →: Phileas 4.0.0](https://philterd.ai/blog/phileas-4-0-0/)

[← Back to all posts](https://philterd.ai/blog/)

Questions, ideas, or want to contribute? Join the conversation at [community.philterd.ai](https://philterd.ai/community/). Everything happens in public on GitHub.
