API

Trash

Move documents and versions to the trash, and take them out again.

Moving a document to the trash takes its publication down and returns it to draft. It can be restored until purgeAfter, the end of the plan's trash retention, and is then deleted for good. One version can be trashed and restored the same way while the document stays; the newest version still live is always the current one.

Trashing and restoring need documents.trash and edit access to the document. Deleting for good without waiting is the workspace Owner's, and is not part of the public API.

Move a document to the trash

DELETE /documents/{documentId} documents.trash

It stays restorable for the plan's retention days, then is purged. Its publication is taken down, any scheduled publish or expiry is cleared, and it goes back to draft. Answers with purgeAfter. Needs edit access to the document (403 forbidden); deleting it for good is the Owner's (POST /api/documents/{documentId}/purge). A document already in the trash is 404 not_found.

Scopes
documents.trash
Retries
Safe with an Idempotency-Key
MCP tool
documents_trash

Path parameters

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

Response

200 OK. A JSON object:

Response fields (1)
NameTypeDescription
purgeAfter number When it will be deleted for good, epoch milliseconds.

Example request

curl -X DELETE https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response
{
  "purgeAfter": 1
}

Documents in the trash

GET /trash documents.listTrash

The documents in the trash that the caller can see, letterheads included, most recently changed first (usually the most recently trashed), at most 200, with when each will be deleted for good. There is no paging.

Scopes
documents.trash

Response

200 OK. A JSON object:

Response fields (47)
NameTypeDescription
documents array of objects The trashed 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.
documents[].purgeAfter number When it will be deleted for good, epoch milliseconds. Can be null.

Example request

curl https://api.flipbird.io/api/v1/trash \
  -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"
          }
        }
      ],
      "purgeAfter": 1
    }
  ]
}

Take a document out of the trash

POST /documents/{documentId}/restore documents.restore

Restores it as a draft: the publication taken down when it was trashed stays down. Answers with the document. It goes back to the folder it was in, which is made again if it was deleted meanwhile (folders.delete). Needs edit access to the document (403 forbidden). A document not in the trash, or already purged, is 404 not_found.

Scopes
documents.trash
Retries
Safe with an Idempotency-Key

Path parameters

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

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 POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/restore \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
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"
      }
    }
  ]
}

Move one version to the trash

DELETE /documents/{documentId}/versions/{version} documents.version.trash

The document stays. This version can be restored until the plan's retention runs out, then it is purged. The newest version still live becomes or stays the current one, and a live publication stops serving this one; with no live version left, the publication is taken down. Answers with purgeAfter. Needs edit access to the document (403 forbidden). A version that is not live is 404 not_found.

Scopes
documents.trash
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

200 OK. A JSON object:

Response fields (1)
NameTypeDescription
purgeAfter number When it will be deleted for good, epoch milliseconds.

Example request

curl -X DELETE https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1 \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response
{
  "purgeAfter": 1
}

Take one version out of the trash

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

Puts the version back among the live ones. The newest live version is the current one, so a restored version newer than the current one becomes current again, and a live publication follows it. Needs edit access to the document (403 forbidden). A version that is not in the trash is 404 not_found.

Scopes
documents.trash
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

200 OK. A JSON object:

Response fields (1)
NameTypeDescription
version integer The number of the version restored.

Example request

curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/restore \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response
{
  "version": 1
}