` | none | Regex allowlist and denylist, max 50 each. The denylist is applied second. |
| `sameDomainOnly`, `respectRobots` | `boolean` | `true`, none | Stay on the seed domain, and honor the site's robots rules. |
### Lookup
Categorized web search, optionally auto rendering the top results. Endpoint reference: [Lookup](/docs/v2-lookup).
```java
LookupResult search = client.v2.lookup("best static site generators",
LookupOptions.builder()
.category("web") // web, news, images, scholar, patents, maps
.numResults(10)
.country("us")
.timeFilter("month") // hour, day, week, month, year
.perceiveTop(3) // auto-render the top 3 hits
.build());
search.results().forEach(hit -> {
System.out.println(hit.position() + " " + hit.title() + " " + hit.url());
if (hit.perceive() != null) System.out.println(" quality " + hit.perceive().renderQuality());
});
```
With `perceiveTop` above 0 (0 to 10, default 0), the top N result URLs are rendered through perceive and each hit carries its full `PerceiveResult` inline on `hit.perceive()`. `numResults` runs 1 to 100 and defaults to 10; `page` runs 1 to 10.
### Distill
Schema driven structured extraction across one or more pages. Endpoint reference: [Distill](/docs/v2-distill).
```java
DistillResult extraction = client.v2.distill(
DistillOptions.builder(Map.of("products", "list of product names with their listed price"))
.urls(List.of("https://example.com/catalog"))
.cssSchema(CssSchema.builder(".product-card", List.of(
CssField.builder("name", "text").selector("h3").build(),
CssField.builder("price", "text").selector(".price").build()))
.targetField("products")
.build())
.build());
extraction.results().forEach(item ->
System.out.println(item.data() + " via " + item.extractionTier()));
```
The optional `cssSchema` runs a free CSS pass first; only the fields it cannot answer escalate to the LLM tier, and `item.extractionTier()` reports which path produced the record (`css`, `llm`, `mixed`, or `none`). You can also discover the URLs first instead of listing them:
```java
client.v2.distill(
DistillOptions.builder(Map.of("title", "page title", "summary", "one-line summary"))
.discoverFrom(new DistillDiscoverFrom("https://example.com", "sitemap", 10))
.build());
```
Exactly one of `urls` (max 50) and `discoverFrom` must be set, and `schema` is required by the builder factory. Both rules are checked client side and throw `IllegalArgumentException` before any request goes out.
### Ingest
Turn a whole site, or a set of uploaded documents, into chunked RAG ready JSONL through one pipeline. Ingest is always asynchronous. Endpoint reference: [Ingest](/docs/v2-ingest).
```java
// From a site
IngestJob job = client.v2.ingest(IngestOptions.builder()
.mode("sitemap") // "urls" (default), "sitemap", "crawl"
.url("https://docs.example.com")
.maxPages(100)
.chunk(new IngestChunkOptions(512, 1)) // maxWords, sentenceOverlap
.webhookUrl("https://my.app/hooks/enconvert")
.build());
// Or from uploaded files
IngestJob fileJob = client.v2.ingestFiles(
List.of(new FileInput(Files.readAllBytes(Path.of("handbook.pdf")), "handbook.pdf"),
new FileInput(Files.readAllBytes(Path.of("notes.docx")), "notes.docx")),
IngestFilesOptions.builder().chunk(new IngestChunkOptions(512, 1)).build());
// Poll for the JSONL
IngestJob status = client.v2.getIngestJob(job.jobId());
if ("completed".equals(status.status())) {
System.out.println(status.outputUrl() + " (" + status.totalChunks() + " chunks)");
}
client.v2.listIngestJobs(V2ListOptions.builder().limit(20).build());
client.v2.cancelIngestJob(job.jobId()); // idempotent
```
`ingestFiles` accepts PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT and MD, plus legacy and ODF office formats. Chunking defaults to 512 words (32 to 4000) with 1 sentence of overlap (0 to 10). `mode` defaults to `urls`, which requires a non-empty `urls` list and forbids `url`; every other mode requires a seed `url` and forbids `urls`. The SDK enforces that pairing before sending.
Completion webhooks are HMAC signed. Fetch the secret and the header names you need to verify a delivery, rotate it when it leaks, and re-fire a delivery your endpoint missed:
```java
WebhookSecret secret = client.v2.getWebhookSecret();
System.out.println(secret.signatureHeader() + " " + secret.signatureScheme());
client.v2.rotateWebhookSecret(); // old signatures stop verifying immediately
WebhookRetryResult retry = client.v2.retryIngestWebhook(job.jobId());
System.out.println(retry.delivered() + " after " + retry.attempts() + " attempts");
```
### Watch
Recurring change monitoring on a URL, with email and webhook notification. Endpoint reference: [Watch](/docs/v2-watch).
```java
Watcher watcher = client.v2.createWatcher("https://example.com/pricing",
WatchCreateOptions.builder()
.frequencyMinutes(60) // 60 to 43200, hourly floor
.diffMode("auto") // auto, text, structured, tables, metadata
.webhookUrl("https://my.app/hooks/changes")
.notifyEmail(true)
.build());
WatcherSnapshotList history = client.v2.getWatcherSnapshots(watcher.watcherId(),
SnapshotListOptions.builder().limit(10).build());
history.snapshots().forEach(s ->
System.out.println(s.checkedAt() + " changed=" + s.hasChanges()
+ " similarity=" + s.similarity()));
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().status("paused").build());
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().webhookUrl("").build());
client.v2.deleteWatcher(watcher.watcherId()); // soft delete, idempotent
```
`listWatchers()` and `getWatcher(watcherId)` read them back. `updateWatcher` requires at least one field and throws `IllegalArgumentException` otherwise. An explicit empty string for `webhookUrl` clears the webhook, while leaving it null means "no change". `deleteWatcher` is a soft delete: it returns the tombstoned watcher with status `deleted`, and a deleted watcher then reads as `404`.
Snapshot diffs contain untrusted page content. WatcherSnapshot.changes() is raw text lifted from the monitored page. Escape it before rendering it in a dashboard, an email, or a chat message.
---
## PDF options
`PdfOptions` is shared by `convertUrlToPdf`, `convertWebsiteToPdf`, `convertDocument`, `convertToPdf`, and `PerceiveOptions.pdfOptions`.
```java
client.convertUrlToPdf("https://internal.example.com/report",
UrlToPdfOptions.builder()
.pdfOptions(PdfOptions.builder()
.pageSize("A4")
.orientation("landscape")
.margins(new PdfMargins(10.0, 10.0, 15.0, 15.0))
.scale(0.9)
.header(new PdfHeaderFooter("Quarterly Report", 15.0))
.footer(new PdfHeaderFooter("Confidential", 12.0))
.build())
.auth(new HttpBasicAuth("user", "pass"))
.cookies(List.of(BrowserCookie.builder("session", "abc123").domain("internal.example.com").build()))
.headers(Map.of("X-Tenant", "acme"))
.saveTo("report.pdf")
.build());
```
| Field | Type | Description |
|-------|------|-------------|
| `pageSize` | `String` | `"A4"`, `"A3"`, `"Letter"`, `"Legal"`, and similar. |
| `pageWidth`, `pageHeight` | `double` | Custom dimensions. Set together, they override `pageSize`. |
| `orientation` | `String` | `"portrait"` or `"landscape"`. |
| `margins` | `PdfMargins` | Record of `top`, `bottom`, `left`, `right`. Any null field is omitted. |
| `scale` | `double` | Render scale, for example `0.9` for 90 percent. |
| `grayscale` | `boolean` | Post-process the PDF to grayscale. |
| `header`, `footer` | `PdfHeaderFooter` | Record of `content` (max 2000 characters) and `height`. |
`BrowserCookie` needs a name and value plus either `domain` or `url`; when `domain` is set without `path`, the API defaults `path` to `/`. Do not combine `auth` with an explicit `Authorization` header, because the API rejects the conflict.
---
## Error handling
Every SDK exception extends `EnconvertException`, which extends `RuntimeException`, so nothing forces a `throws` clause on your call sites. Catch the specific subclasses first.
```java
try {
client.convertUrlToPdf("https://example.com");
} catch (AuthenticationException e) {
System.err.println("Invalid or missing API key");
} catch (QuotaException e) {
System.err.println("Request refused with 402: " + e.getMessage());
} catch (RateLimitException e) {
System.err.println("Too many requests, back off and retry");
} catch (ApiException e) {
System.err.println("API error [" + e.getStatusCode() + "]: " + e.getMessage());
}
```
| Class | Raised on | Status code |
|-------|-----------|-------------|
| `AuthenticationException` | Missing, invalid, or non-permitted API key | `401`, `403` |
| `QuotaException` | HTTP 402 | `402` |
| `RateLimitException` | Too many requests | `429` |
| `ApiException` | Any other 4xx or 5xx response | the actual code |
| `EnconvertException` | Base class, also raised on transport failure, an interrupted request, or an unreadable input file | none |
Client side validation (an unsupported conversion pair, a missing distill schema, an empty watcher update, the wrong number of outputs for `perceiveDirect`) throws `IllegalArgumentException` before any request is made. The message map for server responses is in the [Error codes](/docs/error-codes) reference.
---
## Timeout recovery
Long URL renders and large document conversions can outlive the reverse proxy timeout even when the conversion itself eventually succeeds. The SDK handles that transparently:
1. Before each single URL or file upload request, the SDK generates a UUID and sends it as `job_id`.
2. If the request comes back 5xx, the SDK switches to polling `GET /v1/convert/status/{jobId}` every 3 seconds.
3. On `success` it returns the result. On `failed` it throws `ApiException` carrying the server's error message.
4. The polling deadline is 5 minutes. Past that it throws `ApiException(504, "Conversion timed out")`.
You write no code for this. If a successful response omits `job_id`, the SDK backfills the id it generated, so `result.jobId()` is always usable with `getJobStatus`.
Website batch submissions are excluded on purpose. convertWebsiteToPdf and convertWebsiteToScreenshot have no per-job row to poll, so a 5xx there means the submission itself failed and is surfaced directly. V2 endpoints do not use job polling either; their asynchronous flows go through getPerceiveBatch and getIngestJob.
---
## Configuration
```java
Enconvert client = Enconvert.builder(System.getenv("ENCONVERT_API_KEY"))
.baseUrl("https://api.enconvert.com")
.timeout(Duration.ofSeconds(300))
.build();
```
Three constructors are available as shorthand: `new Enconvert(apiKey)`, `new Enconvert(apiKey, baseUrl)`, and `new Enconvert(apiKey, baseUrl, timeout)`.
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `String` | required | Private API key. A null or empty value throws `IllegalArgumentException`. |
| `baseUrl` | `String` | `https://api.enconvert.com` | API base URL. Trailing slashes are stripped. |
| `timeout` | `Duration` | 300 seconds | Applied as both the connect timeout and the per-request timeout. |
The key travels in the `X-API-Key` header. Presigned download URLs are fetched without it, since they are already signed. Key types are covered in [Authentication](/docs/authentication); create and manage keys in the [dashboard](/dashboard).
Never hardcode the API key. Read it from an environment variable or your secret manager. The SDK is server side only: a private key must not ship inside a desktop or mobile artifact that a user can unpack.
---
## Result shape
Every single file and single URL conversion returns the same record:
```java
public record ConversionResult(
String presignedUrl,
String objectKey,
String filename,
Long fileSize,
Double conversionTimeSeconds,
String jobId) {}
```
The presigned URL is time limited. Pass `saveTo` (or fetch the URL yourself) and store the bytes in your own bucket if you need them to outlive it.
The other response records you will touch most often:
| Record | Key accessors |
|--------|---------------|
| `JobStatus` | `status()` (`processing`, `success`, `failed`), `presignedUrl()`, `objectKey()`, `error()` |
| `BatchStatus` | `status()`, `total()`, `completed()`, `failed()`, `inProgress()`, `zipDownloadUrl()`, `items()` |
| `PerceiveResult` | `operationId()`, `renderQuality()`, `statusCode()`, `deductions()`, `outputs()`, `structured()`, `cacheHit()`, `warnings()` |
| `V2OutputArtifact` | `url()`, `objectKey()`, `sizeBytes()`, `contentType()`, `expiresIn()` |
| `PerceiveDirectResult` | `content()`, `contentType()`, `filename()`, `renderQuality()`, `contentHash()` |
| `IngestJob` | `jobId()`, `status()`, `pagesProcessed()`, `totalChunks()`, `outputUrl()`, `webhookDelivered()` |
| `Watcher` | `watcherId()`, `status()`, `frequencyMinutes()`, `checksCount()`, `nextCheckAt()`, `lastChangeAt()` |
Fields whose shape is defined by your own request (`structured`, `data`, `trackFields`, snapshot `changes`) are exposed as Gson `JsonObject` and pass through untouched. String valued enumerations stay `String` rather than becoming Java `enum` constants, so a newer API value never breaks deserialization on an older SDK build. `com.enconvert.model.v2.V2Enums` holds every accepted value as a typo-proof constant.
---
## Source and issues
- **Maven Central:** `com.enconvert:enconvert-sdk:0.0.1`
- **GitHub:** [conversionapi/java-sdk](https://github.com/conversionapi/java-sdk)
- **License:** MIT
- **Other clients:** [all SDKs](/docs/sdks) · [endpoint reference](/docs/endpoints-overview) · [pricing](/pricing)
---
## Frequently asked questions
### How do I convert files in Java with a Maven dependency?
Add `com.enconvert:enconvert-sdk:0.0.1` to your `pom.xml` or `build.gradle`, build a client with `new Enconvert(System.getenv("ENCONVERT_API_KEY"))`, and call a typed method such as `convertUrlToPdf`, `convertImage`, `convertDocument`, or `convertToPdf`. Pass `saveTo` on the options builder to write the output straight to disk instead of handling the presigned URL yourself.
### How do I convert a URL to PDF in Java?
Call `client.convertUrlToPdf(url, UrlToPdfOptions.builder().saveTo("page.pdf").build())`. Set `singlePage(false)` to paginate using `pdfOptions.pageSize` instead of producing one continuous page, and pass `auth`, `cookies`, or `headers` for a page behind a login.
### How do I convert DOCX to PDF in Java?
Call `client.convertDocument(Path.of("report.docx"), ConvertDocumentOptions.builder().saveTo("report.pdf").build())`. The output format defaults to `pdf`, so you only set `outputFormat` when you want something else, for example `yaml` from a `.json` input. For formats without a dedicated pair, such as EPUB or RTF, use `convertToPdf`.
### How do I convert HEIC to WebP in Java?
Call `client.convertImage(Path.of("photo.heic"), ConvertImageOptions.builder("webp").saveTo("photo.webp").build())`. The input format comes from the file extension and the output format is the required builder argument. `jpeg`, `png`, `svg`, `heic`, and `webp` all convert to each other, and `pdf` rasterizes to `jpeg`. There is no compress-in-place method on this client.
### How do I scrape a web page into clean Markdown from Java?
Two paths. `client.convertUrlToMarkdown(url, ...)` returns GitHub Flavored Markdown with YAML frontmatter as a downloadable file. `client.v2.perceive(url, PerceiveOptions.builder().outputs(List.of("markdown")).build())` returns the same content as an agent-ready artifact with a `renderQuality` score, extraction options, and cache control. Use perceive when a bad read must be detectable rather than silent.
### What is renderQuality and why does every read have one?
`renderQuality` is a score from 0.0 to 1.0 attached to every V2 render. A high score means the page rendered cleanly; a low score means something got in the way, such as a bot challenge, a cookie wall, a login screen, an HTTP error page, or an empty SPA shell. The content is still returned, with `warnings()` and `deductions()` populated, so your pipeline can drop or retry the read instead of feeding a challenge page into a model as if it were the article.
### How do I turn a documentation site into RAG-ready chunks in Java?
Call `client.v2.ingest(IngestOptions.builder().mode("sitemap").url("https://docs.example.com").maxPages(100).chunk(new IngestChunkOptions(512, 1)).build())`. The job is asynchronous, so either poll `getIngestJob(jobId)` until the status is `completed` and read `outputUrl()` for the JSONL, or set `webhookUrl` and verify the HMAC signature with the secret from `getWebhookSecret()`. For local documents rather than a site, use `ingestFiles`.
### How does the SDK handle conversions that outlive the proxy timeout?
Before each single URL or file upload request it generates a UUID and sends it as `job_id`. If the request returns 5xx, it polls `GET /v1/convert/status/{jobId}` every 3 seconds until the job reports `success` or `failed`, with a 5 minute deadline after which it throws `ApiException(504, "Conversion timed out")`. Whole site batch submissions are excluded, because they have no per-job row to poll.
### Which Java version does the SDK require, and what does it pull in?
Java 17 or newer. HTTP goes through the JDK's `java.net.http.HttpClient`, and Gson is the only third party artifact on the classpath. Responses are Java records, so a modern `switch` or pattern match over them works as expected. The client is thread safe: hold one instance and share it.