Skip to main content
Turn EPUB and MOBI ebooks into normalized text chunks. Horizon parses chapters and front/back matter to preserve structure for downstream retrieval and question-answering.

​
Request body

  • sourceUrl — HTTPS or signed URL pointing to the ebook archive. Required if file is not provided.
  • file — Optional uploaded EPUB or MOBI file (multipart/form-data).
  • sourceName — Optional label saved with the extracted records.
  • options — Optional object. Supported keys:
    • segmentLength — Target characters per chunk (default 1000).
    • includeTableOfContents — Boolean; append TOC entries to each chunk (default true).
    • language — ISO language hint for sentence segmentation.
  • webhookUrl — Optional HTTPS URL Horizon should call when the extraction finishes.

​
Sample request

curl https://api.worklet.cloud/v1/extract/ebook \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://cdn.example.com/library/field-guide.epub",
    "sourceName": "Field Guide to Horizon",
    "options": {
      "segmentLength": 1600,
      "includeTableOfContents": true,
      "language": "en"
    }
  }'

# or upload the raw EPUB/MOBI

curl https://api.worklet.cloud/v1/extract/ebook \
  -H "Content-Type: application/json" \
  -d '{
    "file": "data:application/epub+zip;base64,UEsDBBQAAAAIA...",
    "sourceName": "Field Guide to Horizon",
    "options": {
      "segmentLength": 1600,
      "includeTableOfContents": true,
      "language": "en"
    }
  }'

​
Response

Returns 202 Accepted with jobId, status, and statusUrl. When processing finishes quickly, the normalized chapter chunks appear in result.

​
Notes

  • Inline images are ignored; image captions are captured when present.
  • TOC entries are mapped into chunk attributes (chapter, section).
  • Use signed URLs that remain valid for several minutes; larger ebooks can take up to 5 minutes to process.
  • Poll GET /jobs/{jobId} (identical to statusUrl) if you need to check progress or refetch the normalized chunks.
  • To upload the ebook directly, send multipart/form-data with a file field instead of sourceUrl.

​
x402 flow

Ebook extraction is billed per archive through Coinbase’s x402 protocol. If funding is required, Horizon issues: 
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "160000",
      "resource": "POST /extract/ebook",
      "description": "Horizon ebook extraction",
      "mimeType": "application/json",
      "payTo": "0xYourReceivingWallet",
      "maxTimeoutSeconds": 300,
      "asset": "0xYourUSDCContract",
      "extra": {
        "name": "USDC",
        "version": "1"
      }
    }
  ],
  "error": null
}
Forward the accepts data to your facilitator, complete the /verify and /settle cycle, then retry the call with the Base64 payload in X-PAYMENT. Horizon resumes the job and includes X-PAYMENT-RESPONSE when settlement succeeds.