API

Flipbook looks

Save named flipbook looks and choose which a document uses.

A look (an appearance profile) is a named set of choices for how a flipbook is shown: colours, the page background, icons, which controls show, the desktop and mobile views and their full-screen forms, margins, text selection and the page turn. A logo, a favicon, a background picture and a loading screen are for the hosted viewer only.

A flipbook or offline export is drawn in its profileId if given; otherwise in the document's assigned look, set with appearanceProfiles.assign or appearanceId on documents.update; failing that the workspace default, then the built-in look. The look is copied into each export, so editing or deleting it does not change exports already made or queued. A publication names its own look.

Saving a look replaces it whole: fields left out take their defaults. Managing looks needs documents.edit.any. The fields a look holds are listed under params.appearance on exports.request.

List the tenant's flipbook looks

GET /appearance-profiles appearanceProfiles.list

Every saved look in the workspace, by name, each with every default filled in. There is no paging.

Scopes
documents.read
MCP tool
appearance_profiles_list

Response

200 OK. A JSON object:

Response fields (8)
NameTypeDescription
appearances array of objects The looks, by name.
appearances[].id string The profile's id.
appearances[].name string The look's name, unique in the workspace.
appearances[].appearance map of anys The whole look, every default filled in: the shape appearanceProfiles.create takes.
appearances[].isDefault boolean Whether this is the workspace's default look, used by documents without a profile of their own.
appearances[].createdBy string The user id of the member who made it, or null when no member did. Can be null.
appearances[].createdAt number When it was made, epoch milliseconds.
appearances[].updatedAt number When it last changed, epoch milliseconds.

Example request

curl https://api.flipbird.io/api/v1/appearance-profiles \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "appearances": [
    {
      "id": "string",
      "name": "Spring catalogue",
      "appearance": {},
      "isDefault": true,
      "createdBy": "string",
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000
    }
  ]
}

Save a named flipbook look

POST /appearance-profiles appearanceProfiles.create

Colours, page background, icon style and path replacements, which controls show, desktop and mobile (and the maximised view of each), margins, text selection, and a page turn: a builtin (flip, slide, fade, none) or a numeric page-turn program. Icon styles are line, rounded and sharp; filled is accepted but drawn as line, the icons having no filled form.

For the hosted viewer only: a logo (a library image's id, alternative text and an optional http(s) link), a favicon (a PNG or SVG from the library), a background picture (cover, contain or tile, over the page background) and a loading screen (a colour and a line of text). Exports do not draw these. A library image a look uses is copied in the clear for the viewer while a live look uses it.

Made the default, it replaces the current default. A look that does not fit the schema is 400 invalid, its message naming the first field at fault; a name another look has is 409 conflict; a picture that is not a library image of a type and size its slot takes is 400 invalid_look_image, and one that can no longer be read is 410 gone.

Scopes
documents.edit.any
Retries
Safe with an Idempotency-Key
MCP tool
appearance_profiles_create

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
appearance required map of anys The look. name (1 to 80 characters, unique in the workspace) is required; every other field is optional and takes its default: colours (chrome, text, accent, sheet and shadow, each #rgb, #rrggbb or #rrggbbaa), pageBackground (solid, transparent, linear or radial), icons (style, and slots of SVG path data to replace icons), features (which controls show), desktop and mobile (each a normal and a maximised view, with layout, toolbar, density, margins and features), pageTurn (a builtin turn or a program), selection, margins and, for the hosted viewer only, logo, favicon, backgroundImage and loading. At most 32 KB as JSON. Each field is described under params.appearance of exports.request, which takes the same shape.
isDefault boolean Make it the workspace's default look, replacing the current default. Default false.

Response

201 Created. A JSON object:

Response fields (7)
NameTypeDescription
id string The profile's id.
name string The look's name, unique in the workspace.
appearance map of anys The whole look, every default filled in: the shape appearanceProfiles.create takes.
isDefault boolean Whether this is the workspace's default look, used by documents without a profile of their own.
createdBy string The user id of the member who made it, or null when no member did. Can be null.
createdAt number When it was made, epoch milliseconds.
updatedAt number When it last changed, epoch milliseconds.

Example request

curl -X POST https://api.flipbird.io/api/v1/appearance-profiles \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "appearance": {}
}'
Example response
{
  "id": "string",
  "name": "Spring catalogue",
  "appearance": {},
  "isDefault": true,
  "createdBy": "string",
  "createdAt": 1767225600000,
  "updatedAt": 1767225600000
}

Change a flipbook look, or make it the default

PATCH /appearance-profiles/{profileId} appearanceProfiles.update

Given appearance, replaces the whole look: fields left out take their defaults, not the profile's current values, and the profile takes the look's name. Exports already made or queued keep the look they were given. Refused as appearanceProfiles.create refuses; an unknown profile is 404 not_found.

Scopes
documents.edit.any
Retries
Safe with an Idempotency-Key
MCP tool
appearance_profiles_update

Path parameters

NameTypeDescription
profileId required string The appearance profile's id. An id starting apr_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
appearance map of anys The whole new look, in the shape appearanceProfiles.create takes. Fields left out take their defaults, not their current values.
isDefault boolean true makes it the workspace's default look, replacing the current default; false takes that role from it, if it had it, leaving the workspace with no default.

Response

200 OK. A JSON object:

Response fields (7)
NameTypeDescription
id string The profile's id.
name string The look's name, unique in the workspace.
appearance map of anys The whole look, every default filled in: the shape appearanceProfiles.create takes.
isDefault boolean Whether this is the workspace's default look, used by documents without a profile of their own.
createdBy string The user id of the member who made it, or null when no member did. Can be null.
createdAt number When it was made, epoch milliseconds.
updatedAt number When it last changed, epoch milliseconds.

Example request

curl -X PATCH https://api.flipbird.io/api/v1/appearance-profiles/apr_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "appearance": {},
  "isDefault": true
}'
Example response
{
  "id": "string",
  "name": "Spring catalogue",
  "appearance": {},
  "isDefault": true,
  "createdBy": "string",
  "createdAt": 1767225600000,
  "updatedAt": 1767225600000
}

Delete a flipbook look

DELETE /appearance-profiles/{profileId} appearanceProfiles.delete

Documents that used it export in the workspace's default look afterwards. Exports already made keep the look they were given. An unknown profile is 404 not_found.

Scopes
documents.edit.any
Retries
Safe with an Idempotency-Key
MCP tool
appearance_profiles_delete

Path parameters

NameTypeDescription
profileId required string The appearance profile's id. An id starting apr_.

Response

200 OK. An empty JSON object, {}.

Example request

curl -X DELETE https://api.flipbird.io/api/v1/appearance-profiles/apr_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Use this look for a document

POST /appearance-profiles/{profileId}/assign appearanceProfiles.assign

Later flipbook and offline exports of that document use it, unless the export names a different profile. The look is copied into the export, so editing the profile later does not change an export already queued. The same as setting the document's appearanceId with documents.update. Needs edit access to the document (403 forbidden); an unknown profile or document is 404 not_found.

Scopes
documents.edit.any
Retries
Safe with an Idempotency-Key
MCP tool
appearance_profiles_assign

Path parameters

NameTypeDescription
profileId required string The appearance profile's id. An id starting apr_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
documentId required string The document to use the look for. An id starting doc_.

Response

201 Created. A JSON object:

Response fields (2)
NameTypeDescription
documentId string The document's id.
appearanceId string The profile now assigned to it.

Example request

curl -X POST https://api.flipbird.io/api/v1/appearance-profiles/apr_7m2kq9vx4c8d1r5t6wnb/assign \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "documentId": "doc_7m2kq9vx4c8d1r5t6wnb"
}'
Example response
{
  "documentId": "…",
  "appearanceId": "…"
}

Errors

Besides the errors any endpoint can answer, these endpoints answer:

StatusCodeWhen
400invalidThe look does not match its schema.
400invalid_look_imageA picture in the look is not a library image of an allowed type or size.
409conflictAnother look has that name.
410goneA library image the look names can no longer be read.