API
Exports
Export a version as SVG, pictures, an HTML flipbook or an offline zip.
An export is a background job that turns one version into files: export-svg, export-images, export-flipbook (an HTML page) or export-offline (a zip that opens from disk). exports.request answers 202 at once. Poll exports.get or jobs.get until status is done, or wait for the export.completed webhook event, then fetch the file with exports.download.
Asking again for the same export of the same content returns the one already made or on its way, at no cost. Flipbook and offline exports are drawn in a look: profileId, else the document's look, else the workspace default, else the built-in look. The look is copied in, so later edits to it do not change the export.
Credits are taken when an export finishes. One that runs in the engine container is a heavy render of 5 to 25 credits by size; that is every flipbook and offline export, plus larger documents and higher resolutions. Every ten exports a month through the public API cost 1 more credit. A workspace whose credits are throttled is refused new container exports with 402 credits_required.
Export a version as SVG, pictures, an HTML page or an offline flipbook
POST /documents/{documentId}/exports exports.request
Queues the export, or returns the one already made or on its way for the same file and parameters (another version with the same bytes counts as the same file). Poll it with exports.get (or jobs.get) until status is done, then download its file with exports.download; the export.completed webhook event also says when it is ready.
Pages are 1-based; a range such as 1-3, 5 picks pages, and blank is every page. export-offline is a zip that opens from disk: the page, every page's file, and a fonts/ folder listing the fonts it names. export-svg embeds its pictures in each SVG, or, with images: link, writes each picture once into an images/ folder beside the SVGs, which link to it, in a zip.
Flipbook and offline exports are drawn in a look (profileId). Credits are taken when the export finishes: one that runs in the engine container (every flipbook and offline export, and larger documents or higher resolutions) is a heavy render, 5 to 25 credits by the document's size; and every ten exports made through the public API in a month, or part of ten, cost one credit more.
Asking again for an export already made or on its way costs nothing. When the way a type is made changes, the same export made earlier is no longer returned: asking again makes a new one at no cost (no credit check, no charge, and not counted among the API's exports), and the earlier one stays listed and downloadable.
A workspace whose credits are throttled is refused new exports that would run in the container (402 credits_required); other exports, and asking again for one already made, still work. A document with no version is 409 nothing_to_export, and an unknown version or profile is 404 not_found.
- Scopes
documents.read- Credits
- Some requests spend credits, as the description says: By the document's size: 5 up to 10 MiB, 10 up to 50 MiB, 15 up to 100 MiB, 20 up to 250 MiB, 25 above 250 MiB.
- Retries
- Safe with an
Idempotency-Key - MCP tool
exports_request
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
type required | string | SVG: one SVG file per page, or every page stacked in one. More than one file comes as a zip. One of export-svg, export-images, export-flipbook, export-offline. |
version | integer | The number of the version to export. Default the document's current version. Only when type is export-svg. At least 1. |
params | object | The SVG options. Each left out takes its default. Only when type is export-svg. |
params.text | string | outline draws glyphs as shapes; link writes them as text in a linked font, the workspace's own web fonts where it has them. Default outline. One of outline, link. Default outline. |
params.textLayer | boolean | Adds invisible, selectable text over outlined glyphs. Default false. Default false. |
params.dpi | number or integer | The resolution of the pictures inside each SVG, 72 to 600 DPI, or 0 to keep each picture's own pixels. Default 150. Default 150. |
params.imageFormat | string | How pictures are stored: auto uses JPEG for photographs and PNG for the rest. Default auto. One of auto, png, jpeg. Default auto. |
params.quality | number | Quality of JPEG pictures, 0.1 to 1. Default 0.85. 0.1 to 1. Default 0.85. |
params.layout | string | pages writes an SVG per page; single stacks every page in one SVG. Default pages. One of pages, single. Default pages. |
params.background | boolean | Paints each page white behind its content, as a PDF viewer does. Default true. Default true. |
params.pageGap | integer | Space between stacked pages in the single layout, in points. Default 8. 0 to 144. Default 8. |
params.pages | string | Which pages, as a print-dialog range of 1-based pages such as 1-3, 5, 8-. Blank, the default, is every page; pages past the end are dropped. Matches ^(?:\s*\d{1,6}\s*(?:-\s*(?:\d{1,6}\s*)?)?(?:,|$))*$. At most 500 characters. Default ``. |
params.split | object | Cut pages in half. Absent cuts nothing. |
params.split.mode required | string | all cuts every page in direction; specified cuts the pages listed in pages; auto cuts a page whose width or height is about double another page's. One of all, specified, auto. |
params.split.direction | string | The direction of the cut for all, which needs it. One of vertical, horizontal. |
params.split.pages | array of objects | For specified, which needs it: each page to cut and the direction of its cut. 1 to 2,000 items. |
params.split.pages[].page required | integer | The page to cut, 1-based. 1 to 100,000. |
params.split.pages[].direction required | string | The direction of its cut. One of vertical, horizontal. |
params.images | string | embed, the default, puts the pictures inside each SVG; link writes each picture once into an images/ folder beside the SVGs, which link to it, and the export is then a zip whenever there is a picture. One of embed, link. |
params.fontSet | string | Set by the API: any value sent is ignored. Matches ^[0-9a-f]{16}$. |
version | integer | The number of the version to export. Default the document's current version. Only when type is export-images. At least 1. |
params | object | The picture options. Each left out takes its default. Only when type is export-images. |
params.format | string | The pictures' format. Default png. One of png, jpeg, webp. Default png. |
params.dpi | integer | The pictures' resolution, 72 to 600 DPI. Default 150. 72 to 600. Default 150. |
params.quality | number | Quality of JPEG and WebP pictures, 0.1 to 1. Default 0.85. 0.1 to 1. Default 0.85. |
params.pages | string | Which pages, as a print-dialog range of 1-based pages such as 1-3, 5, 8-. Blank, the default, is every page; pages past the end are dropped. Matches ^(?:\s*\d{1,6}\s*(?:-\s*(?:\d{1,6}\s*)?)?(?:,|$))*$. At most 500 characters. Default ``. |
params.split | object | Cut pages in half. Absent cuts nothing. The same fields as params.split. |
version | integer | The number of the version to export. Default the document's current version. Only when type is export-flipbook. At least 1. |
profileId | string | The appearance profile to draw it in. Default the document's own profile, else the workspace's default, else the built-in look. An unknown profile is 404 not_found. Only when type is export-flipbook. An id starting apr_. |
params | object | The page's options. Each left out takes its default. Only when type is export-flipbook. |
params.style | string | flipbook is a book to turn; standard shows every page one after another; tiled shows them in a grid. Default flipbook. One of flipbook, standard, tiled. Default flipbook. |
params.media | string | svg draws the pages as SVG; image as rendered pictures, for the flipbook style only. Default svg. One of svg, image. Default svg. |
params.pack | string | single is one HTML file; separate is index.html beside a file per page, in a zip. Default single. One of single, separate. Default single. |
params.svg | string | How a single-file flipbook holds its SVG pages: inline as elements, embed as data URLs. Default inline. One of inline, embed. Default inline. |
params.text | string | outline draws glyphs as shapes; link writes them as text in a linked font, the workspace's own web fonts where it has them. Default outline. One of outline, link. Default outline. |
params.textLayer | boolean | Adds invisible, selectable text over outlined glyphs. Default false. Default false. |
params.dpi | number or integer | The resolution of the pictures in the pages, and of the pages themselves when media is image, 72 to 600 DPI. 0 keeps each picture's own pixels, for SVG pages only. Default 150. Default 150. |
params.imageFormat | string | How pictures are stored: auto uses JPEG for photographs and PNG for the rest. Default auto. One of auto, png, jpeg. Default auto. |
params.quality | number | Quality of JPEG pictures, 0.1 to 1. Default 0.85. 0.1 to 1. Default 0.85. |
params.pages | string | Which pages, as a print-dialog range of 1-based pages such as 1-3, 5, 8-. Blank, the default, is every page; pages past the end are dropped. Matches ^(?:\s*\d{1,6}\s*(?:-\s*(?:\d{1,6}\s*)?)?(?:,|$))*$. At most 500 characters. Default ``. |
params.split | object | Cut pages in half. Absent cuts nothing. The same fields as params.split. |
params.title | string | The HTML page's title. Default the document's title. 1 to 200 characters. |
params.appearance | object | Set by the API: the look the export is drawn in, from profileId, else the document's profile, else the workspace's default, else the built-in look. Any value sent is replaced, though it must still be a valid look. |
params.appearance.name required | string | The look's name, 1 to 80 characters, unique among the workspace's looks. 1 to 80 characters. |
params.appearance.colours | object | The viewer's colours, each #rgb, #rrggbb or #rrggbbaa. Named colours and CSS functions are refused. Default {"chrome":"#ffffff","text":"#1a1a1a","accent":"#0066cc","sheet":"#ffffff","shadow":"#000000"}. |
params.appearance.colours.chrome | string | The toolbar's background. Default #ffffff. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #ffffff. |
params.appearance.colours.text | string | The toolbar's and the arrows' text and icons. Default #1a1a1a. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #1a1a1a. |
params.appearance.colours.accent | string | Hovered and pressed buttons, and focus outlines. Default #0066cc. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #0066cc. |
params.appearance.colours.sheet | string | The paper behind the pages. Default #ffffff. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #ffffff. |
params.appearance.colours.shadow | string | The shadows under the toolbar, the pages and the arrows. Default #000000. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #000000. |
params.appearance.pageBackground | object | What fills the space around the pages. Default solid #f1f1f3. Default {"kind":"solid","colour":"#f1f1f3","opacity":1}. One of 4 shapes, chosen by kind. |
params.appearance.pageBackground.kind required | string | One colour. One of solid, transparent, linear, radial. |
params.appearance.pageBackground.colour | string | The colour: #rgb, #rrggbb or #rrggbbaa. Default #f1f1f3. Only when kind is solid. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #f1f1f3. |
params.appearance.pageBackground.opacity | number | From 0 (clear) to 1 (opaque). Default 1. Only when kind is solid. 0 to 1. Default 1. |
params.appearance.pageBackground.angle required | number | The gradient's direction, in degrees. Only when kind is linear. 0 to 360. |
params.appearance.pageBackground.stops required | array of objects | Its colours, 2 to 8 stops. Only when kind is linear. 2 to 8 items. |
params.appearance.pageBackground.stops[].colour required | string | The stop's colour: #rgb, #rrggbb or #rrggbbaa. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. |
params.appearance.pageBackground.stops[].at required | number | Where the stop sits along the gradient, from 0 (its start) to 1 (its end). 0 to 1. |
params.appearance.pageBackground.stops required | array of objects | Its colours, 2 to 8 stops. Only when kind is radial. 2 to 8 items. |
params.appearance.pageBackground.stops[].colour required | string | The stop's colour: #rgb, #rrggbb or #rrggbbaa. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. |
params.appearance.pageBackground.stops[].at required | number | Where the stop sits along the gradient, from 0 (its start) to 1 (its end). 0 to 1. |
params.appearance.icons | object | How the icons are drawn. Default {"style":"line"}. |
params.appearance.icons.style | string | How the toolbar's and the turn arrows' icons are drawn: line (as drawn), rounded (heavier) or sharp (finer, square ends). filled is accepted, for looks that chose it, but the icons have no filled form and it is drawn as line. One of line, filled, rounded, sharp. Default line. |
params.appearance.icons.slots | object | Icons to draw instead of the built-in ones, by slot. Each is SVG path data, at most 800 characters. |
params.appearance.icons.slots.prev | string | SVG path data for the previous-page icon, drawn instead of the built-in one. |
params.appearance.icons.slots.next | string | SVG path data for the next-page icon, drawn instead of the built-in one. |
params.appearance.icons.slots.magnifier | string | SVG path data for the magnifier icon, drawn instead of the built-in one. |
params.appearance.icons.slots.expand | string | SVG path data for the enter-full-screen icon, drawn instead of the built-in one. |
params.appearance.icons.slots.contract | string | SVG path data for the leave-full-screen icon, drawn instead of the built-in one. |
params.appearance.icons.slots.close | string | SVG path data for the close icon, drawn instead of the built-in one. |
params.appearance.icons.slots.zoomIn | string | SVG path data for the zoom-in icon, drawn instead of the built-in one. |
params.appearance.icons.slots.zoomOut | string | SVG path data for the zoom-out icon, drawn instead of the built-in one. |
params.appearance.icons.slots.download | string | SVG path data for the download icon, drawn instead of the built-in one. |
params.appearance.icons.slots.search | string | SVG path data for the search icon, drawn instead of the built-in one. |
params.appearance.icons.slots.share | string | SVG path data for the share icon, drawn instead of the built-in one. |
params.appearance.icons.slots.print | string | SVG path data for the print icon, drawn instead of the built-in one. |
params.appearance.icons.slots.thumbnails | string | SVG path data for the thumbnails icon, drawn instead of the built-in one. |
params.appearance.features | object | Which controls show, in every view that does not override them. Default {"toolbar":true,"arrows":true,"pageIndicator":true,"magnifier":true,"fullscreen":true,"thumbnails":false,"zoom":false,"download":false,"search":false,"share":false,"print":false,"keyboard":true,"title":true}. |
params.appearance.features.toolbar | boolean | Shows the toolbar. Default true. Default true. |
params.appearance.features.arrows | boolean | Shows the arrows that turn the pages. Default true. Default true. |
params.appearance.features.pageIndicator | boolean | Shows the page number. Default true. Default true. |
params.appearance.features.magnifier | boolean | Shows the magnifier button. Default true. Default true. |
params.appearance.features.fullscreen | boolean | Shows the full-screen button. Default true. Default true. |
params.appearance.features.thumbnails | boolean | Shows a strip of page thumbnails. Default false. Default false. |
params.appearance.features.zoom | boolean | Shows a zoom button. Default false. Default false. |
params.appearance.features.download | boolean | Shows a download button. Default false. Default false. |
params.appearance.features.search | boolean | Shows a search button. Default false. Default false. |
params.appearance.features.share | boolean | Shows a share button. Default false. Default false. |
params.appearance.features.print | boolean | Shows a print button. Default false. Default false. |
params.appearance.features.keyboard | boolean | Lets the arrow and Page Up and Page Down keys turn the pages. Default true. Default true. |
params.appearance.features.title | boolean | Shows the title. Default true. Default true. |
params.appearance.desktop | object | The views on a screen wider than 768 CSS pixels. Default {"normal":{"layout":"spread","toolbar":"top","density":"regular"},"maximised":{"layout":"spread","toolbar":"overlay","density":"compact"}}. |
params.appearance.desktop.normal | object | The usual view. Default a spread, the toolbar at the top, regular density. Default {"layout":"spread","toolbar":"top","density":"regular"}. |
params.appearance.desktop.normal.layout | string | spread shows two pages side by side; single one page at a time. One of spread, single. Default spread. |
params.appearance.desktop.normal.toolbar | string | Where the toolbar sits: top, bottom, or overlay over the pages. One of top, bottom, overlay. Default top. |
params.appearance.desktop.normal.density | string | How much space there is between the viewer's parts. One of compact, regular, roomy. Default regular. |
params.appearance.desktop.normal.margins | object | This view's own space around the pages. Without it the view uses the look's margins. |
params.appearance.desktop.normal.margins.top | number | Space above the pages, in CSS pixels. Default 20. 0 to 240. Default 20. |
params.appearance.desktop.normal.margins.right | number | Space to the right of the pages, in CSS pixels. Default 16. 0 to 240. Default 16. |
params.appearance.desktop.normal.margins.bottom | number | Space below the pages, in CSS pixels. Default 32. 0 to 240. Default 32. |
params.appearance.desktop.normal.margins.left | number | Space to the left of the pages, in CSS pixels. Default 16. 0 to 240. Default 16. |
params.appearance.desktop.normal.features | object | Controls shown or hidden in this view only, over the look's features. |
params.appearance.desktop.normal.features.toolbar | boolean | In this view only: overrides the look's features.toolbar. |
params.appearance.desktop.normal.features.arrows | boolean | In this view only: overrides the look's features.arrows. |
params.appearance.desktop.normal.features.pageIndicator | boolean | In this view only: overrides the look's features.pageIndicator. |
params.appearance.desktop.normal.features.magnifier | boolean | In this view only: overrides the look's features.magnifier. |
params.appearance.desktop.normal.features.fullscreen | boolean | In this view only: overrides the look's features.fullscreen. |
params.appearance.desktop.normal.features.thumbnails | boolean | In this view only: overrides the look's features.thumbnails. |
params.appearance.desktop.normal.features.zoom | boolean | In this view only: overrides the look's features.zoom. |
params.appearance.desktop.normal.features.download | boolean | In this view only: overrides the look's features.download. |
params.appearance.desktop.normal.features.search | boolean | In this view only: overrides the look's features.search. |
params.appearance.desktop.normal.features.share | boolean | In this view only: overrides the look's features.share. |
params.appearance.desktop.normal.features.print | boolean | In this view only: overrides the look's features.print. |
params.appearance.desktop.normal.features.keyboard | boolean | In this view only: overrides the look's features.keyboard. |
params.appearance.desktop.normal.features.title | boolean | In this view only: overrides the look's features.title. |
params.appearance.desktop.maximised | object | The full-screen view. Default a spread, an overlay toolbar, compact density. Default {"layout":"spread","toolbar":"overlay","density":"compact"}. |
params.appearance.desktop.maximised.layout | string | spread shows two pages side by side; single one page at a time. One of spread, single. Default spread. |
params.appearance.desktop.maximised.toolbar | string | Where the toolbar sits: top, bottom, or overlay over the pages. One of top, bottom, overlay. Default top. |
params.appearance.desktop.maximised.density | string | How much space there is between the viewer's parts. One of compact, regular, roomy. Default regular. |
params.appearance.desktop.maximised.margins | object | This view's own space around the pages. Without it the view uses the look's margins. The same fields as params.appearance.desktop.normal.margins. |
params.appearance.desktop.maximised.features | object | Controls shown or hidden in this view only, over the look's features. The same fields as params.appearance.desktop.normal.features. |
params.appearance.mobile | object | The views on a screen 768 CSS pixels wide or narrower. Default {"normal":{"layout":"single","toolbar":"bottom","density":"compact"},"maximised":{"layout":"single","toolbar":"overlay","density":"compact"}}. |
params.appearance.mobile.normal | object | The usual view. Default a single page, the toolbar at the bottom, compact density. Default {"layout":"single","toolbar":"bottom","density":"compact"}. |
params.appearance.mobile.normal.layout | string | spread shows two pages side by side; single one page at a time. One of spread, single. Default spread. |
params.appearance.mobile.normal.toolbar | string | Where the toolbar sits: top, bottom, or overlay over the pages. One of top, bottom, overlay. Default top. |
params.appearance.mobile.normal.density | string | How much space there is between the viewer's parts. One of compact, regular, roomy. Default regular. |
params.appearance.mobile.normal.margins | object | This view's own space around the pages. Without it the view uses the look's margins. The same fields as params.appearance.desktop.normal.margins. |
params.appearance.mobile.normal.features | object | Controls shown or hidden in this view only, over the look's features. The same fields as params.appearance.desktop.normal.features. |
params.appearance.mobile.maximised | object | The full-screen view. Default a single page, an overlay toolbar, compact density. Default {"layout":"single","toolbar":"overlay","density":"compact"}. |
params.appearance.mobile.maximised.layout | string | spread shows two pages side by side; single one page at a time. One of spread, single. Default spread. |
params.appearance.mobile.maximised.toolbar | string | Where the toolbar sits: top, bottom, or overlay over the pages. One of top, bottom, overlay. Default top. |
params.appearance.mobile.maximised.density | string | How much space there is between the viewer's parts. One of compact, regular, roomy. Default regular. |
params.appearance.mobile.maximised.margins | object | This view's own space around the pages. Without it the view uses the look's margins. The same fields as params.appearance.desktop.normal.margins. |
params.appearance.mobile.maximised.features | object | Controls shown or hidden in this view only, over the look's features. The same fields as params.appearance.desktop.normal.features. |
params.appearance.pageTurn | object | How the pages turn. Default the built-in flip. Default {"kind":"builtin","name":"flip"}. One of 2 shapes, chosen by kind. |
params.appearance.pageTurn.kind required | string | A built-in turn. One of builtin, program. |
params.appearance.pageTurn.name required | string | flip, slide, fade, or none to change pages without a turn. Only when kind is builtin. One of flip, slide, fade, none. |
params.appearance.pageTurn.effect required | object | The program: data the flipbook interprets, never code. One it cannot read (a name over 60 characters or a duration out of range, say) turns pages with the built-in flip. Only when kind is program. |
params.appearance.pageTurn.effect.name required | string | The effect's name. At most 80 characters. |
params.appearance.pageTurn.effect.duration required | number | How long a turn takes, in milliseconds, from 80 to 2000. |
params.appearance.pageTurn.effect.channels | map of anys | The animated values by channel (rotateX, rotateY, rotateZ, x, y, z, scaleX, scaleY, skewX, skewY, opacity, shadow, originX, originY), each an expression: a nested array such as ["mul", ["in", "t"], ["num", -180]] over the inputs t, u, dir and drag. |
params.appearance.pageTurn.effect.curl | any | An expression for how far the turning page curls. |
params.appearance.selection | object | Whether readers can select what is on the pages. Default {"mode":"none","highlight":"#0066cc"}. |
params.appearance.selection.mode | string | What readers may select: nothing (none, the default), text, or text-and-images. One of none, text, text-and-images. Default none. |
params.appearance.selection.highlight | string | The colour of selected text. Default #0066cc. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #0066cc. |
params.appearance.margins | object | Space around the pages, in every view without margins of its own. Default {"top":20,"right":16,"bottom":32,"left":16}. |
params.appearance.margins.top | number | Space above the pages, in CSS pixels. Default 20. 0 to 240. Default 20. |
params.appearance.margins.right | number | Space to the right of the pages, in CSS pixels. Default 16. 0 to 240. Default 16. |
params.appearance.margins.bottom | number | Space below the pages, in CSS pixels. Default 32. 0 to 240. Default 32. |
params.appearance.margins.left | number | Space to the left of the pages, in CSS pixels. Default 16. 0 to 240. Default 16. |
params.appearance.logo | object | Hosted viewer only: a logo above the flipbook's title, as a link when href is set. |
params.appearance.logo.asset required | string | A library image's id: a PNG, JPEG, GIF, WebP or SVG of at most 2 MiB. Matches ^ast_[0-9a-z]{20}$. |
params.appearance.logo.alt required | string | Alternative text: what the logo says, such as the company's name. Required, up to 200 characters. At most 200 characters. |
params.appearance.logo.href | string | An http or https address the logo links to. |
params.appearance.favicon | object | Hosted viewer only: the browser tab's icon on the viewer's pages. |
params.appearance.favicon.asset required | string | A library image's id: a PNG or SVG of at most 512 KiB. Matches ^ast_[0-9a-z]{20}$. |
params.appearance.backgroundImage | object | Hosted viewer only: a picture behind the pages, over pageBackground, which shows until it loads, if it fails, and wherever it does not reach. |
params.appearance.backgroundImage.asset required | string | A library image's id: a PNG, JPEG, WebP or SVG of at most 8 MiB. Matches ^ast_[0-9a-z]{20}$. |
params.appearance.backgroundImage.fit | string | cover fills the space and crops the overflow; contain shows the whole picture; tile repeats it. Default cover. One of cover, contain, tile. Default cover. |
params.appearance.loading | object | Hosted viewer only: a screen over the flipbook until its first pages have loaded, in this colour, with the logo when the look has one and a line of text. |
params.appearance.loading.colour | string | The screen's colour. Default #ffffff. Matches ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. Default #ffffff. |
params.appearance.loading.message | string | A line of text, up to 120 characters. At most 120 characters. |
params.fontSet | string | Set by the API: any value sent is ignored. Matches ^[0-9a-f]{16}$. |
version | integer | The number of the version to export. Default the document's current version. Only when type is export-offline. At least 1. |
profileId | string | The appearance profile to draw it in. Default the document's own profile, else the workspace's default, else the built-in look. An unknown profile is 404 not_found. Only when type is export-offline. An id starting apr_. |
params | object | The book's options. Each left out takes its default. Only when type is export-offline. |
params.style | string | flipbook is a book to turn; standard shows every page one after another; tiled shows them in a grid. Default flipbook. One of flipbook, standard, tiled. Default flipbook. |
params.media | string | svg draws the pages as SVG; image as rendered pictures, for the flipbook style only. Default svg. One of svg, image. Default svg. |
params.text | string | outline draws glyphs as shapes; link writes them as text in a linked font. The zip's fonts/ folder then holds the workspace's web fonts it uses and lists any it does not have. Default outline. One of outline, link. Default outline. |
params.textLayer | boolean | Adds invisible, selectable text over outlined glyphs. Default false. Default false. |
params.dpi | number or integer | The resolution of the pictures in the pages, and of the pages themselves when media is image, 72 to 600 DPI. 0 keeps each picture's own pixels, for SVG pages only. Default 150. Default 150. |
params.imageFormat | string | How pictures are stored: auto uses JPEG for photographs and PNG for the rest. Default auto. One of auto, png, jpeg. Default auto. |
params.quality | number | Quality of JPEG pictures, 0.1 to 1. Default 0.85. 0.1 to 1. Default 0.85. |
params.pages | string | Which pages, as a print-dialog range of 1-based pages such as 1-3, 5, 8-. Blank, the default, is every page; pages past the end are dropped. Matches ^(?:\s*\d{1,6}\s*(?:-\s*(?:\d{1,6}\s*)?)?(?:,|$))*$. At most 500 characters. Default ``. |
params.split | object | Cut pages in half. Absent cuts nothing. The same fields as params.split. |
params.title | string | The HTML page's title. Default the document's title. 1 to 200 characters. |
params.appearance | object | Set by the API: the look the export is drawn in, from profileId, else the document's profile, else the workspace's default, else the built-in look. Any value sent is replaced, though it must still be a valid look. The same fields as params.appearance. |
params.fontSet | string | Set by the API: any value sent is ignored. Matches ^[0-9a-f]{16}$. |
Response
202 Accepted. A JSON object:
Response fields (15)
| Name | Type | Description |
|---|---|---|
export | object | The export: new, or the one already made or on its way. |
export.id | string | The export's id, which is also its job id for jobs.get. |
export.type | string | What kind of export it is. One of export-svg, export-images, export-flipbook, export-offline. |
export.version | number | The number of the version exported. Can be null. |
export.status | string | queued (waiting, also between retries), running, done (the file is ready to download) or failed (for good; asking again retries it). One of queued, running, done, failed. |
export.params | map of anys | The options the job runs with, every default filled in, including the look, the title and any letterhead the API added. |
export.file | object | Once status is done: the file the download sends. Null until then. Can be null. |
export.file.name | string | The stored file's name, such as export.zip. The download is named after the document. |
export.file.contentType | string | The file's media type. |
export.file.bytes | number | The file's size in bytes. |
export.file.pages | number | Pages in the document exported. |
export.error | string | Why it failed, in a sentence for people, when status is failed; null otherwise. It may change: switch on errorCode. Can be null. |
export.errorCode | string | Why it failed, as a stable code, when status is failed; null otherwise. source_missing: the version's stored file is gone. engine_error: the engine could not process this document. gave_up: it did not finish after every attempt. cancelled: Flipbird support cancelled it. job_failed: any other failure. The document.processed webhook event uses the same codes, except cancelled, which it never carries. One of source_missing, engine_error, gave_up, job_failed, cancelled. Can be null. |
export.createdAt | number | When the export was first asked for, epoch milliseconds. |
export.finishedAt | number | When it finished or failed for good, epoch milliseconds. Null until then. Can be null. |
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/exports \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"type": "export-svg"
}' Example response
{
"export": {
"id": "string",
"type": "export-svg",
"version": 1,
"status": "queued",
"params": {},
"file": {
"name": "Spring catalogue",
"contentType": "string",
"bytes": 1,
"pages": 1
},
"error": "string",
"errorCode": "source_missing",
"createdAt": 1767225600000,
"finishedAt": 1767225600000
}
} A document's exports, newest first
GET /documents/{documentId}/exports exports.list
The document's exports of every type and status, newest first, at most 50. There is no paging.
- Scopes
documents.read- MCP tool
exports_list
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (15)
| Name | Type | Description |
|---|---|---|
exports | array of objects | The exports, newest first. |
exports[].id | string | The export's id, which is also its job id for jobs.get. |
exports[].type | string | What kind of export it is. One of export-svg, export-images, export-flipbook, export-offline. |
exports[].version | number | The number of the version exported. Can be null. |
exports[].status | string | queued (waiting, also between retries), running, done (the file is ready to download) or failed (for good; asking again retries it). One of queued, running, done, failed. |
exports[].params | map of anys | The options the job runs with, every default filled in, including the look, the title and any letterhead the API added. |
exports[].file | object | Once status is done: the file the download sends. Null until then. Can be null. |
exports[].file.name | string | The stored file's name, such as export.zip. The download is named after the document. |
exports[].file.contentType | string | The file's media type. |
exports[].file.bytes | number | The file's size in bytes. |
exports[].file.pages | number | Pages in the document exported. |
exports[].error | string | Why it failed, in a sentence for people, when status is failed; null otherwise. It may change: switch on errorCode. Can be null. |
exports[].errorCode | string | Why it failed, as a stable code, when status is failed; null otherwise. source_missing: the version's stored file is gone. engine_error: the engine could not process this document. gave_up: it did not finish after every attempt. cancelled: Flipbird support cancelled it. job_failed: any other failure. The document.processed webhook event uses the same codes, except cancelled, which it never carries. One of source_missing, engine_error, gave_up, job_failed, cancelled. Can be null. |
exports[].createdAt | number | When the export was first asked for, epoch milliseconds. |
exports[].finishedAt | number | When it finished or failed for good, epoch milliseconds. Null until then. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/exports \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"exports": [
{
"id": "string",
"type": "export-svg",
"version": 1,
"status": "queued",
"params": {},
"file": {
"name": "Spring catalogue",
"contentType": "string",
"bytes": 1,
"pages": 1
},
"error": "string",
"errorCode": "source_missing",
"createdAt": 1767225600000,
"finishedAt": 1767225600000
}
]
} An export and how far it has got
GET /documents/{documentId}/exports/{exportId} exports.get
Poll this until status is done, then download the file with exports.download, or until it is failed. An export of another document, or an id that is not an export, is 404 not_found.
- Scopes
documents.read- MCP tool
exports_get
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
exportId required | string | The export's id, from exports.request or exports.list. An id starting job_. |
Response
200 OK. A JSON object:
Response fields (15)
| Name | Type | Description |
|---|---|---|
export | object | The export. |
export.id | string | The export's id, which is also its job id for jobs.get. |
export.type | string | What kind of export it is. One of export-svg, export-images, export-flipbook, export-offline. |
export.version | number | The number of the version exported. Can be null. |
export.status | string | queued (waiting, also between retries), running, done (the file is ready to download) or failed (for good; asking again retries it). One of queued, running, done, failed. |
export.params | map of anys | The options the job runs with, every default filled in, including the look, the title and any letterhead the API added. |
export.file | object | Once status is done: the file the download sends. Null until then. Can be null. |
export.file.name | string | The stored file's name, such as export.zip. The download is named after the document. |
export.file.contentType | string | The file's media type. |
export.file.bytes | number | The file's size in bytes. |
export.file.pages | number | Pages in the document exported. |
export.error | string | Why it failed, in a sentence for people, when status is failed; null otherwise. It may change: switch on errorCode. Can be null. |
export.errorCode | string | Why it failed, as a stable code, when status is failed; null otherwise. source_missing: the version's stored file is gone. engine_error: the engine could not process this document. gave_up: it did not finish after every attempt. cancelled: Flipbird support cancelled it. job_failed: any other failure. The document.processed webhook event uses the same codes, except cancelled, which it never carries. One of source_missing, engine_error, gave_up, job_failed, cancelled. Can be null. |
export.createdAt | number | When the export was first asked for, epoch milliseconds. |
export.finishedAt | number | When it finished or failed for good, epoch milliseconds. Null until then. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/exports/job_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"export": {
"id": "string",
"type": "export-svg",
"version": 1,
"status": "queued",
"params": {},
"file": {
"name": "Spring catalogue",
"contentType": "string",
"bytes": 1,
"pages": 1
},
"error": "string",
"errorCode": "source_missing",
"createdAt": 1767225600000,
"finishedAt": 1767225600000
}
} Download a finished export
GET /documents/{documentId}/exports/{exportId}/file exports.download
The finished file: one SVG, picture or HTML file, or a zip when there are several, named after the document. 409 with code not_ready until the export is done (details.status says how it stands), and 410 gone when its file is no longer stored.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
exportId required | string | The export's id, from exports.request or exports.list. An id starting job_. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/exports/job_7m2kq9vx4c8d1r5t6wnb/file \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 409 | nothing_to_export | The document has no version. |
| 409 | not_ready | Downloading before the export is done. |
| 410 | gone | The export's file is no longer stored. |