Java SDK

Installation

Requires Java 17+. The package is on Maven Central as com.relaypdf:relaypdf.

<dependency>
  <groupId>com.relaypdf</groupId>
  <artifactId>relaypdf</artifactId>
  <version>0.1.3</version>
</dependency>

Quick start

apiKey is required. Load RELAYPDF_API_KEY from the environment.

import com.relaypdf.RelayPDF;
import com.relaypdf.BinaryResult;

RelayPDF client = new RelayPDF(System.getenv("RELAYPDF_API_KEY"));
BinaryResult pdf = (BinaryResult) client.pdf.fromHtml(
    "<h1>Invoice #1042</h1><p>Total: $1,200.00</p>",
    Map.of("filename", "invoice.pdf")
);
pdf.save("invoice.pdf");

Errors and webhooks

Failures throw RelayPDFException. Webhook.verify checks RelayPDF-Signature against the raw body.

try {
    client.pdf.fromUrl("https://example.com");
} catch (RelayPDFException err) {
    System.out.println(err.getStatus() + " " + err.getCode() + " " + err.getMessage());
}

boolean ok = Webhook.verify(
    System.getenv("RELAYPDF_WEBHOOK_SECRET"),
    rawBody,
    signatureHeader
);

SDK reference

Pass Map extra arguments for REST camelCase fields. file values may be byte[] or a data: URL.

Document platform release support

The release adds ocr, pdfa, crop, resize, repair, optimize, attachments, extract-images, redact, compress, image-convert, and email processing. Every official SDK exposes process / ProcessAsync plus files.upload, files.delete, billingUsage / billing_usage, and billingLimits / billing_limits. Availability requires the matching released package. Older published versions may not contain these methods.

See /docs/files, /docs/billing, and each operation guide for field names and limits.

For safe retries, use URL or async output with Idempotency-Key. Per-request caps use X-RelayPDF-Max-Charge-Microdollars (integer millionths of USD). Billing APIs preserve microdollar precision; legacy account millicent fields are not the complete precise balance.

Native OCR with a per-job cap

Requires com.relaypdf:relaypdf 0.1.3 or a compatible newer release. Replace the example URL with your own publicly accessible scan. The 40000-microdollar cap authorizes at most $0.04; it is not a price estimate. Reuse the idempotency key only for retries of the same request.

client.files.upload / delete; client.billingUsage / billingLimits

Files and billing APIs do not require a separate client. See /docs/files, /docs/billing, and /docs/idempotency for ownership, precision, and retry behavior.

import com.relaypdf.RelayPDF;
import java.util.Map;

class Example {
  public static void main(String[] args) {
    var client = new RelayPDF(
        System.getenv("RELAYPDF_API_KEY"));
    var job = client.process("ocr", Map.of(
        "url", "https://example.com/scan.pdf",
        "response", "async"), Map.of(
        "idempotencyKey", "scan-001",
        "maxChargeMicrodollars", 40000));
  }
}

Java upload compatibility

Java 0.1.2 fixes files.upload with the default HTTP transport. Upgrade from 0.1.1 if uploads fail with restricted header name: Content-Length. The SDK now lets Java calculate the header from the request body; custom transports continue to receive the length hint.