Flipbook public API · V1
Embed published flipbooks anywhere.
The public API is read-only and CORS-enabled. It exposes published metadata, version manifests, and generated page images only—never source PDFs, drafts, editor identities, or storage keys.
Start with the current publication
Request metadata for a public ID to get its current version and canonical hosted viewer, iframe, and version manifest links. Public IDs are generated once and remain stable. Metadata and manifests use short caching with ETags so accessibility corrections can appear after publication. Version manifests and generated assets are public only while that version remains current.
curl --fail --silent \
http://localhost:3000/api/v1/flipbooks/A7k_2Xq-9Zcurl --fail --silent --location \
http://localhost:3000/api/v1/flipbooks/A7k_2Xq-9Z/manifestEndpoints
| Method | Path | Use |
|---|---|---|
| GET | /api/v1/flipbooks/{id} | Current metadata |
| GET | /api/v1/flipbooks/{id}/manifest | 307 to current version manifest |
| GET | /api/v1/flipbooks/{id}/versions/{version}/manifest | Current schema-v2 manifest |
| GET | /api/v1/flipbooks/{id}/versions/{version}/assets/{assetPath} | Current page or thumbnail asset |
| GET | /api/v1/openapi.json | OpenAPI 3.1 document |
Version access and caching
A version-numbered URL is not a permanent historical archive. Once a different version becomes current, the old manifest and asset routes return a non-cacheable 404 without reading object storage. Current metadata, redirects, manifests, and assets use a 60-second public cache lifetime and must be revalidated.
Generated files remain immutable in private storage. If an earlier deployment served them with a one-year immutable cache policy, purge any CDN caches during rollout. Copies already downloaded to a browser or another system cannot be recalled.
Iframe
Use /embed/{id} with theme, controls, startPage, and background query parameters.
<div style="position: relative; width: 100%; aspect-ratio: 4 / 3">
<iframe
src="http://localhost:3000/embed/A7k_2Xq-9Z?theme=auto&controls=1"
title="Summer catalog"
loading="lazy"
allowfullscreen
style="position: absolute; inset: 0; width: 100%; height: 100%; border: 0"
></iframe>
</div>The iframe sends versioned flipbook:ready, flipbook:pagechange, flipbook:resize, and flipbook:error messages. Send flipbook:next, flipbook:previous, or flipbook:goTo with the matching public ID and instance ID. Validate the iframe origin in parent code.
React
The internal package supports React 18 and 19, includes no tracking by default, and renders AVIF, WebP, and JPEG with <picture>.
import { FlipbookViewer } from "@flipbook/react";
import "@flipbook/react/styles.css";
export function Catalog() {
return <FlipbookViewer id="A7k_2Xq-9Z" apiBaseUrl="http://localhost:3000" />;
}