EPUB Validator & Publishing Preflight API

Turn one EPUB URL into a machine-readable publishing decision.

EPUB Preflight is an agent-first validation API for automated ebook publishing workflows.

It can run:

• native EPUB structural and publishing QA
• EPUBCheck 5.3.0
• DAISY Ace 1.4.6 accessibility checks
• deterministic safe fixes

The result tells an agent whether the EPUB is:

• ready — clean and ready to publish
• review — publishable, but warnings remain
• blocked — errors require repair

It also returns normalized issues, deduplicated root causes, repair metadata, and ordered next actions. Native QA includes conservative Kindle cover-risk warnings for SVG covers and PNG covers that declare alpha/transparency.

Pricing

Profile	Validation	Price
Native	Native EPUB Preflight checks	$0.01
Conformance	Native + EPUBCheck	$0.02
Full	Native + EPUBCheck + DAISY Ace	$0.05

Safe deterministic fixes and a repaired EPUB artifact are included when requested.

Only the custom validation profile event is charged on completed validations. Incomplete validation and operational failures do not incur the $0.01 / $0.02 / $0.05 profile event; the separately listed Apify Actor Start synthetic event may still apply.

Why use this instead of running EPUBCheck directly?

EPUBCheck remains the standards-focused validator inside the workflow.

EPUB Preflight adds the automation layer around it:

• one hosted API call
• no Java, Node.js, EPUBCheck, or Ace setup on the client
• unified machine-readable output
• ready / review / blocked release decisions
• root-cause grouping and cascade suppression
• agent-facing repair instructions and ordered next actions
• conservative automatic fixes where the correction is deterministic

It is designed to make EPUB validation easy to consume inside AI-agent and automated publishing pipelines.

Typical agent loop

build EPUB
    ↓
run EPUB Preflight
    ↓
READY ─────────→ publish
REVIEW ────────→ inspect warnings
BLOCKED ───────→ repair → rebuild → revalidate

For the shortest decision path, inspect:

validation_complete
status
publishable

If the EPUB is not ready, consume actionable_issues, root_causes, and next_actions instead of parsing validator prose.

Input

{
  "epubUrl": "https://example.com/book.epub",
  "applySafeFixes": false,
  "runEpubcheck": true,
  "runAce": true
}

epubUrl must be a public HTTP(S) URL. Private, loopback, link-local, and other non-public network targets are rejected. Downloads are limited to 100 MiB.

Supported validator combinations are Full (EPUBCheck + Ace), Conformance (EPUBCheck only), and Native (both external validators off). Ace without EPUBCheck is rejected so the executed validation stack always matches the advertised billing profile.

Output

The run exposes three output links:

• Full preflight result — the OUTPUT record in the default key-value store
• Run summary — one compact row in the default dataset
• Generated artifacts — a repaired EPUB when safe fixes changed the input

The full result preserves the normal EPUB Preflight envelope under preflight, while adding Actor-level request, download, and validator metadata.

A validator finding is not an Actor execution failure. Accessibility or conformance violations are returned normally in the unified result. Operational failures such as an invalid URL or failed download make the Actor run fail and write a structured OUTPUT record when possible.

Runtime

The Actor image pins:

• Python 3.11
• Java 17
• EPUBCheck 5.3.0 with verified release SHA-256
• Node.js 20
• DAISY Ace 1.4.6 using the headless ace-puppeteer runner
• Apify Python SDK 4.0.1

Launch memory is capped at 2048 MiB. Hosted Ace validation uses a 600-second subprocess budget.

Pay per event

The Actor uses three one-time custom events:

• native-preflight — $0.01
• conformance-preflight — $0.02
• full-preflight — $0.05

Safe fixes and repaired EPUB return are included in the selected profile price.

Only validation_complete=true outcomes trigger the custom profile event. ready, review, and blocked are all completed validation outcomes. The Apify Actor Start synthetic event is separate from this completion-based charge.

Agent REST reference

The hosted v0.6.1 contract has been verified end to end against the immutable production golden: raw Apify API execution returned ready with zero errors/warnings, and the dependency-free Python consumer at examples/apify_agent_client.py independently returned continue_release.

For automated publishing agents, prefer the asynchronous run/poll/fetch flow and read validation_complete before making any release decision.

The hosted safe-fix path has also been verified end to end: repaired EPUB bytes are stored as ARTIFACT_REPAIRED_EPUB and can be fetched by the reference client with --download-repaired.

See:

• docs/apify-agent-client.md
• docs/hosted-api-baseline.md
• docs/hosted-repaired-artifact-smoke.md