Karbone

Karbone is a Kotlin SDK for the Carbone.io document generation API.

It is meant as a modern, idiomatic and complete replacement for the official carbone-sdk-java, which has been left incomplete and dated: no coroutine support, no typed render options, string-typed errors, and only partial coverage of the API.

Karbone is in early development. The API is not stable yet.

Why Karbone?

• Typed everywhere. RenderOptions, OutputFormat and its PdfOptions / ImageOptions / CsvOptions, UploadOptions, TemplatePatch… all the fields Carbone accepts are Kotlin types with builders, not raw JSON maps.
• Errors as values. Every call is context(_: Raise<KarboneError>) suspend fun ..., built on Arrow’s Raise. No exceptions to catch, no silent nulls; KarboneError is a sealed hierarchy you can exhaustively when on. A synchronous, exception-throwing facade is available for Java and other non-coroutine callers. See Errors.
• Coroutine-first. Every network call is a suspend fun; pagination is exposed as a Flow.
• Hash-first rendering. Rendering from local bytes never requires a separate upload step: Karbone addresses the template by its SHA-256 and uploads on demand only if Carbone does not know it yet. See Rendering.
• On-premise first-class. Cloud and self-hosted carbone-ee are both first-class targets, with the differences (API versioning header, authentication, template management) handled explicitly rather than assumed away. See On-premise.
• Zero HTTP dependency. Built on the JDK’s own java.net.http.HttpClient, kotlinx.serialization for JSON, and arrow-core for errors — no OkHttp, Retrofit or Ktor client pulled into your dependency graph.

Where to go next

• Quickstart — install Karbone and render your first document.
• Configuration — KarboneConfig, timeouts, retries, logging.
• Rendering — template sources, render data, render options, sync vs async.
• Templates — upload, download, update, delete, list, categories and tags.
• Errors — the KarboneError hierarchy and how to handle it.
• On-premise — running and authenticating against a self-hosted carbone-ee.
• Testing — testing code that depends on Karbone with FakeKarbone.