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
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (1)
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (45)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
}