philter-sdk-java 2.0.0: Built for Philter 4.0.0

philter-sdk-java 2.0.0 has been released and is available now on Maven Central as ai.philterd:philter-sdk-java:2.0.0. This is the official Java client for the 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.

Built for Philter 4.0.0

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:

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:

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

The Developer Guide 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:

<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. For language other than Java, call the Philter HTTP API directly using the Philter OpenAPI specification: 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
• Redact PII Before Sending It to an LLM