API

Collections

Group published documents into a bookshelf or kiosk under one address, with its own look, order and access.

A collection is a shelf of documents at https://view.flipbird.io/c/{publicId}. It shows them as a grid of cards or as covers on shelves, in a manual, newest-first or A to Z order. Setting kioskIdleSeconds makes it a touch-screen kiosk that returns to the shelf after that many idle seconds. A new collection is empty, unlisted and not live: fill it with collections.setItems and make it live with collections.publish.

A collection has the same four modes as a publication, which decide who may open the shelf, and its own password. Each document on it keeps its own publication: readers see a document on the shelf only while that document's publication is live and its mode lets them in, so publishing a collection publishes nothing else. collections.setItems takes the updatedAt you last read, so two members editing the same shelf cannot overwrite each other.

Making, changing, filling and publishing collections need the plan's collections feature, documents.publish and documents.publish.manage. Reading, taking down and deleting work without the feature. On a plan without it, collections are kept, but their addresses show readers an unavailable page. A workspace keeps at most 200 collections, each of at most 100 documents.

List collections, most recently changed first

GET /collections collections.list

Returns every collection the workspace keeps (at most 200), in one answer: there are no pages. Each itemCount counts only the documents the caller may see. Works whether or not the plan includes collections.

Scopes
documents.read
MCP tool
collections_list

Response

200 OK. A JSON object:

Response fields (20)
NameTypeDescription
collections array of objects The workspace's collections, most recently changed first.
collections[].id string The collection's id.
collections[].publicId string The collection's address, made when it is created and never changed: readers open it at https://view.flipbird.io/c/{publicId}.
collections[].title string The collection's name, shown as the shelf's heading.
collections[].description string Text shown under the heading, empty for none. Blank lines part its paragraphs.
collections[].mode string Who may open the shelf. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter the collection's password first. authenticated: only signed-in members of the workspace. A new collection is unlisted and not live. One of public, unlisted, password, authenticated.
collections[].live boolean Whether readers can open the shelf now. A new collection is not live until it is published.
collections[].hasPassword boolean Whether a password is stored. Only a password collection keeps one: publishing in another mode drops it.
collections[].seo object What the shelf's page tells search engines and link previews. A field not set is absent.
collections[].seo.title optional string The page title. Not set, the page uses the collection's title. At most 120 characters.
collections[].seo.description optional string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
collections[].seo.noindex optional boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
collections[].appearanceId string The saved look the shelf is shown in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
collections[].layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
collections[].sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
collections[].kioskIdleSeconds integer Seconds without a touch before a kiosk returns to the shelf, or null when the collection is not a kiosk. A kiosk has large touch targets and a full-screen button, and each document opened from it carries a link back to the shelf. Can be null.
collections[].itemCount integer How many documents on it the caller may see, not counting any in the trash.
collections[].createdAt number When it was made, in epoch milliseconds.
collections[].updatedAt number When it last changed, in epoch milliseconds. Every change moves it on. collections.setItems takes it back as updatedAt.
collections[].publishedAt number When it last went live, in epoch milliseconds, or null if it never has. Kept after a take-down. Can be null.

Example request

curl https://api.flipbird.io/api/v1/collections \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "collections": [
    {
      "id": "string",
      "publicId": "…",
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "mode": "public",
      "live": true,
      "hasPassword": true,
      "seo": {
        "title": "Spring catalogue",
        "description": "Our spring range.",
        "noindex": true
      },
      "appearanceId": "…",
      "layout": "grid",
      "sort": "manual",
      "kioskIdleSeconds": 1,
      "itemCount": 1,
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000,
      "publishedAt": 1767225600000
    }
  ]
}

A collection and the documents on it, in order

GET /collections/{collectionId} collections.get

Returns the collection and the documents on it in their set order. Lists only the documents the caller may see, and none in the trash. An unknown collection answers 404 not_found. Works whether or not the plan includes collections.

Scopes
documents.read
MCP tool
collections_get

Path parameters

NameTypeDescription
collectionId required string The collection's id. An id starting col_.

Response

200 OK. A JSON object:

Response fields (29)
NameTypeDescription
collection object The collection, with itemCount counting the documents in items.
collection.id string The collection's id.
collection.publicId string The collection's address, made when it is created and never changed: readers open it at https://view.flipbird.io/c/{publicId}.
collection.title string The collection's name, shown as the shelf's heading.
collection.description string Text shown under the heading, empty for none. Blank lines part its paragraphs.
collection.mode string Who may open the shelf. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter the collection's password first. authenticated: only signed-in members of the workspace. A new collection is unlisted and not live. One of public, unlisted, password, authenticated.
collection.live boolean Whether readers can open the shelf now. A new collection is not live until it is published.
collection.hasPassword boolean Whether a password is stored. Only a password collection keeps one: publishing in another mode drops it.
collection.seo object What the shelf's page tells search engines and link previews. A field not set is absent.
collection.seo.title optional string The page title. Not set, the page uses the collection's title. At most 120 characters.
collection.seo.description optional string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
collection.seo.noindex optional boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
collection.appearanceId string The saved look the shelf is shown in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
collection.layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
collection.sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
collection.kioskIdleSeconds integer Seconds without a touch before a kiosk returns to the shelf, or null when the collection is not a kiosk. A kiosk has large touch targets and a full-screen button, and each document opened from it carries a link back to the shelf. Can be null.
collection.itemCount integer How many documents on it the caller may see, not counting any in the trash.
collection.createdAt number When it was made, in epoch milliseconds.
collection.updatedAt number When it last changed, in epoch milliseconds. Every change moves it on. collections.setItems takes it back as updatedAt.
collection.publishedAt number When it last went live, in epoch milliseconds, or null if it never has. Kept after a take-down. Can be null.
items array of objects The documents on it that the caller may see, not counting any in the trash, in the order collections.setItems set. The shelf applies the collection's sort when it shows them.
items[].documentId string The document's id.
items[].title string The document's title.
items[].state string The document's own state. One of draft, published, archived.
items[].currentVersion number The document's current version number, or null when it has none yet. Can be null.
items[].publication object The document's own publication, or null when it has none. Readers see the document on the shelf only while it is live, and only if its mode lets them open it. Can be null.
items[].publication.publicId string The document's own publication address: https://view.flipbird.io/v/{publicId}.
items[].publication.mode string Who may read the document, as a publication's mode says. One of public, unlisted, password, authenticated.
items[].publication.live boolean Whether the document's publication is live.

Example request

curl https://api.flipbird.io/api/v1/collections/col_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "collection": {
    "id": "string",
    "publicId": "…",
    "title": "Spring catalogue",
    "description": "Our spring range.",
    "mode": "public",
    "live": true,
    "hasPassword": true,
    "seo": {
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "noindex": true
    },
    "appearanceId": "…",
    "layout": "grid",
    "sort": "manual",
    "kioskIdleSeconds": 1,
    "itemCount": 1,
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "publishedAt": 1767225600000
  },
  "items": [
    {
      "documentId": "…",
      "title": "Spring catalogue",
      "state": "draft",
      "currentVersion": 1,
      "publication": {
        "publicId": "…",
        "mode": "public",
        "live": true
      }
    }
  ]
}

Make a collection

POST /collections collections.create

Makes a collection with no documents, in unlisted mode and not live until it is published (collections.publish). Its publicId is made now and kept for good. Fields left out take these defaults: no description, grid layout, manual sort, the workspace's default look, no SEO fields, and not a kiosk. A workspace keeps at most 200 collections: past that the call answers 409 conflict.

Returns the collection and its documents as collections.get does.

Scopes
documents.publish, documents.publish.manage
Plan
Bookshelves, on Pro, Enterprise
Retries
Safe with an Idempotency-Key
MCP tool
collections_create

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
title required string The collection's name, shown as the shelf's heading. 1 to 200 characters.
description string Text shown under the shelf's heading. Blank lines part its paragraphs; an empty string removes it. At most 1,000 characters.
layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
appearanceId string The saved look to show the shelf in, or null for the workspace's default look. An id that is not a saved look answers 404 not_found. An id starting apr_. Can be null.
seo object What the shelf's page tells search engines and link previews. Given, it replaces the stored fields whole.
seo.title string The page title. Not set, the page uses the collection's title. At most 120 characters.
seo.description string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
seo.noindex boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
kioskIdleSeconds integer Makes the collection a kiosk that returns to the shelf after this many seconds without a touch. Null makes it an ordinary shelf. 15 to 3,600. Can be null.

Response

201 Created. A JSON object:

Response fields (29)
NameTypeDescription
collection object The collection, with itemCount counting the documents in items.
collection.id string The collection's id.
collection.publicId string The collection's address, made when it is created and never changed: readers open it at https://view.flipbird.io/c/{publicId}.
collection.title string The collection's name, shown as the shelf's heading.
collection.description string Text shown under the heading, empty for none. Blank lines part its paragraphs.
collection.mode string Who may open the shelf. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter the collection's password first. authenticated: only signed-in members of the workspace. A new collection is unlisted and not live. One of public, unlisted, password, authenticated.
collection.live boolean Whether readers can open the shelf now. A new collection is not live until it is published.
collection.hasPassword boolean Whether a password is stored. Only a password collection keeps one: publishing in another mode drops it.
collection.seo object What the shelf's page tells search engines and link previews. A field not set is absent.
collection.seo.title optional string The page title. Not set, the page uses the collection's title. At most 120 characters.
collection.seo.description optional string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
collection.seo.noindex optional boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
collection.appearanceId string The saved look the shelf is shown in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
collection.layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
collection.sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
collection.kioskIdleSeconds integer Seconds without a touch before a kiosk returns to the shelf, or null when the collection is not a kiosk. A kiosk has large touch targets and a full-screen button, and each document opened from it carries a link back to the shelf. Can be null.
collection.itemCount integer How many documents on it the caller may see, not counting any in the trash.
collection.createdAt number When it was made, in epoch milliseconds.
collection.updatedAt number When it last changed, in epoch milliseconds. Every change moves it on. collections.setItems takes it back as updatedAt.
collection.publishedAt number When it last went live, in epoch milliseconds, or null if it never has. Kept after a take-down. Can be null.
items array of objects The documents on it that the caller may see, not counting any in the trash, in the order collections.setItems set. The shelf applies the collection's sort when it shows them.
items[].documentId string The document's id.
items[].title string The document's title.
items[].state string The document's own state. One of draft, published, archived.
items[].currentVersion number The document's current version number, or null when it has none yet. Can be null.
items[].publication object The document's own publication, or null when it has none. Readers see the document on the shelf only while it is live, and only if its mode lets them open it. Can be null.
items[].publication.publicId string The document's own publication address: https://view.flipbird.io/v/{publicId}.
items[].publication.mode string Who may read the document, as a publication's mode says. One of public, unlisted, password, authenticated.
items[].publication.live boolean Whether the document's publication is live.

Example request

curl -X POST https://api.flipbird.io/api/v1/collections \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Spring catalogue"
}'
Example response
{
  "collection": {
    "id": "string",
    "publicId": "…",
    "title": "Spring catalogue",
    "description": "Our spring range.",
    "mode": "public",
    "live": true,
    "hasPassword": true,
    "seo": {
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "noindex": true
    },
    "appearanceId": "…",
    "layout": "grid",
    "sort": "manual",
    "kioskIdleSeconds": 1,
    "itemCount": 1,
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "publishedAt": 1767225600000
  },
  "items": [
    {
      "documentId": "…",
      "title": "Spring catalogue",
      "state": "draft",
      "currentVersion": 1,
      "publication": {
        "publicId": "…",
        "mode": "public",
        "live": true
      }
    }
  ]
}

Change a collection's title, description, layout, sort, look, SEO or kiosk setting

PATCH /collections/{collectionId} collections.update

Changes only the fields given: a field left out is kept. Null clears the look (back to the workspace's default) or the kiosk setting. A given seo replaces the stored SEO fields whole. Returns the collection and its documents as collections.get does. An unknown collection, or an appearanceId that is not a saved look, answers 404 not_found.

Scopes
documents.publish, documents.publish.manage
Plan
Bookshelves, on Pro, Enterprise
Retries
Safe with an Idempotency-Key
MCP tool
collections_update

Path parameters

NameTypeDescription
collectionId required string The collection's id. An id starting col_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
title string The collection's name, shown as the shelf's heading. 1 to 200 characters.
description string Text shown under the shelf's heading. Blank lines part its paragraphs; an empty string removes it. At most 1,000 characters.
layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
appearanceId string The saved look to show the shelf in, or null for the workspace's default look. An id that is not a saved look answers 404 not_found. An id starting apr_. Can be null.
seo object What the shelf's page tells search engines and link previews. Given, it replaces the stored fields whole.
seo.title string The page title. Not set, the page uses the collection's title. At most 120 characters.
seo.description string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
seo.noindex boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
kioskIdleSeconds integer Makes the collection a kiosk that returns to the shelf after this many seconds without a touch. Null makes it an ordinary shelf. 15 to 3,600. Can be null.

Response

200 OK. A JSON object:

Response fields (29)
NameTypeDescription
collection object The collection, with itemCount counting the documents in items.
collection.id string The collection's id.
collection.publicId string The collection's address, made when it is created and never changed: readers open it at https://view.flipbird.io/c/{publicId}.
collection.title string The collection's name, shown as the shelf's heading.
collection.description string Text shown under the heading, empty for none. Blank lines part its paragraphs.
collection.mode string Who may open the shelf. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter the collection's password first. authenticated: only signed-in members of the workspace. A new collection is unlisted and not live. One of public, unlisted, password, authenticated.
collection.live boolean Whether readers can open the shelf now. A new collection is not live until it is published.
collection.hasPassword boolean Whether a password is stored. Only a password collection keeps one: publishing in another mode drops it.
collection.seo object What the shelf's page tells search engines and link previews. A field not set is absent.
collection.seo.title optional string The page title. Not set, the page uses the collection's title. At most 120 characters.
collection.seo.description optional string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
collection.seo.noindex optional boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
collection.appearanceId string The saved look the shelf is shown in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
collection.layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
collection.sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
collection.kioskIdleSeconds integer Seconds without a touch before a kiosk returns to the shelf, or null when the collection is not a kiosk. A kiosk has large touch targets and a full-screen button, and each document opened from it carries a link back to the shelf. Can be null.
collection.itemCount integer How many documents on it the caller may see, not counting any in the trash.
collection.createdAt number When it was made, in epoch milliseconds.
collection.updatedAt number When it last changed, in epoch milliseconds. Every change moves it on. collections.setItems takes it back as updatedAt.
collection.publishedAt number When it last went live, in epoch milliseconds, or null if it never has. Kept after a take-down. Can be null.
items array of objects The documents on it that the caller may see, not counting any in the trash, in the order collections.setItems set. The shelf applies the collection's sort when it shows them.
items[].documentId string The document's id.
items[].title string The document's title.
items[].state string The document's own state. One of draft, published, archived.
items[].currentVersion number The document's current version number, or null when it has none yet. Can be null.
items[].publication object The document's own publication, or null when it has none. Readers see the document on the shelf only while it is live, and only if its mode lets them open it. Can be null.
items[].publication.publicId string The document's own publication address: https://view.flipbird.io/v/{publicId}.
items[].publication.mode string Who may read the document, as a publication's mode says. One of public, unlisted, password, authenticated.
items[].publication.live boolean Whether the document's publication is live.

Example request

curl -X PATCH https://api.flipbird.io/api/v1/collections/col_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Spring catalogue",
  "description": "Our spring range."
}'
Example response
{
  "collection": {
    "id": "string",
    "publicId": "…",
    "title": "Spring catalogue",
    "description": "Our spring range.",
    "mode": "public",
    "live": true,
    "hasPassword": true,
    "seo": {
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "noindex": true
    },
    "appearanceId": "…",
    "layout": "grid",
    "sort": "manual",
    "kioskIdleSeconds": 1,
    "itemCount": 1,
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "publishedAt": 1767225600000
  },
  "items": [
    {
      "documentId": "…",
      "title": "Spring catalogue",
      "state": "draft",
      "currentVersion": 1,
      "publication": {
        "publicId": "…",
        "mode": "public",
        "live": true
      }
    }
  ]
}

Set which documents a collection lists, in order

PUT /collections/{collectionId}/items collections.setItems

Sets the documents the caller may see, in the order the shelf shows them under the manual sort, at most 100. A document left out is taken off. Documents on it the caller cannot see, or that are in the trash, are kept where they are, and the documents given fill the other places in order. A document need not be published to be listed, but readers see it only while its own publication is live.

Letterheads cannot be listed. Give the collection's updatedAt: a collection changed since is refused with 409 changed, so another member's change is not lost. Other refusals: 404 not_found for a document the caller cannot see, a letterhead or a document in the trash; 400 invalid_request for a document listed twice; 400 too_many when the documents given and those kept would come to more than 100.

Returns the collection and its documents as collections.get does.

Scopes
documents.publish, documents.publish.manage
Plan
Bookshelves, on Pro, Enterprise
Retries
Safe with an Idempotency-Key
MCP tool
collections_set_items

Path parameters

NameTypeDescription
collectionId required string The collection's id. An id starting col_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
documentIds required array of strings The ids of the documents to list, in the order the shelf shows them under the manual sort. Each may appear once. At most 100 items.
updatedAt required integer The collection's updatedAt as the caller last read it, in epoch milliseconds. A collection changed since answers 409 changed. At least 0.

Response

200 OK. A JSON object:

Response fields (29)
NameTypeDescription
collection object The collection, with itemCount counting the documents in items.
collection.id string The collection's id.
collection.publicId string The collection's address, made when it is created and never changed: readers open it at https://view.flipbird.io/c/{publicId}.
collection.title string The collection's name, shown as the shelf's heading.
collection.description string Text shown under the heading, empty for none. Blank lines part its paragraphs.
collection.mode string Who may open the shelf. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter the collection's password first. authenticated: only signed-in members of the workspace. A new collection is unlisted and not live. One of public, unlisted, password, authenticated.
collection.live boolean Whether readers can open the shelf now. A new collection is not live until it is published.
collection.hasPassword boolean Whether a password is stored. Only a password collection keeps one: publishing in another mode drops it.
collection.seo object What the shelf's page tells search engines and link previews. A field not set is absent.
collection.seo.title optional string The page title. Not set, the page uses the collection's title. At most 120 characters.
collection.seo.description optional string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
collection.seo.noindex optional boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
collection.appearanceId string The saved look the shelf is shown in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
collection.layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
collection.sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
collection.kioskIdleSeconds integer Seconds without a touch before a kiosk returns to the shelf, or null when the collection is not a kiosk. A kiosk has large touch targets and a full-screen button, and each document opened from it carries a link back to the shelf. Can be null.
collection.itemCount integer How many documents on it the caller may see, not counting any in the trash.
collection.createdAt number When it was made, in epoch milliseconds.
collection.updatedAt number When it last changed, in epoch milliseconds. Every change moves it on. collections.setItems takes it back as updatedAt.
collection.publishedAt number When it last went live, in epoch milliseconds, or null if it never has. Kept after a take-down. Can be null.
items array of objects The documents on it that the caller may see, not counting any in the trash, in the order collections.setItems set. The shelf applies the collection's sort when it shows them.
items[].documentId string The document's id.
items[].title string The document's title.
items[].state string The document's own state. One of draft, published, archived.
items[].currentVersion number The document's current version number, or null when it has none yet. Can be null.
items[].publication object The document's own publication, or null when it has none. Readers see the document on the shelf only while it is live, and only if its mode lets them open it. Can be null.
items[].publication.publicId string The document's own publication address: https://view.flipbird.io/v/{publicId}.
items[].publication.mode string Who may read the document, as a publication's mode says. One of public, unlisted, password, authenticated.
items[].publication.live boolean Whether the document's publication is live.

Example request

curl -X PUT https://api.flipbird.io/api/v1/collections/col_7m2kq9vx4c8d1r5t6wnb/items \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "documentIds": [
    "doc_7m2kq9vx4c8d1r5t6wnb"
  ],
  "updatedAt": 1767225600000
}'
Example response
{
  "collection": {
    "id": "string",
    "publicId": "…",
    "title": "Spring catalogue",
    "description": "Our spring range.",
    "mode": "public",
    "live": true,
    "hasPassword": true,
    "seo": {
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "noindex": true
    },
    "appearanceId": "…",
    "layout": "grid",
    "sort": "manual",
    "kioskIdleSeconds": 1,
    "itemCount": 1,
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "publishedAt": 1767225600000
  },
  "items": [
    {
      "documentId": "…",
      "title": "Spring catalogue",
      "state": "draft",
      "currentVersion": 1,
      "publication": {
        "publicId": "…",
        "mode": "public",
        "live": true
      }
    }
  ]
}

Publish a collection, or change who may open it

PUT /collections/{collectionId}/publication collections.publish

Makes the collection live in mode, or changes the mode of a live one. The modes are a publication's: public (listed in the sitemap unless its seo.noindex is true), unlisted, password and authenticated (signed-in members of the workspace). A password collection needs a password the first time; afterwards leaving it out keeps the old one. Publishing a collection publishes none of its documents.

Each document on the shelf keeps its own publication and mode: a reader sees one only while it is live and they may open it. 400 password_required for password mode with no password given or stored; 404 not_found for an unknown collection. Returns the collection and its documents as collections.get does.

Scopes
documents.publish, documents.publish.manage
Plan
Bookshelves, on Pro, Enterprise
Retries
Safe with an Idempotency-Key
MCP tool
collections_publish

Path parameters

NameTypeDescription
collectionId required string The collection's id. An id starting col_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
mode required string Who may open the shelf. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter the collection's password first. authenticated: only signed-in members of the workspace. One of public, unlisted, password, authenticated.
password string The password readers enter, for password mode. Needed when none is stored; left out, the stored one is kept. Sending one asks every reader for it again, even if it is unchanged. Ignored in other modes, which drop any stored password. 8 to 200 characters.

Response

200 OK. A JSON object:

Response fields (29)
NameTypeDescription
collection object The collection, with itemCount counting the documents in items.
collection.id string The collection's id.
collection.publicId string The collection's address, made when it is created and never changed: readers open it at https://view.flipbird.io/c/{publicId}.
collection.title string The collection's name, shown as the shelf's heading.
collection.description string Text shown under the heading, empty for none. Blank lines part its paragraphs.
collection.mode string Who may open the shelf. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter the collection's password first. authenticated: only signed-in members of the workspace. A new collection is unlisted and not live. One of public, unlisted, password, authenticated.
collection.live boolean Whether readers can open the shelf now. A new collection is not live until it is published.
collection.hasPassword boolean Whether a password is stored. Only a password collection keeps one: publishing in another mode drops it.
collection.seo object What the shelf's page tells search engines and link previews. A field not set is absent.
collection.seo.title optional string The page title. Not set, the page uses the collection's title. At most 120 characters.
collection.seo.description optional string The page description. Not set, the page uses the collection's description, or a count of its documents when that is empty. At most 300 characters.
collection.seo.noindex optional boolean True keeps a public collection out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
collection.appearanceId string The saved look the shelf is shown in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
collection.layout string How the shelf shows its documents. grid: the documents' covers as a grid of cards. shelf: the covers standing on shelves. One of grid, shelf.
collection.sort string The order the shelf shows its documents in. manual: the order collections.setItems set. newest: the newest document first, by when it was made (a new version does not change it). title: by title, A to Z. One of manual, newest, title.
collection.kioskIdleSeconds integer Seconds without a touch before a kiosk returns to the shelf, or null when the collection is not a kiosk. A kiosk has large touch targets and a full-screen button, and each document opened from it carries a link back to the shelf. Can be null.
collection.itemCount integer How many documents on it the caller may see, not counting any in the trash.
collection.createdAt number When it was made, in epoch milliseconds.
collection.updatedAt number When it last changed, in epoch milliseconds. Every change moves it on. collections.setItems takes it back as updatedAt.
collection.publishedAt number When it last went live, in epoch milliseconds, or null if it never has. Kept after a take-down. Can be null.
items array of objects The documents on it that the caller may see, not counting any in the trash, in the order collections.setItems set. The shelf applies the collection's sort when it shows them.
items[].documentId string The document's id.
items[].title string The document's title.
items[].state string The document's own state. One of draft, published, archived.
items[].currentVersion number The document's current version number, or null when it has none yet. Can be null.
items[].publication object The document's own publication, or null when it has none. Readers see the document on the shelf only while it is live, and only if its mode lets them open it. Can be null.
items[].publication.publicId string The document's own publication address: https://view.flipbird.io/v/{publicId}.
items[].publication.mode string Who may read the document, as a publication's mode says. One of public, unlisted, password, authenticated.
items[].publication.live boolean Whether the document's publication is live.

Example request

curl -X PUT https://api.flipbird.io/api/v1/collections/col_7m2kq9vx4c8d1r5t6wnb/publication \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "public"
}'
Example response
{
  "collection": {
    "id": "string",
    "publicId": "…",
    "title": "Spring catalogue",
    "description": "Our spring range.",
    "mode": "public",
    "live": true,
    "hasPassword": true,
    "seo": {
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "noindex": true
    },
    "appearanceId": "…",
    "layout": "grid",
    "sort": "manual",
    "kioskIdleSeconds": 1,
    "itemCount": 1,
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "publishedAt": 1767225600000
  },
  "items": [
    {
      "documentId": "…",
      "title": "Spring catalogue",
      "state": "draft",
      "currentVersion": 1,
      "publication": {
        "publicId": "…",
        "mode": "public",
        "live": true
      }
    }
  ]
}

Take a collection down; its address is kept for a publish later

DELETE /collections/{collectionId}/publication collections.unpublish

Readers can no longer open the shelf. Its publicId is kept for a publish later. The documents on it stay published as they are. A collection that is not live, or does not exist, answers 404 not_found. Works whether or not the plan includes collections.

Scopes
documents.publish, documents.publish.manage
Retries
Safe with an Idempotency-Key
MCP tool
collections_unpublish

Path parameters

NameTypeDescription
collectionId required string The collection's id. An id starting col_.

Response

200 OK. An empty JSON object, {}.

Example request

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

Delete a collection

DELETE /collections/{collectionId} collections.delete

Deletes the collection and its list of documents. Its address stops working for good. The documents on it are not touched. An unknown collection answers 404 not_found. Works whether or not the plan includes collections.

Scopes
documents.publish, documents.publish.manage
Retries
Safe with an Idempotency-Key
MCP tool
collections_delete

Path parameters

NameTypeDescription
collectionId required string The collection's id. An id starting col_.

Response

200 OK. An empty JSON object, {}.

Example request

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

Errors

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

StatusCodeWhen
400password_requiredPublishing in password mode with no password given or stored.
400too_manyThe documents given, with any the caller cannot see that are kept, would be more than 100.
409changedThe collection changed since the updatedAt given. Read it again and repeat the change.
409conflictThe workspace already has 200 collections.