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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
collectionId required | string | The collection's id. An id starting col_. |
Response
200 OK. A JSON object:
Response fields (29)
| Name | Type | Description |
|---|---|---|
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.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
collectionId required | string | The collection's id. An id starting col_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
collectionId required | string | The collection's id. An id starting col_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
collectionId required | string | The collection's id. An id starting col_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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:
| Status | Code | When |
|---|---|---|
| 400 | password_required | Publishing in password mode with no password given or stored. |
| 400 | too_many | The documents given, with any the caller cannot see that are kept, would be more than 100. |
| 409 | changed | The collection changed since the updatedAt given. Read it again and repeat the change. |
| 409 | conflict | The workspace already has 200 collections. |