API

Publishing

Put a document in front of readers at a fixed address, choose who may read it, and schedule or expire it.

A document has at most one publication. The first publish gives it a publicId, and readers open it at https://view.flipbird.io/v/{publicId}. The address never changes: a new version shows at the same address, and a take-down keeps the publicId for a later publish. The viewer shows the current version once its pages are made; until then, pages on publications.get says whether readers see an earlier version or a page saying the document is being prepared.

The mode decides who may read it: public (anyone, and listed in the sitemap unless seo.noindex is true), unlisted (anyone with the address), password, or authenticated (signed-in members of the workspace). A publishAt in the future schedules the publish, and an expiresAt takes the publication down and archives the document. An hourly sweep runs both, normally within the hour after the time given.

The plan limits how many documents are live at once. A publish past the limit answers 402 plan_required, and a scheduled publish past it is dropped when its time comes. Whether other sites may frame the publication is a document setting, viewer.embed with viewer.embedOrigins, changed with documents.update. Publishing takes documents.publish and edit access to the document.

How a document is published

GET /documents/{documentId}/publication publications.get

Returns the document's publication, or null in publication when it has never been published or scheduled. A publication that was taken down is still returned, with live false: its publicId is kept for a republish. pages says whether readers can see the current version yet. Needs view access to the document; one the caller cannot open answers 404 not_found.

Scopes
documents.read
MCP tool
publications_get

Path parameters

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

Response

200 OK. A JSON object:

Response fields (16)
NameTypeDescription
publication object The document's publication, or null when it has never been published or scheduled. Can be null.
publication.publicId string The publication's address, which never changes: readers open it at https://view.flipbird.io/v/{publicId}. It is kept through new versions, take-downs and republishing.
publication.mode string Who may read it. public: anyone; listed in the viewer's sitemap and open to search engines unless seo.noindex is true. unlisted: anyone with the address; never listed, and search engines are asked not to index it. password: readers enter the publication's password first. authenticated: only signed-in members of the workspace. One of public, unlisted, password, authenticated.
publication.live boolean Whether readers can open it now. False after a take-down, and while a publish is only scheduled.
publication.hasPassword boolean Whether a password is stored. Only a password publication keeps one: publishing in another mode drops it.
publication.seo object What the page tells search engines and link previews. A field not set is absent.
publication.seo.title optional string The page title. Absent, the viewer uses the document's title.
publication.seo.description optional string The page description. Absent, the viewer uses the first words of the document.
publication.seo.noindex optional boolean True keeps a public publication out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
publication.appearanceId string The saved look the viewer renders it in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
publication.updatedAt number When the publication last changed, in epoch milliseconds.
publication.publishAt number When a scheduled publish goes live, in epoch milliseconds, or null when none is scheduled. The hourly sweep publishes it, normally within the hour after this time. Can be null.
publication.expiresAt number When the publication is taken down, in epoch milliseconds, or null for never. The hourly sweep takes it down, normally within the hour after this time, and archives the document. Can be null.
pages object Whether readers can see the current version yet. Null unless the publication is live and the document has a version. Can be null.
pages.state string ready: the viewer's pages for the current version are made. building: they are being made. failed: making them failed. One of ready, building, failed.
pages.earlierShown boolean While state is not ready: true when readers are shown an earlier version's pages meanwhile; false when they see that the document is being prepared, and cannot read it until the pages are made.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/publication \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "publication": {
    "publicId": "…",
    "mode": "public",
    "live": true,
    "hasPassword": true,
    "seo": {
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "noindex": true
    },
    "appearanceId": "…",
    "updatedAt": 1767225600000,
    "publishAt": 1767225600000,
    "expiresAt": 1767225600000
  },
  "pages": {
    "state": "ready",
    "earlierShown": true
  }
}

Publish a document, or change how it is shown

PUT /documents/{documentId}/publication publications.publish

Publishes the document now, or changes how a live publication is shown; with a publishAt in the future, schedules the publish instead. The first publish or schedule makes the publicId; every later one keeps it. Returns the publication as stored. Every call sets mode and replaces seo and the password setting; each field says what leaving it out does.

Publishing now sets the document's state to published, gives it its scan-to-open QR link, cancels any scheduled publish and queues the viewer's pages (publications.get reports them in pages). A document that is not live counts against the plan's limit on live publications: past it the publish is refused with 402 plan_required. A change to a publication already live is never refused for that.

Scheduling stores the settings and leaves the publication not live (live false, publishAt set) until the hourly sweep publishes it, normally within the hour after publishAt. The plan's limit is checked then: a schedule it refuses, or one whose document has no version by then, is cleared without publishing. A document already live cannot be scheduled (409 already_live): take it down first.

Other refusals: 409 nothing_to_publish when the document has no version; 400 password_required for password mode with no password given or stored; 400 expiry_past for an expiresAt that is not in the future; 400 expiry_before_publish when the expiry is not after a scheduled publishAt; 404 not_found for an appearanceId that is not a saved look; 403 forbidden when the caller may view the document but not edit it.

Scopes
documents.publish
Retries
Safe with an Idempotency-Key
MCP tool
publications_publish

Path parameters

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

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
mode required string Who may read it. public: anyone; listed in the viewer's sitemap unless seo.noindex is true. unlisted: anyone with the address; never listed. password: readers enter 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.
appearanceId string The saved look to render it in, or null for the workspace's default look. Left out, the publication keeps the saved look it has; when it has none (a first publish, or the default look), it takes the document's own appearanceId. An id starting apr_. Can be null.
seo object What the page tells search engines and link previews. Replaced whole on every call: left out, the stored fields are cleared.
seo.title string The page title. Left out, the viewer uses the document's title. At most 120 characters.
seo.description string The page description. Left out, the viewer uses the first words of the document. At most 300 characters.
seo.noindex boolean True keeps a public publication out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
publishAt integer When to publish, in epoch milliseconds. A time in the future schedules the publish for then; null, left out or a time already past publishes now. More than 0. Can be null.
expiresAt integer When to take the publication down, in epoch milliseconds: in the future, and after publishAt when scheduling. The hourly sweep then takes it down and archives the document. Null clears it. Left out, the stored one is kept, unless it has already passed, when it is cleared. More than 0. Can be null.

Response

200 OK. A JSON object:

Response fields (13)
NameTypeDescription
publication object The publication as stored: live, or scheduled with publishAt set.
publication.publicId string The publication's address, which never changes: readers open it at https://view.flipbird.io/v/{publicId}. It is kept through new versions, take-downs and republishing.
publication.mode string Who may read it. public: anyone; listed in the viewer's sitemap and open to search engines unless seo.noindex is true. unlisted: anyone with the address; never listed, and search engines are asked not to index it. password: readers enter the publication's password first. authenticated: only signed-in members of the workspace. One of public, unlisted, password, authenticated.
publication.live boolean Whether readers can open it now. False after a take-down, and while a publish is only scheduled.
publication.hasPassword boolean Whether a password is stored. Only a password publication keeps one: publishing in another mode drops it.
publication.seo object What the page tells search engines and link previews. A field not set is absent.
publication.seo.title optional string The page title. Absent, the viewer uses the document's title.
publication.seo.description optional string The page description. Absent, the viewer uses the first words of the document.
publication.seo.noindex optional boolean True keeps a public publication out of the sitemap and asks search engines not to index it. The other modes always ask them not to.
publication.appearanceId string The saved look the viewer renders it in, or null for the workspace's default look (the built-in look when the workspace has none). Can be null.
publication.updatedAt number When the publication last changed, in epoch milliseconds.
publication.publishAt number When a scheduled publish goes live, in epoch milliseconds, or null when none is scheduled. The hourly sweep publishes it, normally within the hour after this time. Can be null.
publication.expiresAt number When the publication is taken down, in epoch milliseconds, or null for never. The hourly sweep takes it down, normally within the hour after this time, and archives the document. Can be null.

Example request

curl -X PUT https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/publication \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "public"
}'
Example response
{
  "publication": {
    "publicId": "…",
    "mode": "public",
    "live": true,
    "hasPassword": true,
    "seo": {
      "title": "Spring catalogue",
      "description": "Our spring range.",
      "noindex": true
    },
    "appearanceId": "…",
    "updatedAt": 1767225600000,
    "publishAt": 1767225600000,
    "expiresAt": 1767225600000
  }
}

Take a document down; its address is kept for a republish

DELETE /documents/{documentId}/publication publications.unpublish

Takes a live publication down: readers can no longer open it, the document goes back to draft (or to archived with archive=true), its expiresAt is cleared, its scan-to-open QR link is archived and the viewer's copies of its pages are deleted. The publicId is kept, so a later publish brings the same address back.

A publication that is not live but has a scheduled publish has the schedule cancelled instead, and archive is ignored. Anything else answers 404 not_found. 403 forbidden when the caller may view the document but not edit it.

Scopes
documents.publish
Retries
Safe with an Idempotency-Key
MCP tool
publications_unpublish

Path parameters

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

Query parameters

NameTypeDescription
archive string true archives the document as it is taken down; false or left out returns it to draft. One of true, false.

Response

200 OK. An empty JSON object, {}.

Example request

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

Errors

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

StatusCodeWhen
400password_requiredpassword mode with no password given or stored.
400expiry_pastexpiresAt is not in the future.
400expiry_before_publishexpiresAt is not after a scheduled publishAt.
409nothing_to_publishThe document has no version yet.
409already_liveScheduling a document that is already live. Take it down first.