API reference

Flipbooker API v1.0.0

64 REST endpoints for flipbooks, subscribers, analytics, tracked links, branding and webhooks. Every request is authenticated with a workspace API key and scoped to that workspace.

Base URL: https://app.flipbooker.com/api/v1
Authentication: Authorization: Bearer wsk_live_…

Download OpenAPI 3.1 spec Read the guides

Books

GET/books

List flipbooks

Returns the workspace flipbooks, newest first. The collection is cursor-paginated.

books:read

Parameters

Parameter	Type	Details
filter[status]	string query	`publishdraftschedule`
filter[name]	string query	max 255 chars
sort	string query	`name-namecreated_at-created_atupdated_at-updated_atstatus-status`
cursor	string query	—
limit	integer query	1–200

Response `200`

Field	Type	Details
datareq	object[]	—
data.batch_id	string	—
data.billing_expires_at	string	Billing's, read-only. Set when paid access ends; grants a grace window and then an expired notice in the viewer rather than unpublishing. Exposed so a client can tell why a book is about to stop being readable, and which of the two it can change.
data.created_at	string	format: date-time
data.description	string	—
data.embed_code	string	—
data.expires_at	string	The customer's own expiry: settable here, and a hard unpublish when it passes.
data.external_catalog_id	integer	—
data.idreq	integer	—
data.namereq	string	—
data.page_countreq	integer	—
data.preview_url	string	—

Example request

curl https://app.flipbooker.com/api/v1/books \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

422 Validation failed

POST/books

Upload a PDF and create a flipbook

Accepts a multipart PDF upload and queues conversion. The response contains a batch ID to poll.

books:write

Request body `multipart/form-data`

Field	Type	Details
auto_links_enabled	boolean	—
filesreq	string[]	—
original_filename	string	max 255 chars
status	string	`draftpublish`

Example request

curl -X POST https://app.flipbooker.com/api/v1/books \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -F "files[][email protected]"

Error responses

422 Validation failed

POST/books/create-from-template

Create a flipbook from a template

Creates a flipbook using a catalog template.

books:write

Request body `application/json`

Field	Type	Details
contentreq	object[]	—
content.author	string	max 255 chars
content.categories	array	—
content.content	string	max 50000 chars
content.currency	string	max 10 chars
content.date	string	max 100 chars
content.description	string	max 50000 chars
content.excerpt	string	max 5000 chars
content.gallery	array	—
content.idreq	string	—
content.image	string	max 2048 chars format: uri
content.price	string	—
content.regular_price	string	—
content.sale_price	string	—
content.short_description	string	max 5000 chars
content.sku	string	max 255 chars
content.stock_status	string	max 100 chars
content.titlereq	string	max 500 chars
content.type	string	max 50 chars
content.url	string	max 2048 chars format: uri
metadata	object	—
metadata.currency	string	max 10 chars
metadata.currency_symbol	string	max 20 chars
metadata.site_name	string	max 255 chars
metadata.site_url	string	max 2048 chars format: uri
sourcereq	string	`wordpresswoocommerce`
source_typereq	string	`postsproducts`
template_id	integer	min 1

Response `201`

Field	Type	Details
datareq	object	—
data.bookreq	object	—
data.book.batch_id	string	—
data.book.billing_expires_at	string	Billing's, read-only. Set when paid access ends; grants a grace window and then an expired notice in the viewer rather than unpublishing. Exposed so a client can tell why a book is about to stop being readable, and which of the two it can change.
data.book.created_at	string	format: date-time
data.book.description	string	—
data.book.embed_code	string	—
data.book.expires_at	string	The customer's own expiry: settable here, and a hard unpublish when it passes.
data.book.external_catalog_id	integer	—
data.book.idreq	integer	—
data.book.namereq	string	—
data.book.page_countreq	integer	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/books/create-from-template \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"<object[]>","source":"wordpress","source_type":"posts"}'

Error responses

422 Validation failed

POST/books/konva

Create an editor flipbook

Creates a flipbook from editor content.

books:write

Request body `application/json`

Field	Type	Details
canvasreq	object	—
canvas.heightreq	integer	1–10000
canvas.objectsreq	string[][]	—
canvas.orientationreq	string	`portraitlandscape`
canvas.widthreq	integer	1–10000
page_imagesreq	string[]	—
settings	object	—
settings.allow_fullscreen	boolean	—
settings.animation_type	string	max 255 chars
settings.auto_links_enabled	boolean	—
settings.background	string	max 2048 chars
settings.copyright_enabled	boolean	Not accepted: these books are built from page images, so there is no source PDF to offer and downloadable_pdf is forced to false when the record is created. Validating it here advertised a setting the endpoint has never honoured. Removed from the contract rather than made `prohibited`, because a caller sending a meaningless field should not start failing — it is simply not part of the request.
settings.domains_enabled	boolean	—
settings.eod_enabled	boolean	—
settings.flip_sound	boolean	—
settings.image_display	string	max 255 chars
settings.mobile_animation_type	string	max 255 chars
settings.pdf_password	string	max 255 chars
settings.pdf_privacy_status	string	max 50 chars
settings.share_social_media	boolean	—
status	string	`draftpublish`
thumbnail	string	max 22020096 chars
titlereq	string	max 255 chars

Example request

curl -X POST https://app.flipbooker.com/api/v1/books/konva \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"canvas":"<object>","page_images":"<string[]>","title":"<string>"}'

Error responses

422 Validation failed

GET/books/uploads/status/active

List active uploads

Returns upload batches that are still converting.

books:read

Example request

curl https://app.flipbooker.com/api/v1/books/uploads/status/active \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/books/uploads/{batchId}/status

Get upload status

Returns conversion progress for one upload batch.

books:read

Parameters

Parameter	Type	Details
batchIdreq	string path	—

Example request

curl https://app.flipbooker.com/api/v1/books/uploads/<batchId>/status \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/books/{book}

Retrieve a flipbook

Fetches a single flipbook by its numeric ID.

books:read

Parameters

Parameter	Type	Details
bookreq	integer path	The book ID

Response `200`

Field	Type	Details
datareq	object	—
data.batch_id	string	—
data.billing_expires_at	string	Billing's, read-only. Set when paid access ends; grants a grace window and then an expired notice in the viewer rather than unpublishing. Exposed so a client can tell why a book is about to stop being readable, and which of the two it can change.
data.created_at	string	format: date-time
data.description	string	—
data.embed_code	string	—
data.expires_at	string	The customer's own expiry: settable here, and a hard unpublish when it passes.
data.external_catalog_id	integer	—
data.idreq	integer	—
data.namereq	string	—
data.page_countreq	integer	—
data.preview_url	string	—

Example request

curl https://app.flipbooker.com/api/v1/books/<book> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

DELETE/books/{book}

Delete a flipbook

Permanently deletes a flipbook and its generated assets.

books:write

Parameters

Parameter	Type	Details
bookreq	integer path	The book ID

Response `200`

Field	Type	Details
datareq	object	—
data.messagereq	string	—
metareq	string	—

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/books/<book> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

PUT/books/{id}

Update flipbook settings

Updates the supplied flipbook metadata and viewer settings. The eod_enabled and domains_enabled flags this flipbook reports are read-only and ignored here: each is derived from an access list, so adding the first entry turns it on and removing the last turns it off. Change the lists through /v1/subscribers for reader access and /v1/books/{book}/embed-domains for embedding.

books:write

Parameters

Parameter	Type	Details
idreq	string path	—

Request body `application/json`

Field	Type	Details
allow_fullscreen	boolean	—
animation_type	string	`flipscroll_viewslidefadezoomflick-throughcut`
auto_links_enabled	boolean	—
background	string	max 2048 chars
copyright_enabled	boolean	—
description	string	max 50000 chars
domain_lists	array	—
downloadable_pdf	boolean	—
eod_lists	array	—
expires_at	string	format: date-time
flip_sound	boolean	—
image_display	string	`repeatcenter/cover`
magic_link_error_message	string	max 1000 chars
magic_link_message	string	max 1000 chars
mobile_animation_type	string	`flipscroll_viewslidefadezoomflick-throughcut`
pdf_password	string	max 255 chars
pdf_privacy_status	string	max 50 chars
published_date	string	format: date-time
share_social_media	boolean	—
slug	string	max 255 chars
statusreq	string	`draftschedulepublish`
title	string	max 255 chars
watermark	string	max 2048 chars

Response `200`

Field	Type	Details
datareq	object	—
data.batch_id	string	—
data.billing_expires_at	string	Billing's, read-only. Set when paid access ends; grants a grace window and then an expired notice in the viewer rather than unpublishing. Exposed so a client can tell why a book is about to stop being readable, and which of the two it can change.
data.created_at	string	format: date-time
data.description	string	—
data.embed_code	string	—
data.expires_at	string	The customer's own expiry: settable here, and a hard unpublish when it passes.
data.external_catalog_id	integer	—
data.idreq	integer	—
data.namereq	string	—
data.page_countreq	integer	—
data.preview_url	string	—

Example request

curl -X PUT https://app.flipbooker.com/api/v1/books/<id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"draft"}'

Error responses

400 Bad request404 Not found422 Validation failed

Batches

GET/batches/{batchId}

Retrieve a batch

Returns the status of an upload batch and the books it produced.

books:read

Parameters

Parameter	Type	Details
batchIdreq	string path	—

Response `200`

Field	Type	Details
datareq	object	—
data.booksreq	object[]	—
data.books.batch_id	string	—
data.books.billing_expires_at	string	Billing's, read-only. Set when paid access ends; grants a grace window and then an expired notice in the viewer rather than unpublishing. Exposed so a client can tell why a book is about to stop being readable, and which of the two it can change.
data.books.created_at	string	format: date-time
data.books.description	string	—
data.books.embed_code	string	—
data.books.expires_at	string	The customer's own expiry: settable here, and a hard unpublish when it passes.
data.books.external_catalog_id	integer	—
data.books.idreq	integer	—
data.books.namereq	string	—
data.books.page_countreq	integer	—

Example request

curl https://app.flipbooker.com/api/v1/batches/<batchId> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

DELETE/batches/{batchId}

Cancel an upload batch

Cancels an upload batch that is still in flight.

books:write

Parameters

Parameter	Type	Details
batchIdreq	string path	—

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/batches/<batchId> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Subscribers

GET/subscribers

List subscribers

Returns subscribers captured across the workspace flipbooks.

subscribers:read

Parameters

Parameter	Type	Details
pagination[per_page]	integer query	1–200
pagination[rowsPerPage]	integer query	1–200
pagination[page]	integer query	min 1
filter	string query	—
type	string query	`emaildomain`

Response `200`

Field	Type	Details
datareq	object[]	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/subscribers \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

422 Validation failed

POST/subscribers

Create a subscriber

Grants a reader access to a gated flipbook.

subscribers:write

Request body `application/json`

Field	Type	Details
book_idreq	integer	—
emailreq	string	max 255 chars format: email
type	string	`emaildomain`

Example request

curl -X POST https://app.flipbooker.com/api/v1/subscribers \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"book_id":"<integer>","email":"<string>"}'

Error responses

422 Validation failed

DELETE/subscribers/{subscriber}

Revoke a subscriber

Removes a reader from a flipbook's access list. The entry may be an address or a domain, and removing the last one turns the flipbook's email gate off.

subscribers:write

Parameters

Parameter	Type	Details
subscriberreq	integer path	—

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/subscribers/<subscriber> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

Analytics

GET/analytics/audit-log

Get the analytics audit log

Returns a chronological record of analytics events.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
viewer_id	integer query	—
event_type	string query	`access_requestedaccess_grantedaccess_rejecteddocument_downloadedlink_clickedlead_form_submittedform_widget_openedcheckout_widget_opened+1 more`
date	string query	—
tracked_link_id	integer query	—
limit	integer query	1–500
cursor	string query	—

Response `200`

Field	Type	Details
datareq	object[]	—
data.active_ms	integer	—
data.active_seconds	number	—
data.book_idreq	integer	—
data.event_typereq	string	—
data.idreq	string	—
data.metadatareq	object \| string	—
data.occurred_at	string	—
data.page_number	integer	—
data.reasonreq	string	—
data.sourcereq	string	—
data.source_event_idreq	integer	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/audit-log?book_id=<book_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/book-flow

Get reading flow

Returns page-to-page reader transitions for a flipbook.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
date	string query	—
tracked_link_id	integer query	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/book-flow?book_id=<book_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/book-view-events

List view events

Returns raw per-reader flipbook view events.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
date	string query	—
limit	integer query	1–500
cursor	string query	—
source_host	string query	max 255 chars
viewer_id	integer query	—
tracked_link_id	integer query	—

Response `200`

Field	Type	Details
datareq	object[]	—
data.book_idreq	integer	—
data.book_title	string	—
data.city	string	—
data.clicksreq	integer	—
data.country	string	—
data.duration_secondsreq	integer	—
data.engagement_scorereq	string	—
data.from_embeddedreq	boolean	—
data.idreq	integer	—
data.impressionsreq	integer	—
data.latitude	number	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/book-view-events?book_id=<book_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/interaction-events

List interaction events

Returns raw reader interaction events such as clicks, plays and downloads.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
viewer_id	integer query	—
event_type	string query	`session_startedpage_segment_completedlink_clickeddocument_downloadedlead_form_submittedform_widget_openedcheckout_widget_openedcheckout_redirect_clicked+1 more`
page_number	integer query	min 1
session_id	string query	max 255 chars
date	string query	—
tracked_link_id	integer query	—
limit	integer query	1–500
cursor	string query	—

Response `200`

Field	Type	Details
datareq	object[]	—
data.active_ms	integer	—
data.active_seconds	number	—
data.book_idreq	integer	—
data.city	string	—
data.country	string	—
data.created_atreq	string	—
data.event_typereq	string	—
data.exit_reasonreq	string	—
data.idreq	integer	—
data.latitude	number	—
data.longitude	number	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/interaction-events?book_id=<book_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/page-performance

Summarise page performance

Returns aggregate engagement for each page.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
date	string query	—
tracked_link_id	integer query	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/page-performance?book_id=<book_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/reader-journey

Get a reader's journey

Returns the ordered timeline for one reader across sessions.

analytics:read Company plan

Parameters

Parameter	Type	Details
viewer_id	integer query	—
session_id	string query	max 255 chars
date	string query	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/reader-journey \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/reader-pages

Summarise readers by page

Returns per-reader, per-page engagement.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
viewer_id	integer query	—
session_id	string query	max 255 chars
date	string query	—
tracked_link_id	integer query	—
page_number	integer query	min 1

Example request

curl https://app.flipbooker.com/api/v1/analytics/reader-pages?book_id=<book_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/readers

Summarise readers

Returns one engagement summary per reader.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
viewer_id	integer query	—
session_id	string query	max 255 chars
include_anonymous	boolean query	—
date	string query	—
sort	string query	`recentengagement`
tracked_link_id	integer query	—
limit	integer query	1–500
cursor	string query	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/readers?book_id=<book_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

GET/analytics/reading-session-pages

Summarise sessions by page

Returns page-level detail within each reading session.

analytics:read Company plan

Parameters

Parameter	Type	Details
book_idreq	integer query	—
view_event_idreq	integer query	—

Response `200`

Field	Type	Details
datareq	string	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/analytics/reading-session-pages?book_id=<book_id>&view_event_id=<view_event_id> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden422 Validation failed

Exports

GET/exports/analytics/{bookId}

Export analytics

Downloads a flipbook analytics summary as a CSV file.

exports:read Company plan

Parameters

Parameter	Type	Details
bookIdreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/analytics/<bookId> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/exports/books/{bookId}/access-audit

Export the access audit

Downloads the flipbook access audit as CSV.

exports:read Company plan

Parameters

Parameter	Type	Details
bookIdreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/books/<bookId>/access-audit \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/exports/books/{bookId}/leads

Export leads

Downloads captured lead form submissions as CSV.

exports:read

Parameters

Parameter	Type	Details
bookIdreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/books/<bookId>/leads \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/exports/books/{id}/audit-log

Export the audit log

Downloads the analytics audit log as CSV.

exports:read Company plan

Parameters

Parameter	Type	Details
idreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/books/<id>/audit-log \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/exports/books/{id}/interaction-events

Export interaction events

Downloads raw reader interaction events as CSV.

exports:read Company plan

Parameters

Parameter	Type	Details
idreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/books/<id>/interaction-events \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/exports/books/{id}/page-performance

Export page performance

Downloads aggregate page engagement as CSV.

exports:read Company plan

Parameters

Parameter	Type	Details
idreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/books/<id>/page-performance \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/exports/books/{id}/reader-pages

Export reader page summaries

Downloads per-reader, per-page engagement as CSV.

exports:read Company plan

Parameters

Parameter	Type	Details
idreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/books/<id>/reader-pages \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/exports/books/{id}/readers

Export reader summaries

Downloads per-reader engagement summaries as CSV.

exports:read Company plan

Parameters

Parameter	Type	Details
idreq	integer path	—

Example request

curl https://app.flipbooker.com/api/v1/exports/books/<id>/readers \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Tracked links

GET/books/{book}/tracked-links

List tracked links

Returns the tracked links configured on a flipbook and their click counts.

tracked-links:read

Parameters

Parameter	Type	Details
bookreq	integer path	The book ID

Response `200`

Field	Type	Details
datareq	object	—
data.tracked_linksreq	string[]	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/books/<book>/tracked-links \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

POST/books/{book}/tracked-links

Create a tracked link

Adds a tracked link so clicks can be attributed to a reader.

tracked-links:write

Parameters

Parameter	Type	Details
bookreq	integer path	The book ID

Request body `application/json`

Field	Type	Details
channel	string	max 64 chars
kind	string	`manualsystem`
metadata	array	—
namereq	string	max 255 chars
slug	string	max 64 chars

Response `201`

Field	Type	Details
datareq	object	—
data.tracked_linkreq	object	—
data.tracked_link.book_id	integer	—
data.tracked_link.clicksreq	integer	—
data.tracked_link.created_atreq	string	—
data.tracked_link.destination_urlreq	string	—
data.tracked_link.idreq	integer	—
data.tracked_link.legacy_urlreq	string	—
data.tracked_link.metadata	array	—
data.tracked_link.namereq	string	—
data.tracked_link.qr_urlreq	string	—
data.tracked_link.slugreq	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/books/<book>/tracked-links \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>"}'

Error responses

404 Not found422 Validation failed

DELETE/books/{book}/tracked-links/{trackedLink}

Delete a tracked link

Removes a tracked link. Existing clicks are retained.

tracked-links:write

Parameters

Parameter	Type	Details
bookreq	integer path	The book ID
trackedLinkreq	integer path	The tracked link ID

Response `200`

Field	Type	Details
datareq	object	—
data.messagereq	string	—
metareq	string	—

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/books/<book>/tracked-links/<trackedLink> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

Brand

GET/brand

Retrieve the brand

Returns the workspace brand and public flipbook styling.

brand:read

Response `200`

Field	Type	Details
datareq	object	—
data.brandreq	object	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/brand \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

POST/brand

Create the brand

Creates the workspace brand record.

brand:write

Request body `multipart/form-data`

Field	Type	Details
about_brand	string	—
company_namereq	string	—
contact_number	string	—
facebook	string	—
file	string	max 2048 chars format: binary
google_analytics	string	—
instagram	string	—
linkedin	string	—
pinterest	string	—
primary_color	string	—
secondary_color	string	—
tertiary_color	string	—
twitter	string	—
website_url	string	format: uri
youtube	string	—

Response `201`

Field	Type	Details
datareq	object	—
data.brandreq	object	—
data.brand.about_brand	string	—
data.brand.brand_color	object	—
data.brand.brand_social_media	object	—
data.brand.company_name	string	—
data.brand.contact_number	string	—
data.brand.created_at	string	format: date-time
data.brand.google_analytics	string	—
data.brand.idreq	integer	—
data.brand.logo	string	—
data.brand.take_over_brandingreq	boolean	POST /v1/toggle-take-over-branding flips this and returns a BrandResource that could not show the value it had just changed, so two calls and no calls looked identical. The internal BrandResource has always exposed it.

Example request

curl -X POST https://app.flipbooker.com/api/v1/brand \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -F "company_name=<string>" \
  -F "[email protected]"

Error responses

403 Forbidden422 Validation failed

PUT/brand

Update the brand

Updates the supplied workspace brand fields.

brand:write

Request body `multipart/form-data`

Field	Type	Details
about_brand	string	—
company_namereq	string	—
contact_number	string	—
facebook	string	—
file	string	max 2048 chars format: binary
google_analytics	string	—
idreq	integer	—
instagram	string	—
linkedin	string	—
pinterest	string	—
primary_color	string	—
secondary_color	string	—
tertiary_color	string	—
twitter	string	—
website_url	string	format: uri
youtube	string	—

Response `200`

Field	Type	Details
datareq	object	—
data.brandreq	object	—
metareq	string	—

Example request

curl -X PUT https://app.flipbooker.com/api/v1/brand \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -F "company_name=<string>" \
  -F "[email protected]" \
  -F "id=<integer>"

Error responses

403 Forbidden422 Validation failed

POST/toggle-take-over-branding

Toggle branding takeover

Turns workspace branding takeover on or off for public flipbook pages.

brand:write

Response `200`

Field	Type	Details
datareq	object	—
data.brandreq	object	—
data.brand.about_brand	string	—
data.brand.brand_color	object	—
data.brand.brand_social_media	object	—
data.brand.company_name	string	—
data.brand.contact_number	string	—
data.brand.created_at	string	format: date-time
data.brand.google_analytics	string	—
data.brand.idreq	integer	—
data.brand.logo	string	—
data.brand.take_over_brandingreq	boolean	POST /v1/toggle-take-over-branding flips this and returns a BrandResource that could not show the value it had just changed, so two calls and no calls looked identical. The internal BrandResource has always exposed it.

Example request

curl -X POST https://app.flipbooker.com/api/v1/toggle-take-over-branding \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

403 Forbidden404 Not found

Webhooks

GET/webhook-subscriptions

List webhook subscriptions

Returns the workspace webhook subscriptions and their event filters.

webhooks:read

Response `200`

Field	Type	Details
datareq	string[]	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

POST/webhook-subscriptions

Create a webhook subscription

Subscribes an endpoint to one or more analytics events.

webhooks:write

Response `201`

Field	Type	Details
datareq	object	—
data.created_atreq	string	—
data.deliveries_countreq	integer	—
data.event_typesreq	object[]	—
data.filtersreq	object[]	—
data.has_signing_secretreq	boolean	—
data.idreq	integer	—
data.is_activereq	boolean	—
data.namereq	string	—
data.providerreq	string	—
data.target_urlreq	string	—
data.updated_atreq	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/webhook-subscriptions/options

List webhook filter options

Returns workspace flipbooks, tracked links, event types and providers for configuring a webhook subscription.

webhooks:read

Response `200`

Field	Type	Details
datareq	object	—
data.booksreq	string[]	—
data.event_typesreq	object[]	—
data.event_types.labelreq	string	—
data.event_types.valuereq	string	—
data.providersreq	object[]	—
data.providers.labelreq	string	—
data.providers.valuereq	string	—
data.tracked_linksreq	string[]	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/webhook-subscriptions/options \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/webhook-subscriptions/sample-events

List sample webhook events

Returns recent workspace webhook payloads for configuring an integration before its subscription exists.

webhooks:read

Parameters

Parameter	Type	Details
event_types	string query	—

Response `200`

Field	Type	Details
datareq	string[]	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/webhook-subscriptions/sample-events \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

PUT/webhook-subscriptions/{subscription}

Update a webhook subscription

Changes a subscription target URL or event list.

webhooks:write

Parameters

Parameter	Type	Details
subscriptionreq	integer path	The subscription ID

Response `200`

Field	Type	Details
datareq	object	—
data.created_atreq	string	—
data.deliveries_countreq	integer	—
data.event_typesreq	object[]	—
data.filtersreq	object[]	—
data.has_signing_secretreq	boolean	—
data.idreq	integer	—
data.is_activereq	boolean	—
data.namereq	string	—
data.providerreq	string	—
data.target_urlreq	string	—
data.updated_atreq	string	—

Example request

curl -X PUT https://app.flipbooker.com/api/v1/webhook-subscriptions/<subscription> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

DELETE/webhook-subscriptions/{subscription}

Delete a webhook subscription

Removes a subscription while preserving its delivery history.

webhooks:write

Parameters

Parameter	Type	Details
subscriptionreq	integer path	The subscription ID

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/webhook-subscriptions/<subscription> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

GET/webhook-subscriptions/{subscription}/deliveries

List webhook deliveries

Returns recent delivery attempts and response statuses.

webhooks:read

Parameters

Parameter	Type	Details
subscriptionreq	integer path	The subscription ID

Response `200`

Field	Type	Details
datareq	string[]	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/webhook-subscriptions/<subscription>/deliveries \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

POST/webhook-subscriptions/{subscription}/test

Test a webhook subscription

Sends a test delivery to a subscription endpoint.

webhooks:write

Parameters

Parameter	Type	Details
subscriptionreq	integer path	The subscription ID

Response `202`

Field	Type	Details
datareq	object	—
data.attemptsreq	integer	—
data.created_atreq	string	—
data.delivered_atreq	string	—
data.error_message	string	—
data.event_idreq	string	—
data.event_typereq	string	—
data.idreq	integer	—
data.payloadreq	object[]	—
data.response_body	string	—
data.response_status	integer	—
data.statusreq	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/webhook-subscriptions/<subscription>/test \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

POST/webhooks

Send a sample webhook

Dispatches a sample event to a URL so you can verify a webhook endpoint.

webhooks:write

Request body `application/json`

Field	Type	Details
event	string	`flipbook.createdflipbook.updatedsubscriber.added`
payload	array	—
url	string	max 2048 chars format: uri

Response `202`

Field	Type	Details
datareq	object	—
data.eventreq	string	—
data.messagereq	string	—
data.payloadreq	object[]	—
data.target_urlreq	string	—
metareq	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/webhooks \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Error responses

422 Validation failed502 Delivery failed

Catalogs

GET/catalogs

List catalogs

Returns product catalogs in the workspace.

catalogs:read

Parameters

Parameter	Type	Details
limit	string query	default: 25

Response `200`

Field	Type	Details
datareq	object[]	—
data.created_atreq	string	—
data.external_id	string	—
data.idreq	integer	—
data.last_sync_error	string	—
data.last_sync_status	string	—
data.last_synced_atreq	string	—
data.metadata	array	—
data.namereq	string	—
data.sourcereq	string	—
data.source_url	string	—
data.statusreq	string	—

Example request

curl https://app.flipbooker.com/api/v1/catalogs \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

POST/catalogs

Create a catalog

Creates a product catalog.

catalogs:write

Request body `application/json`

Field	Type	Details
external_id	string	max 255 chars
metadata	array	—
namereq	string	max 255 chars
source	string	`woocommercewordpressshopifyecwidcustom`
source_url	string	max 2048 chars format: uri
template_key	string	—

Response `202`

Field	Type	Details
datareq	object	—
data.catalogreq	object	—
data.catalog.created_atreq	string	—
data.catalog.external_id	string	—
data.catalog.idreq	integer	—
data.catalog.last_sync_error	string	—
data.catalog.last_sync_status	string	—
data.catalog.last_synced_atreq	string	—
data.catalog.metadata	array	—
data.catalog.namereq	string	—
data.catalog.sourcereq	string	—
data.catalog.source_url	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/catalogs \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>"}'

Error responses

422 Validation failed

GET/catalogs/{catalog}

Retrieve a catalog

Returns one product catalog and its metadata.

catalogs:read

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID

Response `200`

Field	Type	Details
datareq	object	—
data.catalogreq	object	—
data.catalog.created_atreq	string	—
data.catalog.external_id	string	—
data.catalog.idreq	integer	—
data.catalog.last_sync_error	string	—
data.catalog.last_sync_status	string	—
data.catalog.last_synced_atreq	string	—
data.catalog.metadata	array	—
data.catalog.namereq	string	—
data.catalog.sourcereq	string	—
data.catalog.source_url	string	—

Example request

curl https://app.flipbooker.com/api/v1/catalogs/<catalog> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

DELETE/catalogs/{catalog}

Delete a catalog

Deletes a product catalog.

catalogs:write

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID

Response `200`

Field	Type	Details
datareq	object	—
data.catalogreq	object	—
data.catalog.created_atreq	string	—
data.catalog.external_id	string	—
data.catalog.idreq	integer	—
data.catalog.last_sync_error	string	—
data.catalog.last_sync_status	string	—
data.catalog.last_synced_atreq	string	—
data.catalog.metadata	array	—
data.catalog.namereq	string	—
data.catalog.sourcereq	string	—
data.catalog.source_url	string	—

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/catalogs/<catalog> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

GET/catalogs/{catalog}/items

List catalog items

Returns the products in a catalog.

catalogs:read

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID
limit	string query	default: 25

Response `200`

Field	Type	Details
datareq	object[]	—
data.availability	array	—
data.available	boolean	—
data.catalog_idreq	integer	—
data.categories	array	—
data.created_atreq	string	—
data.currency	string	—
data.description	string	—
data.external_item_keyreq	string	—
data.external_product_idreq	string	—
data.external_variant_id	string	—
data.gallery	array	—

Example request

curl https://app.flipbooker.com/api/v1/catalogs/<catalog>/items \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

PATCH/catalogs/{catalog}/items/availability

Update catalog item availability

Updates availability for catalog items.

catalogs:write

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID

Request body `application/json`

Field	Type	Details
itemsreq	string[][]	—
snapshot_at	string	format: date-time

Response `202`

Field	Type	Details
datareq	object	—
data.summaryreq	object	—
data.summary.accepted_itemsreq	string	—
data.summary.errorsreq	string \| string[]	—
data.summary.failed_itemsreq	string	—
data.summary.statusreq	string	—
data.summary.total_itemsreq	string	—
data.sync_jobreq	object	—
data.sync_job.catalog_idreq	integer	—
data.sync_job.created_atreq	string	—
data.sync_job.errorsreq	object[]	—
data.sync_job.finished_atreq	string	—

Example request

curl -X PATCH https://app.flipbooker.com/api/v1/catalogs/<catalog>/items/availability \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":"<string[][]>"}'

Error responses

404 Not found422 Validation failed

DELETE/catalogs/{catalog}/items/{item}

Delete a catalog item

Removes an item from a catalog.

catalogs:write

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID
itemreq	integer path	The item ID

Response `200`

Field	Type	Details
datareq	object	—
data.messagereq	string	—
metareq	string	—

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/catalogs/<catalog>/items/<item> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

POST/catalogs/{catalog}/items:bulk-upsert

Bulk upsert catalog items

Creates or updates multiple catalog items in one request.

catalogs:write

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID

Request body `application/json`

Field	Type	Details
itemsreq	string[][]	—

Response `202`

Field	Type	Details
datareq	object	—
data.summaryreq	object	—
data.summary.accepted_itemsreq	string	—
data.summary.errorsreq	string \| string[]	—
data.summary.failed_itemsreq	string	—
data.summary.statusreq	string	—
data.summary.total_itemsreq	string	—
data.sync_jobreq	object	—
data.sync_job.catalog_idreq	integer	—
data.sync_job.created_atreq	string	—
data.sync_job.errorsreq	object[]	—
data.sync_job.finished_atreq	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/catalogs/<catalog>/items:bulk-upsert \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":"<string[][]>"}'

Error responses

404 Not found422 Validation failed

POST/catalogs/{catalog}/render

Render a catalog

Creates a flipbook from a product catalog.

catalogs:readbooks:write

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID

Request body `application/json`

Field	Type	Details
cover	object	—
cover.description	string	max 5000 chars
cover.title	string	max 255 chars
cover.website	string	max 2048 chars
items	string[]	—
settings	object	—
settings.allow_fullscreen	boolean	—
settings.animation_type	string	max 255 chars
settings.auto_links_enabled	boolean	—
settings.background	string	max 2048 chars
settings.copyright_enabled	boolean	Not accepted: these books are built from page images, so there is no source PDF to offer and downloadable_pdf is forced to false when the record is created. Validating it here advertised a setting the endpoint has never honoured. Removed from the contract rather than made `prohibited`, because a caller sending a meaningless field should not start failing — it is simply not part of the request.
settings.domains_enabled	boolean	—
settings.eod_enabled	boolean	—
settings.flip_sound	boolean	—
settings.image_display	string	max 255 chars
settings.mobile_animation_type	string	max 255 chars
settings.pdf_password	string	max 255 chars
settings.pdf_privacy_status	string	max 50 chars
settings.share_social_media	boolean	—
status	string	`draftpublish`
template_id	integer	min 1
title	string	max 255 chars

Example request

curl -X POST https://app.flipbooker.com/api/v1/catalogs/<catalog>/render \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Error responses

401 Unauthenticated404 Not found422 Validation failed

GET/catalogs/{catalog}/sync-jobs/{syncJob}

Retrieve a catalog sync job

Returns the status of a catalog synchronization job.

catalogs:read

Parameters

Parameter	Type	Details
catalogreq	integer path	The catalog ID
syncJobreq	integer path	The sync job ID

Response `200`

Field	Type	Details
datareq	object	—
data.sync_jobreq	object	—
data.sync_job.catalog_idreq	integer	—
data.sync_job.created_atreq	string	—
data.sync_job.errorsreq	object[]	—
data.sync_job.finished_atreq	string	—
data.sync_job.idreq	integer	—
data.sync_job.progressreq	object	—
data.sync_job.started_atreq	string	—
data.sync_job.statusreq	string	—
data.sync_job.typereq	string	—
data.sync_job.updated_atreq	string	—

Example request

curl https://app.flipbooker.com/api/v1/catalogs/<catalog>/sync-jobs/<syncJob> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

401 Unauthenticated404 Not found

GET/templates

List catalog templates

Returns the catalog templates available to the workspace.

catalogs:read

Parameters

Parameter	Type	Details
type	string query	max 64 chars

Response `200`

Field	Type	Details
datareq	object[]	—
data.idreq	string	—
data.is_defaultreq	boolean	—
data.namereq	string	—
data.thumbnailsreq	object	—
data.typereq	string	—
metareq	object	—
meta.default_template_idreq	string	—
meta.default_template_sourcereq	string	—

Example request

curl https://app.flipbooker.com/api/v1/templates \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

422 Validation failed

Integrations

POST/integrations/shopify/webhooks

Receive a Shopify product webhook

Processes a Shopify product data webhook for catalog synchronization.

catalogs:write

Request body `application/json`

Field	Type	Details
payloadreq	object	—
payload.customer	object	—
payload.customer.email	string	max 255 chars format: email
payload.customer.id	integer	—
payload.data_request	object	—
payload.data_request.id	integer	—
payload.shop_domainreq	string	max 255 chars
payload.shop_idreq	integer	—
shopDomainreq	string	max 255 chars
topicreq	string	`customers/data_requestcustomers/redactshop/redact`

Response `202`

Field	Type	Details
actionreq	string	—
countsreq	object	—
replayedreq	boolean	—
statusreq	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/integrations/shopify/webhooks \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":"<object>","shopDomain":"<string>","topic":"customers/data_request"}'

Error responses

401 Unauthenticated422 Validation failed

General

GET/health

Health check

Returns the API status and version.

Response `200`

Field	Type	Details
statusreq	string	—
timestampreq	string	—
versionreq	string	—

Example request

curl https://app.flipbooker.com/api/v1/health \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

GET/me

Describe the current connection

Returns the authenticated workspace, plan features and granted scopes so an integration can identify and configure its connection.

Example request

curl https://app.flipbooker.com/api/v1/me \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

400 Bad request401 Unauthenticated403 Forbidden

Embed domains

GET/books/{book}/embed-domains

List embed domains

Returns the websites allowed to embed this flipbook. Matching includes subdomains, so "example.com" also permits "docs.example.com".

books:read

Parameters

Parameter	Type	Details
bookreq	integer path	—

Response `200`

Field	Type	Details
datareq	object[]	—
data.created_atreq	string	—
data.domainreq	string	—
data.idreq	string	—
data.includes_subdomainsreq	boolean	—
metareq	string	—

Example request

curl https://app.flipbooker.com/api/v1/books/<book>/embed-domains \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

POST/books/{book}/embed-domains

Allow a website to embed

Adds a website to the flipbook embed allowlist. Accepts a bare host such as "example.com"; a pasted URL is reduced to its host. Adding the first entry turns the embedding restriction on.

books:write

Parameters

Parameter	Type	Details
bookreq	integer path	—

Request body `application/json`

Field	Type	Details
domainreq	string	max 255 chars

Response `200`

Field	Type	Details
datareq	object	—
data.created_atreq	string	—
data.domainreq	string	—
data.idreq	string	—
data.includes_subdomainsreq	boolean	—
metareq	string	—

Example request

curl -X POST https://app.flipbooker.com/api/v1/books/<book>/embed-domains \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"<string>"}'

Error responses

404 Not found422 Validation failed

DELETE/books/{book}/embed-domains/{embedDomain}

Stop a website embedding

Removes a website from the flipbook embed allowlist. Removing the last entry turns the embedding restriction off.

books:write

Parameters

Parameter	Type	Details
bookreq	integer path	—
embedDomainreq	integer path	—

Example request

curl -X DELETE https://app.flipbooker.com/api/v1/books/<book>/embed-domains/<embedDomain> \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Error responses

404 Not found

Books

List flipbooks

Parameters

Response 200

Error responses

Upload a PDF and create a flipbook

Request body multipart/form-data

Error responses

Create a flipbook from a template

Request body application/json

Response 201

Error responses

Create an editor flipbook

Request body application/json

Error responses

List active uploads

Get upload status

Parameters

Retrieve a flipbook

Parameters

Response 200

Error responses

Delete a flipbook

Parameters

Response 200

Error responses

Update flipbook settings

Parameters

Request body application/json

Response 200

Error responses

Batches

Retrieve a batch

Parameters

Response 200

Error responses

Cancel an upload batch

Parameters

Subscribers

List subscribers

Parameters

Response 200

Error responses

Create a subscriber

Request body application/json

Error responses

Revoke a subscriber

Parameters

Error responses

Analytics

Get the analytics audit log

Parameters

Response 200

Error responses

Get reading flow

Parameters

Error responses

List view events

Parameters

Response 200

Error responses

List interaction events

Parameters

Response 200

Error responses

Summarise page performance

Parameters

Error responses

Get a reader's journey

Parameters

Error responses

Summarise readers by page

Parameters

Error responses

Summarise readers

Parameters

Error responses

Summarise sessions by page

Parameters

Response 200

Response `200`

Request body `multipart/form-data`

Request body `application/json`

Response `201`

Request body `application/json`

Response `200`

Response `200`

Request body `application/json`

Response `200`

Response `200`

Response `200`

Request body `application/json`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Request body `application/json`

Response `201`

Response `200`

Response `200`

Request body `multipart/form-data`

Response `201`

Request body `multipart/form-data`

Response `200`

Response `200`

Response `200`

Response `201`

Response `200`

Response `200`