Converting documents over HTTP

01What it is

One HTTP front over the jexter document engine. Everything the engine can produce, it produces here — a target added to the engine appears on this API the same day, with nothing to wire on either side.

Nine routes, set out as plates below. Each plate has the same anatomy: the signature, one sentence of purpose, then what you can pass and what comes back. Learn it once, read any of them at a glance.

The difference between the two that matter is only how long you are willing to hold a connection open. Below a few dozen pages, convert. Above, submit a job: a 1000-page book takes about 40 seconds, which no proxy or load balancer will hold.

02Your key

Every route needs it except /api/health and /api/version, which stay open so monitoring can reach them. Two header forms, both accepted:

Authorization: Bearer <key>
X-API-Key: <key>

03Five minutes

Is it up?

curl https://sugarcloud.ch/api/health
ok

Which build answers?

curl https://sugarcloud.ch/api/version
{"name":"sugarcloud.ch","commit":"1a35bfb","built":"2026-10-22T10:09:01Z",
 "engine":{"version":"1.1.0","commit":"601255b","built":"2026-10-22T10:08:33Z"}}

Turn a PDF into an EPUB and save it:

curl -H "Authorization: Bearer $KEY" \
     --data-binary @book.pdf \
     "https://sugarcloud.ch/api/convert?to=epub" -o book.epub

The same book, as Markdown for an index or a search engine — change one word:

"https://sugarcloud.ch/api/convert?to=md" -o book.md

That is the whole API for a small document. The rest of this page is for big ones, and for knowing what went wrong.

04Convert, now

HTTP/1.1 200 OK
Content-Type: application/epub+zip
Content-Disposition: attachment; filename="document.epub"

An .ocd.epub is re-exported rather than re-imported, which is faster and lossless; an image (PNG, JPEG, TIFF) is read by OCR. The input is read, never declared — we look at the first bytes, so the content type does not have to be right.

05Convert, as a job

UID=$(curl -s -H "X-API-Key: $KEY" \
      --data-binary @book.pdf "https://sugarcloud.ch/api/jobs?to=epub" | jq -r .uid)

202  {"uid":"ffc0…","state":"QUEUED"}

{"uid":"ffc0…","state":"RUNNING","percent":42}
{"uid":"ffc0…","state":"DONE","percent":100,"filename":"book.epub","mediaType":"application/epub+zip"}

06In your code

The whole job loop — submit, poll, take the result, remove the job — as one function you can paste into your server. It runs as it stands against this service; only the key is yours, read from the environment (SUGARCLOUD_KEY). An error raises with the service's own message: 400: unknown target "epub3" (GET /api/targets).

Python — requests

import os, time, requests

API = "https://sugarcloud.ch/api"
KEY = {"X-API-Key": os.environ["SUGARCLOUD_KEY"]}    # from the server's configuration, never a page

def call(method, path, **kw):
    r = requests.request(method, API + path, headers=KEY, **kw)
    if r.status_code >= 400:
        raise RuntimeError(f"{r.status_code}: {r.json()['error']}")
    return r

def convert(path, to, **options):
    """A PDF, an image or an .ocd.epub in, the artifact out — as a job, whatever its size."""
    with open(path, "rb") as f:
        uid = call("POST", "/jobs", params={"to": to, **options}, data=f).json()["uid"]
    try:
        while True:
            job = call("GET", f"/jobs/{uid}").json()
            if job["state"] == "DONE":
                return call("GET", f"/jobs/{uid}/result").content
            if job["state"] in ("FAILED", "STALE"):
                raise RuntimeError(job.get("error") or job["state"])
            time.sleep(1)
    finally:
        try: call("DELETE", f"/jobs/{uid}")          # done with it; a weekly sweep takes what is left
        except RuntimeError: pass

open("book.epub", "wb").write(convert("book.pdf", "epub"))

Node 18 or later — fetch, nothing to install

import { readFile, writeFile } from 'node:fs/promises';

const API = 'https://sugarcloud.ch/api';
const KEY = { 'X-API-Key': process.env.SUGARCLOUD_KEY };  // from the server's config, never a page

async function call(method, path, body) {
  const res = await fetch(API + path, { method, body, headers: KEY });
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
  return res;
}

/** A PDF, an image or an .ocd.epub in, the artifact out — as a job, whatever its size. */
export async function convert(bytes, to, options = {}) {
  const query = new URLSearchParams({ to, ...options });
  const { uid } = await (await call('POST', `/jobs?${query}`, bytes)).json();
  try {
    for (;;) {
      const job = await (await call('GET', `/jobs/${uid}`)).json();
      if (job.state === 'DONE') {
        const result = await call('GET', `/jobs/${uid}/result`);
        return Buffer.from(await result.arrayBuffer());
      }
      if (job.state === 'FAILED' || job.state === 'STALE') throw new Error(job.error ?? job.state);
      await new Promise((r) => setTimeout(r, 1000));
    }
  } finally {
    await call('DELETE', `/jobs/${uid}`).catch(() => {});  // done with it; a sweep takes the rest
  }
}

await writeFile('book.md', await convert(await readFile('book.pdf'), 'md'));

Options are the query: convert("book.pdf", "pdf", selectable="true") in Python, convert(bytes, 'pdf', { selectable: 'true' }) in Node. For a short document /api/convert is one call instead, the same body and query, the bytes back.

07Targets

GET /api/targets is the authority — it lists what this deployment can produce today. At the time of writing:

08Options

GET /api/options returns the registry itself — key, label, help, type and default — so a UI can build itself and a client never guesses. Every query parameter other than to is passed straight to the engine.

09Errors

One shape, on every route:

{"error":"unknown target \"epub3\" (GET /api/targets)"}

A failed job carries the same text in its error field.

10Limits

What this deployment holds to. None of it is a page count: a book is the unit.

A key, or a limit that does not fit your documents: contact [at] sugarcube.ch.