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

> markpdf-cpp classes, methods and options.

# Referencia

## `markpdf::Client`

```cpp theme={null}
#include <markpdf/client.hpp>

markpdf::ClientOptions opts;
opts.apiKey = "YOUR_API_KEY";                  // or MARKPDF_API_KEY environment variable if omitted
opts.baseUrl = "https://api.markpdf.tech";  // optional, production default
opts.timeoutMs = 300000;                     // default 300000 (5 min)
opts.maxRetries = 2;                         // reintentos en 429/5xx

markpdf::Client client(opts);
// or, for the simple case:
markpdf::Client client2("YOUR_API_KEY");
```

<ParamField body="apiKey" type="std::string" required>
  Your API key. If omitted, the constructor reads `MARKPDF_API_KEY` from the environment; throws `std::runtime_error` under construction if neither exists.
</ParamField>

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

<ParamField body="timeoutMs" type="long" default="300000">
  Timeout per request in milliseconds (`CURLOPT_TIMEOUT_MS`).
</ParamField>

<ParamField body="maxRetries" type="int" default="2">
  Automatic retries with exponential backoff in `429` and `5xx`.
</ParamField>

`markpdf::Client` is not copyable but it is movable. It is safe to share an instance between threads for read-only calls (`getJob`, `pdfIndex`); for concurrent conversions, each thread reuses its own `curl easy handle` internally via a pool.

## `ConvertOptions`

Struct shared by `convertFile`, `convertFromUrl` and `convertStream`, with the same 1:1 mapping to the [query params of API](/docs/api/parameters):

```cpp theme={null}
struct ConvertOptions {
    std::string filename;
    InputFormat inputFormat = InputFormat::Auto;
    Mode mode = Mode::Fast;
    Engine engine = Engine::Auto;
    bool clean = true;
    bool imageOcr = false;
    bool hybridOcr = false;
    ResponseFormat responseFormat = ResponseFormat::Markdown;
    std::optional<std::string> pages;
    std::optional<std::string> outputUrl;
    OutputEncoding outputEncoding = OutputEncoding::Identity;
    std::optional<std::string> outputHeadUrl;
    bool autoPoll = true;
};
```

The enums (`InputFormat`, `Mode`, `Engine`, `ResponseFormat`, `OutputEncoding`) are serialized to the same string values ​​as documented by API — see [Parameters](/docs/api/parameters).

## Methods

### `convertFile`

```cpp theme={null}
Result<ConversionResult, MarkpdfError>
Client::convertFile(const std::string& path, const ConvertOptions& opts = {});
```

Upload a local file to `POST /convert/raw`.

<ParamField body="opts.autoPoll" type="bool" default="true">
  If the server responds `202`, the client blocks the current thread and polls from `GET /jobs/{id}` to `completed`/`failed`. With `autoPoll = false`, `convertFile` returns an error of type `JobQueued` with `jobId` for manual poll. See [Streaming and async](/docs/sdks/cpp/streaming-and-async).
</ParamField>

### `convertFromUrl`

```cpp theme={null}
Result<ConversionResult, MarkpdfError>
Client::convertFromUrl(const std::string& url, const ConvertOptions& opts = {});
```

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

### `convertStream`

```cpp theme={null}
void Client::convertStream(
    const std::string& pathOrUrl,
    StreamSource source,                     // StreamSource::File o StreamSource::Url
    const std::function<void(std::string_view chunk)>& onChunk,
    const StreamOptions& opts = {}
);
```

Invokes `onChunk` synchronously for each fragment received from `POST /convert/stream` (or `/convert/stream-from-url`). There is no return value: the callback is executed in the same thread that calls `convertStream`, while the HTTP request is still in progress. See [Streaming and async](/docs/sdks/cpp/streaming-and-async).

```cpp theme={null}
struct StreamOptions {
    std::string filename;
    InputFormat inputFormat = InputFormat::Auto;
    bool clean = true;
    bool slim = true;
    StreamSlimStrategy strategy = StreamSlimStrategy::Sampled;
};
```

### `pdfIndex`

```cpp theme={null}
Result<PdfSpine, MarkpdfError>
Client::pdfIndex(const std::string& url, const std::string& filename = "");
```

Llama a `POST /pdf/index`.

### `getJob`

```cpp theme={null}
Result<JobStatus, MarkpdfError>
Client::getJob(const std::string& jobId);
```

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

## Return Types

### `ConversionResult`

```cpp theme={null}
struct Timings {
    int convertMs, cleanMs, totalWorkerMs, uploadMs, totalRequestMs;
};

struct ConversionResult {
    std::string markdown;
    std::string filename;
    std::string inputFormat;
    std::string engine;
    long sizeBytes;
    long markdownBytes;
    long tokenSavedEstimate;
    Timings timings;
};
```

### `PdfSpine`

```cpp theme={null}
struct Section { int page; int level; std::string text; };
struct PageInfo { int page; int chars; std::string firstLine; };

struct PdfSpine {
    int pageCount;
    long inputBytes;
    std::vector<Section> sections;
    std::vector<std::string> repeatedHeadersFooters;
    std::vector<PageInfo> pages;
    bool pagesTruncated;
    long estimatedTokensFull;
    long estimatedTokensSpineOnly;
};
```

### `JobStatus`

```cpp theme={null}
enum class JobState { Queued, Processing, Completed, Failed };

struct JobStatus {
    std::string jobId;
    JobState status;
    std::optional<std::string> body;   // presente si status == Completed
    std::optional<std::string> error;  // presente si status == Failed
};
```

## `Result<T, E>`

`markpdf::Result<T, E>` is a lightweight wrapper like `std::expected` (C++17 compatible):

```cpp theme={null}
auto result = client.convertFile("report.pdf");
if (result) {
    use(result.value());   // o *result
} else {
    handle(result.error()); // MarkpdfError
}
```

See [Error Handling](/docs/sdks/cpp/error-handling) for the details of `MarkpdfError`.