API
Enrichment
Lay hotspots, calls to action, videos and image galleries over a published document's pages.
Enrichment items are interactive elements the hosted viewer draws over a document's pages. A hotspot shows a note, and a cta button opens a web address or turns to a page. A video plays a YouTube or Vimeo video, and nothing loads from the provider until the reader presses play. A gallery opens images from the workspace's image library. Items belong to the document, not to a version, and go live as soon as they are saved: there is no separate publish step.
Each item sits on a page (1-based) at rect, given as fractions of the page from its top left. enrichment.get returns pages, the sizes of the pages the viewer shows now, to place items against. enrichment.set replaces the whole list, so read it, change it and write it back. Keep each item's id the same across saves so readers' clicks on it count together.
Saving needs the plan's enrichment feature, documents.publish and edit access to the document. Without the feature, items are kept but readers see none.
A document's enrichment items: hotspots, calls to action, videos and galleries over its pages
GET /documents/{documentId}/enrichment enrichment.get
Returns the items, when they were last saved, and the pages the hosted viewer shows now. Each item is on a page (1-based) at rect, [x0, y0, x1, y1] as fractions of the page from its top left. pages describes the pages the hosted viewer shows now (null when it shows none). An item on a page the shown version does not have is kept but not shown.
Items belong to the document, not to a version: a new version keeps them on the same page numbers. Reading works whether or not the plan includes enrichment; without it, readers are shown no items. Needs view access to the document; one the caller cannot open answers 404 not_found.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (40)
| Name | Type | Description |
|---|---|---|
items | array of objects | The document's items, in the order they were saved. |
items[].type | string | hotspot: a marker that shows a note when the reader points at it, focuses it or taps it. One of hotspot, cta, video, gallery. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is hotspot. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is hotspot. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is hotspot. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is hotspot. 1 to 80 characters. |
items[].text | string | The note shown on pointing, focusing or tapping. It may run over lines. Only when type is hotspot. 1 to 600 characters. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is cta. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is cta. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is cta. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is cta. 1 to 80 characters. |
items[].target | object | What the button does. Only when type is cta. One of 2 shapes, chosen by kind. |
items[].target.kind | string | url: open a web address in a new tab. One of url, page. |
items[].target.url | string | The http or https address to open, with no user name or password. Only when kind is url. At most 2,000 characters. |
items[].target.page | integer | The page to turn to, 1-based. A button to a page the shown version does not have is not drawn. Only when kind is page. 1 to 10,000. |
items[].style | string | solid: filled with the look's accent colour. outline: outlined in it. Only when type is cta. One of solid, outline. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is video. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is video. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is video. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is video. 1 to 80 characters. |
items[].video | object | The video, as a provider and its id. A URL is never stored. Only when type is video. One of 2 shapes, chosen by provider. |
items[].video.provider | string | youtube: played from YouTube's privacy-enhanced player, www.youtube-nocookie.com. One of youtube, vimeo. |
items[].video.id | string | The video's 11-character id, the v= of its watch address. Only when provider is youtube. Matches ^[A-Za-z0-9_-]{11}$. |
items[].video.start optional | integer | Seconds into the video to start at. Left out, it starts at the beginning. Only when provider is youtube. 0 to 86,400. |
items[].video.id | string | The video's numeric id. Only when provider is vimeo. Matches ^[0-9]{1,12}$. |
items[].video.hash optional | string | An unlisted video's privacy hash: the h= of its link, or the part after the id in vimeo.com/{id}/{hash}. Only when provider is vimeo. Matches ^[0-9a-f]{6,20}$. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is gallery. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is gallery. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is gallery. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is gallery. 1 to 80 characters. |
items[].images | array of objects | The images the gallery shows, in order. Only when type is gallery. 1 to 12 items. |
items[].images[].asset | string | The id of a PNG, JPEG, GIF or WebP image in the workspace's library (an asset's id). Saving copies it for the viewer to serve. Matches ^ast_[0-9a-z]{20}$. |
items[].images[].alt | string | What the image shows, for readers who cannot see it. Empty only for a decorative image. At most 200 characters. |
updatedAt | number | When the items were last saved, in epoch milliseconds, or null when they never were. Can be null. |
pages | object | The pages the hosted viewer shows now, which the items are placed on, or null while it shows none (the document is not published, or its pages are not made yet). Can be null. |
pages.version | integer | The document version the pages are of. |
pages.current | boolean | Whether that is the document's current version. After a new version, the viewer shows the last version whose pages are made until the new one's are. |
pages.sizes | array of objects | Each page's size, after rotation, in page order. |
pages.sizes[].width | number | The page's width in points (1/72 inch). |
pages.sizes[].height | number | The page's height in points (1/72 inch). |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/enrichment \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"items": [
{
"id": "en_3ahov29g",
"page": 1,
"rect": [
0.1,
0.1,
0.4,
0.3
],
"label": "Spring campaign",
"type": "hotspot",
"text": "string"
}
],
"updatedAt": 1767225600000,
"pages": {
"version": 1,
"current": true,
"sizes": [
{
"width": 1,
"height": 1
}
]
}
} Replace a document's enrichment items
PUT /documents/{documentId}/enrichment enrichment.set
Replaces every item. The hosted viewer shows them at once. A hotspot shows text; a cta opens an http(s) address in a new tab or turns to a page; a video is a YouTube or Vimeo id, played from the privacy-enhanced player only once the reader presses play; a gallery shows images from the workspace's library (PNG, JPEG, GIF or WebP), which are copied for the viewer to serve.
At most 100 items, 20 on a page, 12 images in a gallery and 60 different gallery images in a document. Needs edit access to the document as well as documents.publish: 403 forbidden when the caller may only view it. A gallery image that is not a PNG, JPEG, GIF or WebP in the workspace's library answers 400 invalid_enrichment_image, with the asset's id in error.details.asset, and nothing is saved.
The copies of images the galleries no longer show are deleted. Returns the items as saved, with pages as enrichment.get gives it.
- Scopes
documents.publish- Plan
- Interactive pages, on Pro, Enterprise
- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 512 KiB.
| Name | Type | Description |
|---|---|---|
items required | array of objects | Every item the document carries, of any type. Saving replaces them all. At most 100 items. |
items[].type required | string | hotspot: a marker that shows a note when the reader points at it, focuses it or taps it. One of hotspot, cta, video, gallery. |
items[].id required | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is hotspot. Matches ^en_[0-9a-z]{8,24}$. |
items[].page required | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is hotspot. 1 to 10,000. |
items[].rect required | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is hotspot. |
items[].label required | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is hotspot. 1 to 80 characters. |
items[].text required | string | The note shown on pointing, focusing or tapping. It may run over lines. Only when type is hotspot. 1 to 600 characters. |
items[].id required | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is cta. Matches ^en_[0-9a-z]{8,24}$. |
items[].page required | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is cta. 1 to 10,000. |
items[].rect required | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is cta. |
items[].label required | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is cta. 1 to 80 characters. |
items[].target required | object | What the button does. Only when type is cta. One of 2 shapes, chosen by kind. |
items[].target.kind required | string | url: open a web address in a new tab. One of url, page. |
items[].target.url required | string | The http or https address to open, with no user name or password. Only when kind is url. At most 2,000 characters. |
items[].target.page required | integer | The page to turn to, 1-based. A button to a page the shown version does not have is not drawn. Only when kind is page. 1 to 10,000. |
items[].style required | string | solid: filled with the look's accent colour. outline: outlined in it. Only when type is cta. One of solid, outline. |
items[].id required | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is video. Matches ^en_[0-9a-z]{8,24}$. |
items[].page required | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is video. 1 to 10,000. |
items[].rect required | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is video. |
items[].label required | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is video. 1 to 80 characters. |
items[].video required | object | The video, as a provider and its id. A URL is never stored. Only when type is video. One of 2 shapes, chosen by provider. |
items[].video.provider required | string | youtube: played from YouTube's privacy-enhanced player, www.youtube-nocookie.com. One of youtube, vimeo. |
items[].video.id required | string | The video's 11-character id, the v= of its watch address. Only when provider is youtube. Matches ^[A-Za-z0-9_-]{11}$. |
items[].video.start | integer | Seconds into the video to start at. Left out, it starts at the beginning. Only when provider is youtube. 0 to 86,400. |
items[].video.id required | string | The video's numeric id. Only when provider is vimeo. Matches ^[0-9]{1,12}$. |
items[].video.hash | string | An unlisted video's privacy hash: the h= of its link, or the part after the id in vimeo.com/{id}/{hash}. Only when provider is vimeo. Matches ^[0-9a-f]{6,20}$. |
items[].id required | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is gallery. Matches ^en_[0-9a-z]{8,24}$. |
items[].page required | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is gallery. 1 to 10,000. |
items[].rect required | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is gallery. |
items[].label required | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is gallery. 1 to 80 characters. |
items[].images required | array of objects | The images the gallery shows, in order. Only when type is gallery. 1 to 12 items. |
items[].images[].asset required | string | The id of a PNG, JPEG, GIF or WebP image in the workspace's library (an asset's id). Saving copies it for the viewer to serve. Matches ^ast_[0-9a-z]{20}$. |
items[].images[].alt required | string | What the image shows, for readers who cannot see it. Empty only for a decorative image. At most 200 characters. |
Response
200 OK. A JSON object:
Response fields (40)
| Name | Type | Description |
|---|---|---|
items | array of objects | The document's items, in the order they were saved. |
items[].type | string | hotspot: a marker that shows a note when the reader points at it, focuses it or taps it. One of hotspot, cta, video, gallery. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is hotspot. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is hotspot. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is hotspot. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is hotspot. 1 to 80 characters. |
items[].text | string | The note shown on pointing, focusing or tapping. It may run over lines. Only when type is hotspot. 1 to 600 characters. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is cta. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is cta. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is cta. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is cta. 1 to 80 characters. |
items[].target | object | What the button does. Only when type is cta. One of 2 shapes, chosen by kind. |
items[].target.kind | string | url: open a web address in a new tab. One of url, page. |
items[].target.url | string | The http or https address to open, with no user name or password. Only when kind is url. At most 2,000 characters. |
items[].target.page | integer | The page to turn to, 1-based. A button to a page the shown version does not have is not drawn. Only when kind is page. 1 to 10,000. |
items[].style | string | solid: filled with the look's accent colour. outline: outlined in it. Only when type is cta. One of solid, outline. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is video. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is video. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is video. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is video. 1 to 80 characters. |
items[].video | object | The video, as a provider and its id. A URL is never stored. Only when type is video. One of 2 shapes, chosen by provider. |
items[].video.provider | string | youtube: played from YouTube's privacy-enhanced player, www.youtube-nocookie.com. One of youtube, vimeo. |
items[].video.id | string | The video's 11-character id, the v= of its watch address. Only when provider is youtube. Matches ^[A-Za-z0-9_-]{11}$. |
items[].video.start optional | integer | Seconds into the video to start at. Left out, it starts at the beginning. Only when provider is youtube. 0 to 86,400. |
items[].video.id | string | The video's numeric id. Only when provider is vimeo. Matches ^[0-9]{1,12}$. |
items[].video.hash optional | string | An unlisted video's privacy hash: the h= of its link, or the part after the id in vimeo.com/{id}/{hash}. Only when provider is vimeo. Matches ^[0-9a-f]{6,20}$. |
items[].id | string | The item's id, made by the caller: en_ and 8 to 24 lower-case letters and digits, unique in the document. Keep it the same across saves, so readers' clicks on the item count together. Only when type is gallery. Matches ^en_[0-9a-z]{8,24}$. |
items[].page | integer | The page the item is on, 1-based. An item on a page the shown version does not have is kept but not drawn. Only when type is gallery. 1 to 10,000. |
items[].rect | array of 4 numbers | Where the item sits on its page: [x0, y0, x1, y1] as fractions of the page's width and height from its top left corner. It runs left to right and top to bottom, and is at least 0.01 of the page each way. Only when type is gallery. |
items[].label | string | What the item is called: its accessible name, and the words on a button (a call to action, a gallery, a video) or a note's heading. Only when type is gallery. 1 to 80 characters. |
items[].images | array of objects | The images the gallery shows, in order. Only when type is gallery. 1 to 12 items. |
items[].images[].asset | string | The id of a PNG, JPEG, GIF or WebP image in the workspace's library (an asset's id). Saving copies it for the viewer to serve. Matches ^ast_[0-9a-z]{20}$. |
items[].images[].alt | string | What the image shows, for readers who cannot see it. Empty only for a decorative image. At most 200 characters. |
updatedAt | number | When the items were last saved, in epoch milliseconds, or null when they never were. Can be null. |
pages | object | The pages the hosted viewer shows now, which the items are placed on, or null while it shows none (the document is not published, or its pages are not made yet). Can be null. |
pages.version | integer | The document version the pages are of. |
pages.current | boolean | Whether that is the document's current version. After a new version, the viewer shows the last version whose pages are made until the new one's are. |
pages.sizes | array of objects | Each page's size, after rotation, in page order. |
pages.sizes[].width | number | The page's width in points (1/72 inch). |
pages.sizes[].height | number | The page's height in points (1/72 inch). |
Example request
curl -X PUT https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/enrichment \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"id": "en_3ahov29g",
"page": 1,
"rect": [
0.1,
0.1,
0.4,
0.3
],
"label": "Spring campaign",
"type": "hotspot",
"text": "string"
}
]
}' Example response
{
"items": [
{
"id": "en_3ahov29g",
"page": 1,
"rect": [
0.1,
0.1,
0.4,
0.3
],
"label": "Spring campaign",
"type": "hotspot",
"text": "string"
}
],
"updatedAt": 1767225600000,
"pages": {
"version": 1,
"current": true,
"sizes": [
{
"width": 1,
"height": 1
}
]
}
} Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | invalid_enrichment_image | A gallery image is not a raster image in the workspace's library. details.asset names it. |