API

Documents

List, read, make and change documents, and read and download their versions.

A document is a titled, filed PDF with a history of versions. documents.create makes it empty, and each upload or saved edit adds a version, numbered from 1. currentVersion is the newest version not in the trash; exports, recognition and the publication use it unless told otherwise. A version's bytes and sha256 never change, so they can be cached for good. Its thumbnail can change: a letterhead change makes it again at the same address, with a new ETag. A thumbnail no longer the newest for its version is deleted 30 days after it was made, and made again if it is asked for.

Documents sit in folders, paths such as /marketing/2026/, and carry lower-case tags. A member sees and changes only what their role and the workspace's folder and document grants allow. A document they cannot see is 404 not_found; one they can see but not change is 403 forbidden, and documents.get says which with canEdit.

state follows the publication: draft until published, published while live, and archived once taken down to the archive or expired. New versions are encrypted unless the Owner turns that off. Letterheads are documents of kind letterhead, listed apart; a choice at the page, document, member or workspace level draws one on other documents' pages.

A version made from another kind of file, a Word (.docx), OpenDocument text (.odt), RTF, Markdown, plain text, HTML or CSV file converted to PDF before upload, can keep that file beside it: documents.storeOriginal stores it once, its structure checked, and documents.downloadOriginal gives it back as it was. A version's original, and a document's currentOriginal, name it, or are null. An original is encrypted when its version is, counts toward the plan's storage, and is deleted with its version.

List documents, newest change first

GET /documents documents.list

Lists the documents the caller can see, limit at a time. Documents in the trash are not listed (see documents.listTrash), and letterheads only with kind=letterhead. Sorted by sort (updated, the default; created; title; pages) in order (newest, most pages or A to Z unless given).

Pages resume from nextCursor, which is valid only with the same sort and order; a cursor made for another sort is 400 invalid_request. A document whose sort key changes while you page (an edit for updated, a rename for title, a new version for pages) can move across a page boundary; created never moves.

search takes up to 6 words, and every word must match: part of the title, the start of a tag, or, for a word of 3 characters or more, the start of a word in the text of the document's live publication (lower-cased and accent-folded). An invalid folder path is 400 invalid.

Scopes
documents.read
MCP tool
documents_list

Query parameters

NameTypeDescription
folder string Only documents in this folder and the folders inside it, such as /marketing/. Default /, every folder. At most 1,100 characters.
cursor string nextCursor from the previous page, with the same sort and order. Omit it for the first page. Matches ^(?:-?\d{1,16}|t[A-Za-z0-9_-]{0,1100})\.doc_[0-9a-z]{20}$.
limit integer Most documents to return. Default 50. 1 to 200.
q string Only documents whose title contains this text, ignoring case. At most 200 characters.
search string Words that must all match the title, a tag or, for words of 3 characters or more, the live publication's text. Only the first 6 words are used. At most 200 characters.
tag string Only documents carrying this tag. 1 to 40 characters.
sort string What to sort by: updated (last change), created, title, or pages (the current version's page count; a count not yet known sorts below every other). Default updated. One of updated, created, title, pages.
order string Sort direction. Default asc for title and desc for the others. One of asc, desc.
state string Only documents in this state. One of draft, published, archived.
kind string letterhead lists the letterheads instead. Default document. One of document, letterhead.
updatedFrom integer Only documents last changed at or after this time, epoch milliseconds. 0 to 8,640,000,000,000.
updatedTo integer Only documents last changed at or before this time, epoch milliseconds. 0 to 8,640,000,000,000.

Response

200 OK. A JSON object:

Response fields (47)
NameTypeDescription
documents array of objects This page of documents.
documents[].id string The document's id.
documents[].title string The document's title.
documents[].folder string The folder it is filed in: a path that starts and ends with /, such as /marketing/2026/. / is the top level.
documents[].tags array of strings Its tags, lower-cased, in alphabetical order.
documents[].state string draft: not published (new, taken down, or moved to the trash). published: its publication is live. archived: its publication was taken down to the archive, or reached its expiry. One of draft, published, archived.
documents[].encrypted boolean Whether versions uploaded from now on are stored encrypted. On for every new document; only the workspace Owner can turn it off.
documents[].currentVersion number The number of its current version: the newest one not in the trash. Null when it has none. Can be null.
documents[].currentOriginal object The file the current version's PDF was converted from, kept as it was uploaded: download it with documents.downloadOriginal for currentVersion. Null when the current version has none, or there is no current version. Can be null.
documents[].currentOriginal.filename string The name the file was uploaded with, which its download is named from. Empty when none was given.
documents[].currentOriginal.format string What it is: docx (Word), odt (OpenDocument text), rtf, markdown, text (plain text), html or csv. One of docx, odt, rtf, markdown, text, html, csv.
documents[].currentOriginal.size number Its size in bytes.
documents[].createdBy string The user id of the member who made it, or null when no member did. Can be null.
documents[].createdAt number When it was made, epoch milliseconds.
documents[].updatedAt number When it last changed, epoch milliseconds.
documents[].deletedAt number When it was moved to the trash, epoch milliseconds. Null unless it is in the trash. Can be null.
documents[].appearanceId string The appearance profile its flipbook and offline exports are drawn in, or null to use the workspace's default look. Can be null.
documents[].viewer object How the hosted viewer shows it once published.
documents[].viewer.download boolean Readers of the publication may download the PDF. Off unless turned on.
documents[].viewer.embed boolean Other sites may frame the publication's embed. On unless turned off.
documents[].viewer.embedOrigins array of strings When not empty, the only sites that may frame the embed, as origins such as https://www.example.com (no path). Empty lets any site frame it.
documents[].signing string Whether its content is locked for signing. Null: not signed and no open signing request. requested: a signing request is open and nobody has signed yet. signed: it holds at least one signature. While it is not null, new versions, editor saves, reverts and version trash or restore answer 409 signing_locked; title, folder, tags, publishing and exports stay open. One of requested, signed. Can be null.
documents[].kind string document for an ordinary document. letterhead for a letterhead, which is listed apart from the document library and drawn on other documents' pages. One of document, letterhead.
documents[].imageLayout object How the picture this document was made from is placed on its page. Null when it was not made from a picture. Can be null.
documents[].imageLayout.fit string contain fits the whole picture inside the margins and leaves the spare space empty; cover fills the space inside the margins and crops what overflows. One of cover, contain.
documents[].imageLayout.alignX string Which side the picture keeps to across the space inside the margins; any spare space, or the part cover crops away, is on the other side. center splits it. One of left, center, right.
documents[].imageLayout.alignY string Which edge the picture keeps to down the space inside the margins; any spare space, or the part cover crops away, is at the other edge. center splits it. One of top, center, bottom.
documents[].imageLayout.pageWidth number The page's width in PDF points (1/72 inch). More than 0. At most 14,400.
documents[].imageLayout.pageHeight number The page's height in PDF points. More than 0. At most 14,400.
documents[].imageLayout.marginTop number Space kept clear at the top of the page, in PDF points. 0 to 5,000.
documents[].imageLayout.marginRight number Space kept clear at the right of the page, in PDF points. 0 to 5,000.
documents[].imageLayout.marginBottom number Space kept clear at the bottom of the page, in PDF points. 0 to 5,000.
documents[].imageLayout.marginLeft number Space kept clear at the left of the page, in PDF points. 0 to 5,000.
documents[].imageLayout.imageWidth number The picture's width in pixels. With imageHeight it gives the shape the fit keeps. More than 0. At most 100,000.
documents[].imageLayout.imageHeight number The picture's height in pixels. More than 0. At most 100,000.
documents[].imageLayout.assetId string The original picture, kept in the image library, or null when none was kept. An id starting ast_. Can be null.
documents[].letterhead object The document-level letterhead choice. inherit means the document has not chosen. One of 3 shapes, chosen by mode.
documents[].letterhead.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
documents[].letterhead.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
documents[].letterhead.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.
documents[].letterheadPages array of objects Pages with a letterhead choice of their own, by page number. Every other page follows the document-level choice.
documents[].letterheadPages[].page integer The page number, 1-based.
documents[].letterheadPages[].choice object That page's own choice. One of 3 shapes, chosen by mode.
documents[].letterheadPages[].choice.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
documents[].letterheadPages[].choice.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
documents[].letterheadPages[].choice.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.
nextCursor string Pass it as cursor for the next page. Null when there are no more; a full page can be followed by an empty one. Can be null.

Example request

curl https://api.flipbird.io/api/v1/documents \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "documents": [
    {
      "id": "string",
      "title": "Spring catalogue",
      "folder": "/catalogues",
      "tags": [
        "spring"
      ],
      "state": "draft",
      "encrypted": true,
      "currentVersion": 1,
      "currentOriginal": {
        "filename": "catalogue.pdf",
        "format": "docx",
        "size": 1
      },
      "createdBy": "string",
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000,
      "deletedAt": 1767225600000,
      "appearanceId": "…",
      "viewer": {
        "download": true,
        "embed": true,
        "embedOrigins": [
          "string"
        ]
      },
      "signing": "requested",
      "kind": "document",
      "imageLayout": {
        "fit": "cover",
        "alignX": "left",
        "alignY": "top",
        "pageWidth": 1,
        "pageHeight": 1,
        "marginTop": 1,
        "marginRight": 1,
        "marginBottom": 1,
        "marginLeft": 1,
        "imageWidth": 1,
        "imageHeight": 1,
        "assetId": "ast_7m2kq9vx4c8d1r5t6wnb"
      },
      "letterhead": {
        "mode": "inherit"
      },
      "letterheadPages": [
        {
          "page": 1,
          "choice": {
            "mode": "inherit"
          }
        }
      ]
    }
  ],
  "nextCursor": "string"
}

A document

GET /documents/{documentId} documents.get

canEdit says whether the caller may change it: edit it, upload a version, publish it or set its lead form. A Standard member may change only the documents they made and those they hold an edit grant on. A document the caller cannot see, or one in the trash, is 404 not_found.

Scopes
documents.read
MCP tool
documents_get

Path parameters

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

Response

200 OK. A JSON object:

Response fields (46)
NameTypeDescription
id string The document's id.
title string The document's title.
folder string The folder it is filed in: a path that starts and ends with /, such as /marketing/2026/. / is the top level.
tags array of strings Its tags, lower-cased, in alphabetical order.
state string draft: not published (new, taken down, or moved to the trash). published: its publication is live. archived: its publication was taken down to the archive, or reached its expiry. One of draft, published, archived.
encrypted boolean Whether versions uploaded from now on are stored encrypted. On for every new document; only the workspace Owner can turn it off.
currentVersion number The number of its current version: the newest one not in the trash. Null when it has none. Can be null.
currentOriginal object The file the current version's PDF was converted from, kept as it was uploaded: download it with documents.downloadOriginal for currentVersion. Null when the current version has none, or there is no current version. Can be null.
currentOriginal.filename string The name the file was uploaded with, which its download is named from. Empty when none was given.
currentOriginal.format string What it is: docx (Word), odt (OpenDocument text), rtf, markdown, text (plain text), html or csv. One of docx, odt, rtf, markdown, text, html, csv.
currentOriginal.size number Its size in bytes.
createdBy string The user id of the member who made it, or null when no member did. Can be null.
createdAt number When it was made, epoch milliseconds.
updatedAt number When it last changed, epoch milliseconds.
deletedAt number When it was moved to the trash, epoch milliseconds. Null unless it is in the trash. Can be null.
appearanceId string The appearance profile its flipbook and offline exports are drawn in, or null to use the workspace's default look. Can be null.
viewer object How the hosted viewer shows it once published.
viewer.download boolean Readers of the publication may download the PDF. Off unless turned on.
viewer.embed boolean Other sites may frame the publication's embed. On unless turned off.
viewer.embedOrigins array of strings When not empty, the only sites that may frame the embed, as origins such as https://www.example.com (no path). Empty lets any site frame it.
signing string Whether its content is locked for signing. Null: not signed and no open signing request. requested: a signing request is open and nobody has signed yet. signed: it holds at least one signature. While it is not null, new versions, editor saves, reverts and version trash or restore answer 409 signing_locked; title, folder, tags, publishing and exports stay open. One of requested, signed. Can be null.
kind string document for an ordinary document. letterhead for a letterhead, which is listed apart from the document library and drawn on other documents' pages. One of document, letterhead.
imageLayout object How the picture this document was made from is placed on its page. Null when it was not made from a picture. Can be null.
imageLayout.fit string contain fits the whole picture inside the margins and leaves the spare space empty; cover fills the space inside the margins and crops what overflows. One of cover, contain.
imageLayout.alignX string Which side the picture keeps to across the space inside the margins; any spare space, or the part cover crops away, is on the other side. center splits it. One of left, center, right.
imageLayout.alignY string Which edge the picture keeps to down the space inside the margins; any spare space, or the part cover crops away, is at the other edge. center splits it. One of top, center, bottom.
imageLayout.pageWidth number The page's width in PDF points (1/72 inch). More than 0. At most 14,400.
imageLayout.pageHeight number The page's height in PDF points. More than 0. At most 14,400.
imageLayout.marginTop number Space kept clear at the top of the page, in PDF points. 0 to 5,000.
imageLayout.marginRight number Space kept clear at the right of the page, in PDF points. 0 to 5,000.
imageLayout.marginBottom number Space kept clear at the bottom of the page, in PDF points. 0 to 5,000.
imageLayout.marginLeft number Space kept clear at the left of the page, in PDF points. 0 to 5,000.
imageLayout.imageWidth number The picture's width in pixels. With imageHeight it gives the shape the fit keeps. More than 0. At most 100,000.
imageLayout.imageHeight number The picture's height in pixels. More than 0. At most 100,000.
imageLayout.assetId string The original picture, kept in the image library, or null when none was kept. An id starting ast_. Can be null.
letterhead object The document-level letterhead choice. inherit means the document has not chosen. One of 3 shapes, chosen by mode.
letterhead.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
letterhead.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterhead.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.
letterheadPages array of objects Pages with a letterhead choice of their own, by page number. Every other page follows the document-level choice.
letterheadPages[].page integer The page number, 1-based.
letterheadPages[].choice object That page's own choice. One of 3 shapes, chosen by mode.
letterheadPages[].choice.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
letterheadPages[].choice.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterheadPages[].choice.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.
canEdit boolean Whether the caller may change the document: edit it, upload a version, publish it or set its lead form.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "id": "string",
  "title": "Spring catalogue",
  "folder": "/catalogues",
  "tags": [
    "spring"
  ],
  "state": "draft",
  "encrypted": true,
  "currentVersion": 1,
  "currentOriginal": {
    "filename": "catalogue.pdf",
    "format": "docx",
    "size": 1
  },
  "createdBy": "string",
  "createdAt": 1767225600000,
  "updatedAt": 1767225600000,
  "deletedAt": 1767225600000,
  "appearanceId": "…",
  "viewer": {
    "download": true,
    "embed": true,
    "embedOrigins": [
      "string"
    ]
  },
  "signing": "requested",
  "kind": "document",
  "imageLayout": {
    "fit": "cover",
    "alignX": "left",
    "alignY": "top",
    "pageWidth": 1,
    "pageHeight": 1,
    "marginTop": 1,
    "marginRight": 1,
    "marginBottom": 1,
    "marginLeft": 1,
    "imageWidth": 1,
    "imageHeight": 1,
    "assetId": "ast_7m2kq9vx4c8d1r5t6wnb"
  },
  "letterhead": {
    "mode": "inherit"
  },
  "letterheadPages": [
    {
      "page": 1,
      "choice": {
        "mode": "inherit"
      }
    }
  ],
  "canEdit": true
}

Make an empty document to upload versions into

POST /documents documents.create

Makes an empty draft document with no version, encrypted. Upload its first version with uploads.start (or in one call with uploads.inline, which can also make the document). A folder the caller cannot edit is 403 forbidden (404 not_found when they cannot see it), and an invalid folder path or title is 400 invalid. Making a letterhead needs the documents.edit.any scope (403 forbidden).

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
documents_create

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
title required string The document's title, 1 to 200 characters. 1 to 200 characters.
folder string The folder to file it in, such as /marketing/2026/. Default /, the top level. At most 1,100 characters.
tags array of strings Up to 30 tags of up to 40 characters. They are stored lower-cased, once each. At most 30 items.
kind string letterhead makes a letterhead instead of a document. Default document. One of document, letterhead.

Response

201 Created. A JSON object:

Response fields (45)
NameTypeDescription
id string The document's id.
title string The document's title.
folder string The folder it is filed in: a path that starts and ends with /, such as /marketing/2026/. / is the top level.
tags array of strings Its tags, lower-cased, in alphabetical order.
state string draft: not published (new, taken down, or moved to the trash). published: its publication is live. archived: its publication was taken down to the archive, or reached its expiry. One of draft, published, archived.
encrypted boolean Whether versions uploaded from now on are stored encrypted. On for every new document; only the workspace Owner can turn it off.
currentVersion number The number of its current version: the newest one not in the trash. Null when it has none. Can be null.
currentOriginal object The file the current version's PDF was converted from, kept as it was uploaded: download it with documents.downloadOriginal for currentVersion. Null when the current version has none, or there is no current version. Can be null.
currentOriginal.filename string The name the file was uploaded with, which its download is named from. Empty when none was given.
currentOriginal.format string What it is: docx (Word), odt (OpenDocument text), rtf, markdown, text (plain text), html or csv. One of docx, odt, rtf, markdown, text, html, csv.
currentOriginal.size number Its size in bytes.
createdBy string The user id of the member who made it, or null when no member did. Can be null.
createdAt number When it was made, epoch milliseconds.
updatedAt number When it last changed, epoch milliseconds.
deletedAt number When it was moved to the trash, epoch milliseconds. Null unless it is in the trash. Can be null.
appearanceId string The appearance profile its flipbook and offline exports are drawn in, or null to use the workspace's default look. Can be null.
viewer object How the hosted viewer shows it once published.
viewer.download boolean Readers of the publication may download the PDF. Off unless turned on.
viewer.embed boolean Other sites may frame the publication's embed. On unless turned off.
viewer.embedOrigins array of strings When not empty, the only sites that may frame the embed, as origins such as https://www.example.com (no path). Empty lets any site frame it.
signing string Whether its content is locked for signing. Null: not signed and no open signing request. requested: a signing request is open and nobody has signed yet. signed: it holds at least one signature. While it is not null, new versions, editor saves, reverts and version trash or restore answer 409 signing_locked; title, folder, tags, publishing and exports stay open. One of requested, signed. Can be null.
kind string document for an ordinary document. letterhead for a letterhead, which is listed apart from the document library and drawn on other documents' pages. One of document, letterhead.
imageLayout object How the picture this document was made from is placed on its page. Null when it was not made from a picture. Can be null.
imageLayout.fit string contain fits the whole picture inside the margins and leaves the spare space empty; cover fills the space inside the margins and crops what overflows. One of cover, contain.
imageLayout.alignX string Which side the picture keeps to across the space inside the margins; any spare space, or the part cover crops away, is on the other side. center splits it. One of left, center, right.
imageLayout.alignY string Which edge the picture keeps to down the space inside the margins; any spare space, or the part cover crops away, is at the other edge. center splits it. One of top, center, bottom.
imageLayout.pageWidth number The page's width in PDF points (1/72 inch). More than 0. At most 14,400.
imageLayout.pageHeight number The page's height in PDF points. More than 0. At most 14,400.
imageLayout.marginTop number Space kept clear at the top of the page, in PDF points. 0 to 5,000.
imageLayout.marginRight number Space kept clear at the right of the page, in PDF points. 0 to 5,000.
imageLayout.marginBottom number Space kept clear at the bottom of the page, in PDF points. 0 to 5,000.
imageLayout.marginLeft number Space kept clear at the left of the page, in PDF points. 0 to 5,000.
imageLayout.imageWidth number The picture's width in pixels. With imageHeight it gives the shape the fit keeps. More than 0. At most 100,000.
imageLayout.imageHeight number The picture's height in pixels. More than 0. At most 100,000.
imageLayout.assetId string The original picture, kept in the image library, or null when none was kept. An id starting ast_. Can be null.
letterhead object The document-level letterhead choice. inherit means the document has not chosen. One of 3 shapes, chosen by mode.
letterhead.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
letterhead.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterhead.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.
letterheadPages array of objects Pages with a letterhead choice of their own, by page number. Every other page follows the document-level choice.
letterheadPages[].page integer The page number, 1-based.
letterheadPages[].choice object That page's own choice. One of 3 shapes, chosen by mode.
letterheadPages[].choice.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
letterheadPages[].choice.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterheadPages[].choice.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.

Example request

curl -X POST https://api.flipbird.io/api/v1/documents \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Spring catalogue"
}'
Example response
{
  "id": "string",
  "title": "Spring catalogue",
  "folder": "/catalogues",
  "tags": [
    "spring"
  ],
  "state": "draft",
  "encrypted": true,
  "currentVersion": 1,
  "currentOriginal": {
    "filename": "catalogue.pdf",
    "format": "docx",
    "size": 1
  },
  "createdBy": "string",
  "createdAt": 1767225600000,
  "updatedAt": 1767225600000,
  "deletedAt": 1767225600000,
  "appearanceId": "…",
  "viewer": {
    "download": true,
    "embed": true,
    "embedOrigins": [
      "string"
    ]
  },
  "signing": "requested",
  "kind": "document",
  "imageLayout": {
    "fit": "cover",
    "alignX": "left",
    "alignY": "top",
    "pageWidth": 1,
    "pageHeight": 1,
    "marginTop": 1,
    "marginRight": 1,
    "marginBottom": 1,
    "marginLeft": 1,
    "imageWidth": 1,
    "imageHeight": 1,
    "assetId": "ast_7m2kq9vx4c8d1r5t6wnb"
  },
  "letterhead": {
    "mode": "inherit"
  },
  "letterheadPages": [
    {
      "page": 1,
      "choice": {
        "mode": "inherit"
      }
    }
  ]
}

Rename, move or retag a document, or change how the viewer shows it

PATCH /documents/{documentId} documents.update

Changes only the fields given and answers with the document. viewer.download lets readers of the publication download the PDF: turning it on makes a live publication's download copy, and turning it off deletes it. viewer.embed lets other sites frame its embed, and viewer.embedOrigins, when not empty, names the only sites that may (origins such as https://www.example.com).

A letterhead change queues the thumbnail and a live publication's pages again under the new letterhead. Needs edit access to the document (403 forbidden), and to the folder it moves to. An unknown appearance profile or letterhead is 404 not_found.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
documents_update

Path parameters

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

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
title string A new title, 1 to 200 characters. 1 to 200 characters.
folder string Move it to this folder, such as /marketing/2026/. At most 1,100 characters.
tags array of strings Replace its tags with these: up to 30 of up to 40 characters, stored lower-cased. At most 30 items.
appearanceId string The appearance profile its flipbook and offline exports are drawn in, or null to use the workspace's default look. An id starting apr_. Can be null.
viewer object How the hosted viewer shows it once published. Fields left out keep their value.
viewer.download boolean Whether readers of the publication may download the PDF.
viewer.embed boolean Whether other sites may frame the publication's embed.
viewer.embedOrigins array of strings When not empty, the only sites that may frame the embed, as origins such as https://www.example.com (no path), at most 20. Empty lets any site frame it. At most 20 items.
imageLayout object Replace how the picture this document was made from is placed on its page, or null to clear it. It is a record for the client that rebuilds the page from the original picture: storing it changes no version. Can be null.
imageLayout.fit required string contain fits the whole picture inside the margins and leaves the spare space empty; cover fills the space inside the margins and crops what overflows. One of cover, contain.
imageLayout.alignX required string Which side the picture keeps to across the space inside the margins; any spare space, or the part cover crops away, is on the other side. center splits it. One of left, center, right.
imageLayout.alignY required string Which edge the picture keeps to down the space inside the margins; any spare space, or the part cover crops away, is at the other edge. center splits it. One of top, center, bottom.
imageLayout.pageWidth required number The page's width in PDF points (1/72 inch). More than 0. At most 14,400.
imageLayout.pageHeight required number The page's height in PDF points. More than 0. At most 14,400.
imageLayout.marginTop required number Space kept clear at the top of the page, in PDF points. 0 to 5,000.
imageLayout.marginRight required number Space kept clear at the right of the page, in PDF points. 0 to 5,000.
imageLayout.marginBottom required number Space kept clear at the bottom of the page, in PDF points. 0 to 5,000.
imageLayout.marginLeft required number Space kept clear at the left of the page, in PDF points. 0 to 5,000.
imageLayout.imageWidth required number The picture's width in pixels. With imageHeight it gives the shape the fit keeps. More than 0. At most 100,000.
imageLayout.imageHeight required number The picture's height in pixels. More than 0. At most 100,000.
imageLayout.assetId required string The original picture, kept in the image library, or null when none was kept. An id starting ast_. Can be null.
letterhead object The document-level letterhead choice. inherit clears it. One of 3 shapes, chosen by mode.
letterhead.mode required string No choice at this level: the next broader level decides. One of inherit, none, use.
letterhead.id required string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterhead.placement required string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.
letterheadPage object One page's letterhead choice.
letterheadPage.page required integer The page number, 1-based. 1 to 10,000.
letterheadPage.choice required object That page's own choice. inherit removes it, so the page follows the document-level choice. One of 3 shapes, chosen by mode.
letterheadPage.choice.mode required string No choice at this level: the next broader level decides. One of inherit, none, use.
letterheadPage.choice.id required string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterheadPage.choice.placement required string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.

Response

200 OK. A JSON object:

Response fields (45)
NameTypeDescription
id string The document's id.
title string The document's title.
folder string The folder it is filed in: a path that starts and ends with /, such as /marketing/2026/. / is the top level.
tags array of strings Its tags, lower-cased, in alphabetical order.
state string draft: not published (new, taken down, or moved to the trash). published: its publication is live. archived: its publication was taken down to the archive, or reached its expiry. One of draft, published, archived.
encrypted boolean Whether versions uploaded from now on are stored encrypted. On for every new document; only the workspace Owner can turn it off.
currentVersion number The number of its current version: the newest one not in the trash. Null when it has none. Can be null.
currentOriginal object The file the current version's PDF was converted from, kept as it was uploaded: download it with documents.downloadOriginal for currentVersion. Null when the current version has none, or there is no current version. Can be null.
currentOriginal.filename string The name the file was uploaded with, which its download is named from. Empty when none was given.
currentOriginal.format string What it is: docx (Word), odt (OpenDocument text), rtf, markdown, text (plain text), html or csv. One of docx, odt, rtf, markdown, text, html, csv.
currentOriginal.size number Its size in bytes.
createdBy string The user id of the member who made it, or null when no member did. Can be null.
createdAt number When it was made, epoch milliseconds.
updatedAt number When it last changed, epoch milliseconds.
deletedAt number When it was moved to the trash, epoch milliseconds. Null unless it is in the trash. Can be null.
appearanceId string The appearance profile its flipbook and offline exports are drawn in, or null to use the workspace's default look. Can be null.
viewer object How the hosted viewer shows it once published.
viewer.download boolean Readers of the publication may download the PDF. Off unless turned on.
viewer.embed boolean Other sites may frame the publication's embed. On unless turned off.
viewer.embedOrigins array of strings When not empty, the only sites that may frame the embed, as origins such as https://www.example.com (no path). Empty lets any site frame it.
signing string Whether its content is locked for signing. Null: not signed and no open signing request. requested: a signing request is open and nobody has signed yet. signed: it holds at least one signature. While it is not null, new versions, editor saves, reverts and version trash or restore answer 409 signing_locked; title, folder, tags, publishing and exports stay open. One of requested, signed. Can be null.
kind string document for an ordinary document. letterhead for a letterhead, which is listed apart from the document library and drawn on other documents' pages. One of document, letterhead.
imageLayout object How the picture this document was made from is placed on its page. Null when it was not made from a picture. Can be null.
imageLayout.fit string contain fits the whole picture inside the margins and leaves the spare space empty; cover fills the space inside the margins and crops what overflows. One of cover, contain.
imageLayout.alignX string Which side the picture keeps to across the space inside the margins; any spare space, or the part cover crops away, is on the other side. center splits it. One of left, center, right.
imageLayout.alignY string Which edge the picture keeps to down the space inside the margins; any spare space, or the part cover crops away, is at the other edge. center splits it. One of top, center, bottom.
imageLayout.pageWidth number The page's width in PDF points (1/72 inch). More than 0. At most 14,400.
imageLayout.pageHeight number The page's height in PDF points. More than 0. At most 14,400.
imageLayout.marginTop number Space kept clear at the top of the page, in PDF points. 0 to 5,000.
imageLayout.marginRight number Space kept clear at the right of the page, in PDF points. 0 to 5,000.
imageLayout.marginBottom number Space kept clear at the bottom of the page, in PDF points. 0 to 5,000.
imageLayout.marginLeft number Space kept clear at the left of the page, in PDF points. 0 to 5,000.
imageLayout.imageWidth number The picture's width in pixels. With imageHeight it gives the shape the fit keeps. More than 0. At most 100,000.
imageLayout.imageHeight number The picture's height in pixels. More than 0. At most 100,000.
imageLayout.assetId string The original picture, kept in the image library, or null when none was kept. An id starting ast_. Can be null.
letterhead object The document-level letterhead choice. inherit means the document has not chosen. One of 3 shapes, chosen by mode.
letterhead.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
letterhead.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterhead.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.
letterheadPages array of objects Pages with a letterhead choice of their own, by page number. Every other page follows the document-level choice.
letterheadPages[].page integer The page number, 1-based.
letterheadPages[].choice object That page's own choice. One of 3 shapes, chosen by mode.
letterheadPages[].choice.mode string No choice at this level: the next broader level decides. One of inherit, none, use.
letterheadPages[].choice.id string The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_.
letterheadPages[].choice.placement string background draws the letterhead behind the page's content; foreground draws it over the content. Only when mode is use. One of background, foreground.

Example request

curl -X PATCH https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Spring catalogue",
  "folder": "/catalogues"
}'
Example response
{
  "id": "string",
  "title": "Spring catalogue",
  "folder": "/catalogues",
  "tags": [
    "spring"
  ],
  "state": "draft",
  "encrypted": true,
  "currentVersion": 1,
  "currentOriginal": {
    "filename": "catalogue.pdf",
    "format": "docx",
    "size": 1
  },
  "createdBy": "string",
  "createdAt": 1767225600000,
  "updatedAt": 1767225600000,
  "deletedAt": 1767225600000,
  "appearanceId": "…",
  "viewer": {
    "download": true,
    "embed": true,
    "embedOrigins": [
      "string"
    ]
  },
  "signing": "requested",
  "kind": "document",
  "imageLayout": {
    "fit": "cover",
    "alignX": "left",
    "alignY": "top",
    "pageWidth": 1,
    "pageHeight": 1,
    "marginTop": 1,
    "marginRight": 1,
    "marginBottom": 1,
    "marginLeft": 1,
    "imageWidth": 1,
    "imageHeight": 1,
    "assetId": "ast_7m2kq9vx4c8d1r5t6wnb"
  },
  "letterhead": {
    "mode": "inherit"
  },
  "letterheadPages": [
    {
      "page": 1,
      "choice": {
        "mode": "inherit"
      }
    }
  ]
}

A document's versions, newest first

GET /documents/{documentId}/versions documents.versions

Every version in one answer unless limit is given; with it, pass nextCursor back as cursor for the next page. trash=true lists the versions in the trash instead, which needs the documents.trash scope and edit access to the document (403 forbidden).

Scopes
documents.read
MCP tool
documents_versions

Path parameters

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

Query parameters

NameTypeDescription
trash string true lists the versions in the trash instead of the live ones. Default false. One of true, false.
cursor integer nextCursor from the previous page: the last version number it listed. At least 1.
limit integer Most versions to return. Without it every version is returned and nextCursor is null. 1 to 200.

Response

200 OK. A JSON object:

Response fields (17)
NameTypeDescription
versions array of objects This page of versions, newest first.
versions[].version number The version number, counting up from 1.
versions[].size number The PDF's size in bytes.
versions[].sha256 string The SHA-256 of the PDF's bytes, in lower-case hex.
versions[].pages number Its page count. Null until the job that makes the version's thumbnail has read it, shortly after the version is made. Can be null.
versions[].filename string The file name given when the version was made, used to name its downloads. Empty when none was given.
versions[].encrypted boolean Whether this version is stored encrypted.
versions[].createdBy string The user id of the member who made it, or null when no member did. Can be null.
versions[].createdAt number When it was made, epoch milliseconds.
versions[].deletedAt number When it was moved to the trash, epoch milliseconds. Null unless it is in the trash. Can be null.
versions[].purgeAfter number When a version in the trash is deleted for good, epoch milliseconds. Null unless it is in the trash. Can be null.
versions[].original object The file this version's PDF was converted from, kept as it was uploaded (a Word, OpenDocument, RTF, Markdown, text, HTML or CSV file): download it with documents.downloadOriginal. Null when none was kept: the version was uploaded as a PDF, made from an image, saved from the editor, or its original was not stored. Can be null.
versions[].original.filename string The name the file was uploaded with, which its download is named from. Empty when none was given.
versions[].original.format string What it is: docx (Word), odt (OpenDocument text), rtf, markdown, text (plain text), html or csv. One of docx, odt, rtf, markdown, text, html, csv.
versions[].original.size number Its size in bytes.
nextCursor number Pass it as cursor for the next page. Null when limit was not given or there are no more; a full page can be followed by an empty one. Can be null.
trashedCount integer How many of this document's versions are in the trash and can still be restored.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "versions": [
    {
      "version": 1,
      "size": 1,
      "sha256": "string",
      "pages": 1,
      "filename": "catalogue.pdf",
      "encrypted": true,
      "createdBy": "string",
      "createdAt": 1767225600000,
      "deletedAt": 1767225600000,
      "purgeAfter": 1,
      "original": {
        "filename": "catalogue.pdf",
        "format": "docx",
        "size": 1
      }
    }
  ],
  "nextCursor": 1,
  "trashedCount": 1
}

A version's first-page thumbnail (PNG)

GET /documents/{documentId}/versions/{version}/thumbnail documents.thumbnail

Made by a job after the version is stored, with the letterhead that applies to the document: 404 with code not_ready until it is (details.status says how the job stands).

When there is none under the letterhead as it is now (one changed since: the document's, a member's or the workspace's default, or the letterhead's own new version), asking makes it, and answers not_ready meanwhile; so does asking for one whose file was lost.

The picture at this address changes with the letterhead, so it is sent with five minutes' private caching and an ETag (the job it came from): send If-None-Match to get 304 when it has not changed.

Scopes
documents.read

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.
version required integer The version number. At least 1.

Response

200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/thumbnail \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

Which letterhead applies to each page

GET /documents/{documentId}/letterhead documents.letterhead

Which letterhead each page gets, and from where. A page's own choice comes first, then the document's, then the calling member's default, then the workspace default; a none at any level stops the search. Pages are listed once the current version's thumbnail job has read their sizes (pages with a choice of their own are always listed), so pages can be empty until then.

matches is false when the page and the letterhead differ in size, and then the letterhead is not drawn on that page.

Scopes
documents.read

Path parameters

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

Response

200 OK. A JSON object:

Response fields (18)
NameTypeDescription
fallback object What a page with no choice of its own gets: the document's choice, then the member's default, then the workspace default. Null when none applies. Can be null.
fallback.id string The letterhead's id.
fallback.placement string background draws the letterhead behind the page's content; foreground draws it over the content. One of background, foreground.
fallback.from string Which level chose it: document, user (the member's default) or account (the workspace default). One of document, user, account.
fallback.title string The letterhead's title.
pages array of objects Each known page and what it gets, in page order.
pages[].page integer The page number, 1-based.
pages[].letterheadId string The letterhead this page gets, or null for none. Can be null.
pages[].placement string How it is drawn, or null for none. One of background, foreground. Can be null.
pages[].from string Which level chose it: page, document, user (the member's default) or account (the workspace default). Null for none. One of page, document, user, account. Can be null.
pages[].title string The letterhead's title, or null for none. Can be null.
pages[].matches boolean Whether the page and the letterhead are the same size, within half a point; it is drawn only when they are. Null until both sizes are known. Can be null.
pages[].pageSize object The page's size, from the current version's thumbnail job. Null until known. Can be null.
pages[].pageSize.width number Width in PDF points.
pages[].pageSize.height number Height in PDF points.
pages[].letterheadSize object The size of the letterhead's first page. Null until known, or when no letterhead applies. Can be null.
pages[].letterheadSize.width number Width in PDF points.
pages[].letterheadSize.height number Height in PDF points.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/letterhead \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "fallback": {
    "id": "string",
    "placement": "background",
    "from": "document",
    "title": "Spring catalogue"
  },
  "pages": [
    {
      "page": 1,
      "letterheadId": "…",
      "placement": "background",
      "from": "page",
      "title": "Spring catalogue",
      "matches": true,
      "pageSize": {
        "width": 1,
        "height": 1
      },
      "letterheadSize": {
        "width": 1,
        "height": 1
      }
    }
  ]
}

Download a version's PDF

GET /documents/{documentId}/versions/{version}/source documents.download

The version's PDF as it was stored, decrypted when it is encrypted, named from the version's filename. An unknown version is 404 not_found, and one whose file is no longer stored is 410 gone.

Scopes
documents.read

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.
version required integer The version number. At least 1.

Response

200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/source \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

Keep the file a converted version was made from

PUT /documents/{documentId}/versions/{version}/original documents.storeOriginal

After uploading the PDF a Word (.docx), OpenDocument text (.odt), RTF, Markdown, plain text, HTML or CSV file was converted to, send that file as the body to keep it beside the version, so it can be downloaded as it was (documents.downloadOriginal). A version keeps one original, stored once: a second is 409 original_exists.

Only the member who uploaded the version may store it (an API key acts as its member; anyone else is 403 forbidden), within an hour of the upload (409 original_too_late), and only for a version an upload made, by uploads.start and its parts or by uploads.inline (409 not_an_upload for one saved from the editor, made current again, or matched to content the workspace already stored), and not for a version in the trash (409 in_trash; a document in the trash is 404 not_found).

The bytes are read again here: a file that is not the format given (judged from its first bytes; for the four text formats, bytes that are text) is 415 format_mismatch, and one whose structure does not hold together is 422 damaged_file with what is wrong: a Word file with no document body or a zip directory that does not read, an OpenDocument file whose first entry is not its text mimetype, an RTF file whose braces do not balance, or text that holds a NUL character, is more than 5% control characters (tab, line feed, carriage return, form feed and escape not counted), is UTF-16 that does not decode, or starts with a UTF-8 byte-order mark and then is not UTF-8.

Text with no byte-order mark that is not UTF-8 is read as Windows-1252, kept as it is and served with that charset. The most each format takes: 25 MiB for Word, OpenDocument and RTF, 20 MiB for CSV, 8 MiB for HTML and 2 MiB for Markdown and text (413 too_large). An empty body is 400 empty_body. It is encrypted at rest when the version is.

It counts toward the plan's storage, and one that would take the workspace past it is 402 plan_required. Needs edit access to the document, as uploading a version does; an unknown version is 404 not_found.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.
version required integer The version's number. At least 1.

Query parameters

NameTypeDescription
format required string What the file is: docx, odt, rtf, markdown, text, html or csv. The bytes must be that format. One of docx, odt, rtf, markdown, text, html, csv.
filename string The file's name, which its download is named from. Control and direction characters are removed. Left out, it has none. At most 200 characters.

Request body

The raw bytes, at most 25 MiB, sent as application/octet-stream.

Response

201 Created. A JSON object:

Response fields (4)
NameTypeDescription
original object The original now kept beside the version.
original.filename string The name the file was uploaded with, which its download is named from. Empty when none was given.
original.format string What it is: docx (Word), odt (OpenDocument text), rtf, markdown, text (plain text), html or csv. One of docx, odt, rtf, markdown, text, html, csv.
original.size number Its size in bytes.

Example request

curl -X PUT "https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/original?format=docx" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @part-1.bin
Example response
{
  "original": {
    "filename": "catalogue.pdf",
    "format": "docx",
    "size": 1
  }
}

Download the file a converted version was made from

GET /documents/{documentId}/versions/{version}/original documents.downloadOriginal

The original as it was uploaded, decrypted when it is encrypted, as an attachment named from its filename with its format's extension, and served with its media type and a sandboxing Content-Security-Policy, so an HTML original never runs on this site. A version with no original, or an unknown version, is 404 not_found, and one whose file is no longer stored is 410 gone.

A document in a folder the caller cannot see is 404 not_found.

Scopes
documents.read

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.
version required integer The version's number. At least 1.

Response

200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/original \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

Make an earlier version current again

POST /documents/{documentId}/versions/{version}/revert documents.version.revert

Adds a new version whose content is that version's stored file, and makes it current. Every version in between is kept. The version must be live (409 in_trash when it is in the trash) and not the current one (409 already_current). A version stored in the clear is refused with 409 not_sealed while the document asks for encryption: download it and upload it again to have it sealed.

A version whose file is no longer stored is 409 gone. A live publication moves to the new version. Needs edit access to the document (403 forbidden).

Scopes
documents.edit
Retries
Safe with an Idempotency-Key

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.
version required integer The version number. At least 1.

Response

201 Created. A JSON object:

Response fields (15)
NameTypeDescription
version object The new version, now the current one.
version.version number The version number, counting up from 1.
version.size number The PDF's size in bytes.
version.sha256 string The SHA-256 of the PDF's bytes, in lower-case hex.
version.pages number Its page count. Null until the job that makes the version's thumbnail has read it, shortly after the version is made. Can be null.
version.filename string The file name given when the version was made, used to name its downloads. Empty when none was given.
version.encrypted boolean Whether this version is stored encrypted.
version.createdBy string The user id of the member who made it, or null when no member did. Can be null.
version.createdAt number When it was made, epoch milliseconds.
version.deletedAt number When it was moved to the trash, epoch milliseconds. Null unless it is in the trash. Can be null.
version.purgeAfter number When a version in the trash is deleted for good, epoch milliseconds. Null unless it is in the trash. Can be null.
version.original object The file this version's PDF was converted from, kept as it was uploaded (a Word, OpenDocument, RTF, Markdown, text, HTML or CSV file): download it with documents.downloadOriginal. Null when none was kept: the version was uploaded as a PDF, made from an image, saved from the editor, or its original was not stored. Can be null.
version.original.filename string The name the file was uploaded with, which its download is named from. Empty when none was given.
version.original.format string What it is: docx (Word), odt (OpenDocument text), rtf, markdown, text (plain text), html or csv. One of docx, odt, rtf, markdown, text, html, csv.
version.original.size number Its size in bytes.

Example request

curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/revert \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response
{
  "version": {
    "version": 1,
    "size": 1,
    "sha256": "string",
    "pages": 1,
    "filename": "catalogue.pdf",
    "encrypted": true,
    "createdBy": "string",
    "createdAt": 1767225600000,
    "deletedAt": 1767225600000,
    "purgeAfter": 1,
    "original": {
      "filename": "catalogue.pdf",
      "format": "docx",
      "size": 1
    }
  }
}

Errors

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

StatusCodeWhen
400invalidA folder path, title or tags fail the workspace's checks.
400not_a_pictureimageLayout.assetId names a video from the media library, not a picture.
404not_readyThe thumbnail is not made yet, or not yet made again after a letterhead change.
409in_trashReverting to a version that is in the trash, or storing an original for one.
409already_currentReverting to the version that is already current.
409not_sealedReverting to an unencrypted version while the document asks for encryption.
409goneReverting to a version whose file is no longer stored.
400empty_bodyStoring a version's original with no body.
409original_existsStoring an original for a version that already keeps one. A version keeps one, stored once.
409original_too_lateStoring an original more than an hour after its version was uploaded.
409not_an_uploadStoring an original for a version no upload made: saved from the editor, made current again, or matched to content already stored.
415format_mismatchAn original's bytes are not the format given.
422damaged_fileAn original's structure does not hold together: a Word or OpenDocument zip that does not read or lacks its text, RTF whose braces do not balance, or text that holds NUL, is more than 5% control characters, is UTF-16 that does not decode, or is marked UTF-8 and is not (other text that is not UTF-8 is read as Windows-1252). The message says which.
410goneDownloading a file that is no longer stored.