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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Response

200 OK. A JSON object:

Response fields (40)
NameTypeDescription
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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Request body

A JSON object, at most 512 KiB.

NameTypeDescription
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)
NameTypeDescription
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:

StatusCodeWhen
400invalid_enrichment_imageA gallery image is not a raster image in the workspace's library. details.asset names it.