API
Uploads
Upload a PDF as a new version of a document, in one call or in resumable parts.
A PDF of 700 KiB or less goes in one call: uploads.inline, with the file as base64; it can also make the document. Anything larger, up to 1 GiB, is a multipart upload: uploads.start with the file's size and sha256, then each part to uploads.putPart, then uploads.complete. Completion checks the bytes against the declared size and hash, and that the PDF ends as one does (%%EOF in its last 1024 bytes, after a startxref whose offset lies inside the file), and makes the version.
Each part is partSize bytes (8 MiB), and the last holds the rest. Parts are numbered from 1, may be sent in any order and can be resent safely. uploads.get lists the parts received, so an interrupted upload can resume. An upload expires 24 hours after it starts; uploads.abort ends one early and releases the storage it held. Content the workspace already stores is not sent again: the start answers kind: stored with the version at once.
A new version is processed in the background. A job reads its page count (until then pages is null) and draws its thumbnail. A live publication moves to the new version once its pages are made. The document.processed webhook event reports each job as it finishes. Uploads count against the plan's storage, and starting them is rate limited per member, API key or OAuth grant.
Start uploading a new version of a document
POST /uploads uploads.start
The first step of a multipart upload, for a PDF of up to 1 GiB. Declare the file's size and sha256, and optionally its first bytes as header. If the document's current version already has these bytes, that version is returned and no version is made; if this workspace already stores them, the new version is made from them at once. Either way the answer is kind: stored and nothing is sent.
Otherwise the answer is kind: upload, with the uploadId, the partSize and the number of parts: send each part to uploads.putPart, then finish with uploads.complete. A file of 700 KiB or less can go in one call to uploads.inline instead. The declared size counts against the plan's storage from here until the upload ends, and a file that would not fit is 402 plan_required.
Starting an upload is limited to 20 a minute for each member, API key or OAuth grant (429 rate_limited). A header that does not start as a PDF does is 415 unsupported_type, and one that cannot be read is 400 invalid_request. A document the caller cannot edit is 403 forbidden.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
documentId required | string | The document the new version is for. An id starting doc_. |
filename | string | The file's name, kept with the version and used to name its downloads. At most 200 characters. |
size required | integer | The file's exact size in bytes, at most 1 GiB. 1 to 1,073,741,824. |
sha256 required | string | The SHA-256 of the whole file, in lower-case hex. Completion checks the stored bytes against it. Matches ^[0-9a-f]{64}$. |
header | string | The file's first 5 to 64 bytes, standard base64, so a file that is not a PDF is refused before a multipart upload is opened. Without it, the first part is checked instead. At most 88 characters. |
Response
201 Created. A JSON object:
Response fields (24)
| Name | Type | Description |
|---|---|---|
kind | string | Send the parts: the upload is open. One of upload, stored. |
upload | object | The new upload. Only when kind is upload. |
upload.uploadId | string | The upload's id, for the calls that follow. |
upload.status | string | open: taking parts. completing: uploads.complete is checking the bytes and making the version. complete: the version was made. aborted: abandoned, by uploads.abort, by a first part that is not a PDF, or on expiry. failed: completion found the bytes did not match, or could not finish. Only an open upload takes parts. One of open, completing, complete, aborted, failed. |
upload.partSize | number | The size in bytes of every part but the last, which holds the rest of the file: 8388608 (8 MiB). Cut the file by this value. |
upload.parts | number | How many parts to send: the file's size divided by partSize, rounded up. Parts are numbered from 1. |
upload.received | array of numbers | The part numbers stored so far, in ascending order. Resume an interrupted upload by sending the others. |
upload.expiresAt | number | When the upload expires, epoch milliseconds: 24 hours after it started. After that its parts and completion are refused with 410 upload_expired. |
version | object | The version: the document's current version when it already had these bytes, or a new version made from content the workspace already stores. Only when kind is stored. |
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. |
deduplicated | boolean | Always true here: the bytes were not uploaded again. Only when kind is stored. |
Example request
curl -X POST https://api.flipbird.io/api/v1/uploads \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"documentId": "doc_7m2kq9vx4c8d1r5t6wnb",
"size": 1,
"sha256": "3a18f6d4b2907e5c3a18f6d4b2907e5c3a18f6d4b2907e5c3a18f6d4b2907e5c"
}' Example response
{
"kind": "upload",
"upload": {
"uploadId": "…",
"status": "open",
"partSize": 1,
"parts": 1,
"received": [
1
],
"expiresAt": 1767225600000
}
} Which parts an upload has received
GET /uploads/{uploadId} uploads.get
The upload's status, part size and part count, and which part numbers have arrived, so an interrupted upload can resume by sending only the missing parts. Needs edit access to the document the upload is for. An unknown upload is 404 not_found.
- Scopes
documents.edit
Path parameters
| Name | Type | Description |
|---|---|---|
uploadId required | string | The upload's id, from uploads.start. An id starting upl_. |
Response
200 OK. A JSON object:
Response fields (6)
| Name | Type | Description |
|---|---|---|
uploadId | string | The upload's id, for the calls that follow. |
status | string | open: taking parts. completing: uploads.complete is checking the bytes and making the version. complete: the version was made. aborted: abandoned, by uploads.abort, by a first part that is not a PDF, or on expiry. failed: completion found the bytes did not match, or could not finish. Only an open upload takes parts. One of open, completing, complete, aborted, failed. |
partSize | number | The size in bytes of every part but the last, which holds the rest of the file: 8388608 (8 MiB). Cut the file by this value. |
parts | number | How many parts to send: the file's size divided by partSize, rounded up. Parts are numbered from 1. |
received | array of numbers | The part numbers stored so far, in ascending order. Resume an interrupted upload by sending the others. |
expiresAt | number | When the upload expires, epoch milliseconds: 24 hours after it started. After that its parts and completion are refused with 410 upload_expired. |
Example request
curl https://api.flipbird.io/api/v1/uploads/upl_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"uploadId": "…",
"status": "open",
"partSize": 1,
"parts": 1,
"received": [
1
],
"expiresAt": 1767225600000
} Send one part
PUT /uploads/{uploadId}/parts/{partNumber} uploads.putPart
The body is the part's raw bytes (application/octet-stream). Part n is bytes (n-1)*partSize to n*partSize of the file: every part is exactly partSize bytes except the last, which holds what is left. Any other length is 400 wrong_part_length, and a part number past parts is 400 no_such_part. Parts may be sent in any order.
Part 1 must start as a PDF does; if it does not, the upload is aborted and the call is 415 unsupported_type. Sending a part again with the same bytes is safe; with different bytes it is refused (409 part_changed), and a changed file needs a new upload. An upload that is not open is 409 upload_closed, and an expired one is 410 upload_expired. Answers with the part number stored.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
uploadId required | string | The upload's id, from uploads.start. An id starting upl_. |
partNumber required | integer | Which part this is, 1-based, up to the upload's parts. 1 to 10,000. |
Request body
The raw bytes, at most 8 MiB, sent as application/octet-stream.
Response
200 OK. A JSON object:
Response fields (1)
| Name | Type | Description |
|---|---|---|
partNumber | number | The part number stored. |
Example request
curl -X PUT https://api.flipbird.io/api/v1/uploads/upl_7m2kq9vx4c8d1r5t6wnb/parts/1 \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/octet-stream" \
--data-binary @part-1.bin Example response
{
"partNumber": 1
} Finish an upload and make the version
POST /uploads/{uploadId}/complete uploads.complete
Call it once every part has been sent. The stored bytes are checked against the declared size and sha256; a mismatch discards the upload (422 content_mismatch) and the file must be uploaded again from uploads.start. The PDF's end is checked too: it must have %%EOF within its last 1024 bytes and a startxref before that whose offset lies inside the file.
One that does not, such as a file cut short, discards the upload (422 damaged_file, with what is wrong). On success the new version is the document's current one, and is returned. Parts not yet stored are 409 parts_missing, with their numbers in details.missing. Rarely, 409 parts_resend asks for every part to be sent again before completing once more (details.parts says how many).
An upload already completing, or not open, is 409 upload_closed; an expired one is 410 upload_expired. After the version is made, a job reads its page count and draws its thumbnail: until that job is done the version's pages is null and documents.thumbnail answers 404 not_ready, and when it is done the document.processed webhook event is sent.
A live publication moves to the new version once its pages are made.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
uploadId required | string | The upload's id, from uploads.start. An id starting upl_. |
Response
201 Created. A JSON object:
Response fields (15)
| Name | Type | Description |
|---|---|---|
version | object | The new version. |
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/uploads/upl_7m2kq9vx4c8d1r5t6wnb/complete \
-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
}
}
} Abandon an upload
DELETE /uploads/{uploadId} uploads.abort
Ends an open upload: the parts stored so far are deleted and the storage it held is released. An expired upload can still be aborted. One that has completed, or is completing, is 409 upload_closed.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
uploadId required | string | The upload's id, from uploads.start. An id starting upl_. |
Response
200 OK. An empty JSON object, {}.
Example request
curl -X DELETE https://api.flipbird.io/api/v1/uploads/upl_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" Upload a small PDF in one call
POST /uploads/inline uploads.inline
data is the whole PDF as standard base64, at most 716800 bytes (700 KiB) before encoding. Give documentId to add the file as that document's next version, or title (with folder and tags if wanted) to make a new document from it; not both (400 invalid_request).
Content this workspace already stores is reused rather than stored again (deduplicated: true); when the document's current version already has these bytes, it is returned and no version is made. A file that is not a PDF is 415 unsupported_type, and a PDF without %%EOF in its last 1024 bytes, or whose startxref offset lies outside it, is 422 damaged_file; either way nothing is stored.
If a new document was made and the upload then fails, the document stays, empty, and the error's details.documentId names it so a retry can pass it as documentId. The new version is then processed as after uploads.complete. Each call counts against the same 20 a minute as uploads.start (429 rate_limited).
A larger file, up to 1 GiB, goes through the REST multipart upload instead: POST /api/uploads, PUT /api/uploads/{uploadId}/parts/{n}, then POST /api/uploads/{uploadId}/complete.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
uploads_inline
Request body
A JSON object, at most 1 MiB.
| Name | Type | Description |
|---|---|---|
documentId | string | Add the file as the next version of this document. Give this or title, not both. An id starting doc_. |
title | string | Make a new document with this title from the file. Give this or documentId, not both. 1 to 200 characters. |
folder | string | The new document's folder, such as /marketing/2026/. Default /. Only with title: with documentId it is 400 invalid_request. At most 1,100 characters. |
tags | array of strings | The new document's tags, stored lower-cased. Only with title: with documentId it is 400 invalid_request. At most 30 items. |
filename | string | The file's name, kept with the version and used to name its downloads. At most 200 characters. |
data required | string | The whole PDF as standard base64 (whitespace is ignored), at most 716800 bytes before encoding. 8 to 955,736 characters. |
Response
201 Created. A JSON object:
Response fields (59)
| Name | Type | Description |
|---|---|---|
document | object | The document, new or existing, as it is now. |
document.id | string | The document's id. |
document.title | string | The document's title. |
document.folder | string | The folder it is filed in: a path that starts and ends with /, such as /marketing/2026/. / is the top level. |
document.tags | array of strings | Its tags, lower-cased, in alphabetical order. |
document.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. |
document.encrypted | boolean | Whether versions uploaded from now on are stored encrypted. On for every new document; only the workspace Owner can turn it off. |
document.currentVersion | number | The number of its current version: the newest one not in the trash. Null when it has none. Can be null. |
document.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. |
document.currentOriginal.filename | string | The name the file was uploaded with, which its download is named from. Empty when none was given. |
document.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. |
document.currentOriginal.size | number | Its size in bytes. |
document.createdBy | string | The user id of the member who made it, or null when no member did. Can be null. |
document.createdAt | number | When it was made, epoch milliseconds. |
document.updatedAt | number | When it last changed, epoch milliseconds. |
document.deletedAt | number | When it was moved to the trash, epoch milliseconds. Null unless it is in the trash. Can be null. |
document.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. |
document.viewer | object | How the hosted viewer shows it once published. |
document.viewer.download | boolean | Readers of the publication may download the PDF. Off unless turned on. |
document.viewer.embed | boolean | Other sites may frame the publication's embed. On unless turned off. |
document.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. |
document.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. |
document.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. |
document.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. |
document.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. |
document.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. |
document.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. |
document.imageLayout.pageWidth | number | The page's width in PDF points (1/72 inch). More than 0. At most 14,400. |
document.imageLayout.pageHeight | number | The page's height in PDF points. More than 0. At most 14,400. |
document.imageLayout.marginTop | number | Space kept clear at the top of the page, in PDF points. 0 to 5,000. |
document.imageLayout.marginRight | number | Space kept clear at the right of the page, in PDF points. 0 to 5,000. |
document.imageLayout.marginBottom | number | Space kept clear at the bottom of the page, in PDF points. 0 to 5,000. |
document.imageLayout.marginLeft | number | Space kept clear at the left of the page, in PDF points. 0 to 5,000. |
document.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. |
document.imageLayout.imageHeight | number | The picture's height in pixels. More than 0. At most 100,000. |
document.imageLayout.assetId | string | The original picture, kept in the image library, or null when none was kept. An id starting ast_. Can be null. |
document.letterhead | object | The document-level letterhead choice. inherit means the document has not chosen. One of 3 shapes, chosen by mode. |
document.letterhead.mode | string | No choice at this level: the next broader level decides. One of inherit, none, use. |
document.letterhead.id | string | The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_. |
document.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. |
document.letterheadPages | array of objects | Pages with a letterhead choice of their own, by page number. Every other page follows the document-level choice. |
document.letterheadPages[].page | integer | The page number, 1-based. |
document.letterheadPages[].choice | object | That page's own choice. One of 3 shapes, chosen by mode. |
document.letterheadPages[].choice.mode | string | No choice at this level: the next broader level decides. One of inherit, none, use. |
document.letterheadPages[].choice.id | string | The letterhead's id: a document of kind letterhead. Only when mode is use. An id starting doc_. |
document.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. |
version | object | The new version, or the current version when it already had these bytes. |
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. The same fields as document.currentOriginal. |
deduplicated | boolean | True when the bytes were not stored again: the workspace already had them. |
Example request
curl -X POST https://api.flipbird.io/api/v1/uploads/inline \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"data": "JVBERi0xLjcK…"
}' Example response
{
"document": {
"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"
}
}
]
},
"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
}
},
"deduplicated": true
} Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | wrong_part_length | A part is not exactly its length: partSize, or the rest for the last. |
| 400 | no_such_part | The part number is past the upload's parts. |
| 409 | part_changed | A part was sent again with different bytes. |
| 409 | upload_closed | The upload is not open: it is completing, completed or abandoned. |
| 409 | parts_missing | Completing before every part is stored. details.missing lists them. |
| 409 | parts_resend | Storage refused the part list: send every part again, then complete. |
| 410 | upload_expired | The upload is more than 24 hours old. |
| 415 | unsupported_type | The file is not a PDF. |
| 422 | content_mismatch | The bytes stored do not match the size and sha256 given. |
| 422 | damaged_file | The PDF's end does not hold together: no %%EOF in its last 1024 bytes, or no startxref before it whose offset lies inside the file. A file cut short ends this way. |