> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia

> Java SDK classes, methods and options.

# Referencia

## `MarkpdfClient`

```java theme={null}
MarkpdfClient client = new MarkpdfClient("YOUR_API_KEY");

// or with custom baseUrl
MarkpdfClient client = new MarkpdfClient("YOUR_API_KEY", "https://api.markpdf.tech");
```

Internally use a single reusable `java.net.http.HttpClient` — don't create a `MarkpdfClient` per request; instantiate it once and reuse it (it's thread-safe).

## `ConvertOptions`

Immutable class built with builder. All fields are optional and use the same defaults as API.

```java theme={null}
ConvertOptions options = ConvertOptions.builder()
    .inputFormat(ConvertOptions.InputFormat.AUTO)   // default AUTO
    .mode(ConvertOptions.Mode.FAST)                 // default FAST
    .engine(ConvertOptions.Engine.AUTO)              // default AUTO
    .clean(true)                                     // default true
    .imageOcr(false)                                 // default false
    .hybridOcr(false)                                // default false
    .responseFormat(ConvertOptions.ResponseFormat.MARKDOWN) // default MARKDOWN
    .pages("1-10")                                   // default null (the whole document)
    .outputUrl(null)
    .outputEncoding(ConvertOptions.OutputEncoding.IDENTITY)
    .outputHeadUrl(null)
    .autoPoll(true)                                  // default true
    .build();

// shortcut for all defaults
ConvertOptions.defaults();
```

### Enums

```java theme={null}
enum Mode { FAST, ULTRA_FAST, BALANCED, QUALITY, AUTO }
enum InputFormat { AUTO, PDF, DOCX, XLSX, PPTX, CSV, TXT, ZIP }
enum ResponseFormat { MARKDOWN, JSON }
enum OutputEncoding { IDENTITY, GZIP, ZSTD }
```

See [Modes](/docs/concepts/modes) and [Formats](/docs/concepts/formats).

## Methods

### `convertFile`

```java theme={null}
ConvertResult convertFile(Path path, ConvertOptions options) throws MarkpdfException
```

Upload the file via multipart to `POST /convert`. Blocking.

### `convertBytes`

```java theme={null}
ConvertResult convertBytes(byte[] data, String filename, ConvertOptions options) throws MarkpdfException
```

Send `data` as raw body to `POST /convert/raw`. Blocking.

### `convertBytesAsync`

```java theme={null}
CompletableFuture<ConvertResult> convertBytesAsync(byte[] data, String filename, ConvertOptions options)
```

Same as `convertBytes` but non-blocking, using `HttpClient.sendAsync` internally. The `CompletableFuture` is exceptionally completed with `MarkpdfException` (wrapped if applicable) in case of error. See [Async and jobs](/docs/sdks/java/streaming-and-async).

### `convertFromUrl`

```java theme={null}
ConvertResult convertFromUrl(String url, String filename, ConvertOptions options) throws MarkpdfException
```

Llama a `POST /convert/from-url`.

### `pdfIndex`

```java theme={null}
Map<String, Object> pdfIndex(String url, String filename) throws MarkpdfException
```

Call `POST /pdf/index`. Returns the spine as `Map<String, Object>` deserialized with Jackson (`ObjectMapper.readValue(..., Map.class)`), preserving the original JSON structure: `pageCount`, `sections`, `fontModel`, etc.

```java theme={null}
Map<String, Object> spine = client.pdfIndex("https://bucket.example.com/report.pdf?sig=...", null);
List<Map<String, Object>> sections = (List<Map<String, Object>>) spine.get("sections");
```

### `getJob`

```java theme={null}
Job getJob(String jobId) throws MarkpdfException
```

Consulta manualmente `GET /jobs/{id}`.

### `waitForJob`

```java theme={null}
Job waitForJob(String jobId, Duration pollInterval, Duration timeout) throws MarkpdfException
```

Blocking: polls `GET /jobs/{id}` with interval `pollInterval` until `completed`/`failed` or until `timeout` is exhausted. `timeout` can be `null` to wait indefinitely.

## `ConvertResult`

Sealed interface with three records — uses pattern matching:

```java theme={null}
sealed interface ConvertResult
    permits ConvertResult.Markdown, ConvertResult.Json, ConvertResult.Queued {

    record Markdown(String markdown) implements ConvertResult {}
    record Json(JsonResult result) implements ConvertResult {}
    record Queued(Job job) implements ConvertResult {}
}
```

```java theme={null}
ConvertResult result = client.convertBytes(data, "report.pdf", options);

String markdown = switch (result) {
    case ConvertResult.Markdown md -> md.markdown();
    case ConvertResult.Json j -> j.result().markdown();
    case ConvertResult.Queued q -> throw new IllegalStateException("job en cola: " + q.job().jobId());
};
```

## `JsonResult`

```java theme={null}
record JsonResult(
    String markdown,
    String filename,
    String inputFormat,
    String engine,
    long sizeBytes,
    long markdownBytes,
    long tokenSavedEstimate,
    Timings timings
) {}

record Timings(
    long convertMs,
    long cleanMs,
    long totalWorkerMs,
    long uploadMs,
    long totalRequestMs
) {}
```

## `Job`

```java theme={null}
record Job(
    String jobId,
    JobStatus status, // enum: QUEUED, PROCESSING, COMPLETED, FAILED
    Object body,
    String error
) {}
```