> ## 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

> Kotlin SDK classes, methods, and options.

# Referencia

## `MarkpdfClient`

```kotlin theme={null}
val client = MarkpdfClient(
    apiKey = "YOUR_API_KEY",
    baseUrl = "https://api.markpdf.tech", // optional, production default
    http = OkHttpClient(),                  // optional, your own OkHttpClient
)
```

<ParamField body="apiKey" type="String" required>
  Tu API key.
</ParamField>

<ParamField body="baseUrl" type="String" default="https://api.markpdf.tech">
  URL base of API.
</ParamField>

<ParamField body="http" type="OkHttpClient" default="OkHttpClient()">
  OkHttp instance to reuse. Useful for sharing the connection pool with the rest of your app, injecting interceptors (logging, proxy) or adjusting timeouts.
</ParamField>

`MarkpdfClient` is thread-safe and is intended to be instantiated once and reused throughout the life of the app.

## `ConvertOptions`

Data class with defaults — pass only what you want to change.

```kotlin theme={null}
data class ConvertOptions(
    val inputFormat: InputFormat = InputFormat.AUTO,
    val mode: ConversionMode = ConversionMode.FAST,
    val engine: Engine = Engine.AUTO,
    val clean: Boolean = true,
    val imageOcr: Boolean = false,
    val hybridOcr: Boolean = false,
    val responseFormat: ResponseFormat = ResponseFormat.MARKDOWN,
    val slim: Boolean = true,
    val pages: String? = null,
    val outputUrl: String? = null,
    val outputEncoding: OutputEncoding = OutputEncoding.IDENTITY,
    val outputHeadUrl: String? = null,
    val autoPoll: Boolean = true,
)
```

```kotlin theme={null}
// Example: just change mode
val options = ConvertOptions(mode = ConversionMode.BALANCED)
```

### Enums

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

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

## Methods (all `suspend`)

### `convertFile`

```kotlin theme={null}
suspend fun convertFile(
    file: File,
    options: ConvertOptions = ConvertOptions(),
): ConvertResult
```

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

### `convertBytes`

```kotlin theme={null}
suspend fun convertBytes(
    data: ByteArray,
    filename: String,
    options: ConvertOptions = ConvertOptions(),
): ConvertResult
```

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

### `convertFromUrl`

```kotlin theme={null}
suspend fun convertFromUrl(
    url: String,
    filename: String? = null,
    options: ConvertOptions = ConvertOptions(),
): ConvertResult
```

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

### `pdfIndex`

```kotlin theme={null}
suspend fun pdfIndex(url: String, filename: String? = null): JsonObject
```

Call `POST /pdf/index`. Returns a `kotlinx.serialization.json.JsonObject` with the spine — `pageCount`, `sections`, `fontModel`, etc.

```kotlin theme={null}
val spine = client.pdfIndex("https://bucket.example.com/report.pdf?sig=...")
val sections = spine["sections"]!!.jsonArray
for (section in sections) {
    println(section.jsonObject["text"])
}
```

### `getJob`

```kotlin theme={null}
suspend fun getJob(jobId: String): Job
```

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

### `waitForJob`

```kotlin theme={null}
suspend fun waitForJob(
    jobId: String,
    pollInterval: Duration = 5.seconds,
    timeout: Duration? = null,
): Job
```

Polls from `GET /jobs/{id}` (using `kotlinx.coroutines.delay`, without blocking the thread) until `completed`/`failed` or until `timeout` is exhausted. `Duration` is `kotlin.time.Duration`.

## `ConvertResult`

Sealed class with three subtypes — uses `when` exhaustive:

```kotlin theme={null}
sealed class ConvertResult {
    data class Markdown(val markdown: String) : ConvertResult()
    data class Json(val result: JsonResult) : ConvertResult()
    data class Queued(val job: Job) : ConvertResult()
}
```

```kotlin theme={null}
val markdown = when (val result = client.convertBytes(bytes, "report.pdf")) {
    is ConvertResult.Markdown -> result.markdown
    is ConvertResult.Json -> result.result.markdown
    is ConvertResult.Queued -> error("job en cola: ${result.job.jobId}")
}
```

## `JsonResult`

```kotlin theme={null}
data class JsonResult(
    val markdown: String,
    val filename: String,
    val inputFormat: String,
    val engine: String,
    val sizeBytes: Long,
    val markdownBytes: Long,
    val tokenSavedEstimate: Long,
    val timings: Timings,
)

data class Timings(
    val convertMs: Long,
    val cleanMs: Long,
    val totalWorkerMs: Long,
    val uploadMs: Long,
    val totalRequestMs: Long,
)
```

## `Job`

```kotlin theme={null}
data class Job(
    val jobId: String,
    val status: JobStatus, // enum: QUEUED, PROCESSING, COMPLETED, FAILED
    val body: JsonElement? = null,
    val error: String? = null,
)
```