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)
| Name | Type | Description |
|---|---|---|
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.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
profileId required | string | The appearance profile's id. An id starting apr_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
profileId required | string | The appearance profile's id. An id starting apr_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
documentId required | string | The document to use the look for. An id starting doc_. |
Response
201 Created. A JSON object:
Response fields (2)
| Name | Type | Description |
|---|---|---|
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:
| Status | Code | When |
|---|---|---|
| 400 | invalid | The look does not match its schema. |
| 400 | invalid_look_image | A picture in the look is not a library image of an allowed type or size. |
| 409 | conflict | Another look has that name. |
| 410 | gone | A library image the look names can no longer be read. |