API
Editing sessions
Edit a document's draft on the server, then save it as a new version or throw it away.
Each document has one editing session holding a draft: a working copy that starts from the current version. sessions.applyOps runs edit ops (pages, text, pictures, annotations, headers and footers, properties, bookmarks) and read ops on it, and each edit adds one to seq. The draft is not a version: sessions.saveVersion stores it as the next one, sessions.workingCopy downloads it as it is, and sessions.close with discard: true throws it away.
Only the holder of the write lease may edit. An API caller takes the lease with its first applyOps and keeps it for a minute after each call. A browser editing the document holds it while connected, and API edits are then 409 locked. Pass baseSeq to be sure nobody has changed the draft since you last looked (409 stale). Call sessions.close when done, so others can edit.
A session holds documents of up to 2 MiB and 200 pages. Page indexes in op arguments are 0-based. Positions are in PDF points from the page's top-left corner.
The editing session: who holds the lease, who is here, and the draft
GET /documents/{documentId}/session sessions.get
The document's draft (its working copy), the version it started from, who holds the write lease and who is connected. Reading it changes nothing and takes no lease.
- Scopes
documents.read- MCP tool
documents_session_get
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (24)
| Name | Type | Description |
|---|---|---|
seq | number | Edits applied since the session began. Each edit op adds one, and it never goes back. |
baseVersion | number | The version the draft started from. Null when the document has no version. Can be null. |
baseSeq | number | The seq at which the draft was baseVersion: seq minus baseSeq is the number of unsaved edits. |
currentVersion | number | The document's current version. Ahead of baseVersion when a version was added while the draft was open. Can be null. |
draft | object | The draft's last autosave, or null when it has none. Edits are autosaved within 30 seconds. Can be null. |
draft.seq | number | The seq the autosave holds. |
lease | object | Who holds the write lease (only the holder may edit), or null when nobody does. Can be null. One of 2 shapes, chosen by kind. |
lease.kind | string | Held by a browser connected over the WebSocket, for as long as it keeps answering. One of socket, api. |
lease.clientId | string | The connection that holds it. Only when kind is socket. |
lease.userId | string | The member who holds it. Only when kind is socket. |
lease.name | string | Their name as others see it. Only when kind is socket. |
lease.since | number | When they took it, epoch milliseconds. Only when kind is socket. |
lease.userId | string | The member the caller acts for. Only when kind is api. |
lease.name | string | Their name as others see it, with the API key's or OAuth app's name. Only when kind is api. |
lease.since | number | When the lease was taken, epoch milliseconds. Only when kind is api. |
lease.expiresAt | number | When it lapses unless another call extends it, epoch milliseconds: a minute after the last call. Only when kind is api. |
peers | array of objects | Who is connected over the WebSocket. API callers are not listed. |
peers[].clientId | string | This connection's id within the session. |
peers[].userId | string | The member's user id. |
peers[].name | string | The member's name, or their email. |
peers[].canEdit | boolean | Whether this connection may edit the draft. |
peers[].joinedAt | number | When it connected, epoch milliseconds. |
editable | boolean | False when the document cannot be edited in a session: it has no version, or it is larger than 2 MiB or has more than 200 pages. |
reason optional | string | Why not, when editable is false. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/session \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"seq": 1,
"baseVersion": 1,
"baseSeq": 1,
"currentVersion": 1,
"draft": {
"seq": 1
},
"lease": {
"kind": "socket",
"clientId": "…",
"userId": "…",
"name": "Spring catalogue",
"since": 1
},
"peers": [
{
"clientId": "…",
"userId": "…",
"name": "Spring catalogue",
"canEdit": true,
"joinedAt": 1767225600000
}
],
"editable": true,
"reason": "string"
} Apply edits to the document's draft
POST /documents/{documentId}/session/ops sessions.applyOps
Runs up to 20 ops on the document's draft as one batch, in order: the batch is kept only if every op succeeds. Takes the write lease for a minute if it is free (each call extends it), and refuses while a browser or another member holds it (409 locked, details.holder says who). Edits change the draft, not a version: save it with sessions.saveVersion, or throw it away with sessions.close.
Read ops answer without changing seq.
Refusals: 403 forbidden when the caller may read the document but not edit it; 409 stale when baseSeq is not the draft's seq; 400 invalid_op when an op's arguments do not fit its schema (details.issues says where); 422 unsupported for an op that needs something this engine cannot do, such as a redaction; 422 engine_error when an op fails; 422 too_heavy when the document is, or would become, more than a session holds (2 MiB or 200 pages); 409 no_version when the document has no version yet.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
documents_session_apply
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
ops required | array of objects | The ops to run, in order: 1 to 20. 1 to 20 items. |
ops[].op required | string | The op. Edits change the draft and add one to seq: pageOp (rotate, delete, move, insert, crop or resize pages), deletePages, replaceText (find and replace), imageOp (delete, move or replace a picture on a page), save (write annotations and form values into the file), decorate (headers, footers, page numbers and a text watermark, drawn in Helvetica), setDocumentInfo (title, author and the other document properties) and setOutline (replace the bookmarks). Reads change nothing: documentInfo, documentFonts, search, scanText and outline. One of pageOp, deletePages, replaceText, imageOp, save, decorate, setDocumentInfo, setOutline, documentInfo, documentFonts, search, scanText, outline. |
ops[].args required | map of anys | The op's arguments, checked against that op's schema. Page indexes are 0-based. Positions and sizes are PDF points from the page's top-left corner, y down, after the page's rotation. pageOp: op, whose kind is rotate (pageIndex, clockwise), delete (pageIndex), move (from, to), insertBlank (at, width, height), crop (target, rect, or null to uncrop) or geometry (target, width, height, margins, fit scale or center), where target is a page index or all. deletePages: indices. replaceText: needle, replacement, and optionally only (pageIndex and the hit's quad, 8 numbers) to change one occurrence. imageOp: pageIndex, the picture's bbox, and action, whose kind is delete, move (to) or replace (dataUrl). save: annotations, formValues (field name to value), flatten (none, forms or all), and optionally stripMetadata and fullRewrite; security is refused here (use sessions.protectedCopy). decorate: headerFooter (slots hl, hc, hr, fl, fc, fr, size, color as #rrggbb, marginX, marginY, target), watermark (text, size, color, opacity, angleDeg, behind, optionally position and margin, target), or both; target is all, notFirst, a page index or {pages: [indexes]}, and {date} in a slot is written as the day the op runs (YYYY-MM-DD, UTC). setDocumentInfo: fields, any of title, author, subject, keywords, creator and producer. setOutline: items, the whole outline depth first, each with title, page, level (0 at the top) and open. search: pageIndex, needle, maxHits. scanText: patterns (each an id and a regular expression's source and flags), maxHits, and optionally pageIndex. documentInfo, documentFonts and outline take {}. |
baseSeq | integer | When given, the draft must be at this seq, or the call is refused with 409 stale (details.seq says where it is). At least 0. |
Response
200 OK. A JSON object:
Response fields (2)
| Name | Type | Description |
|---|---|---|
seq | number | The draft's seq after the batch. |
results | array of anys | One result per op, in order: what the op returned, without any file bytes. Fetch the working copy for those. |
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/session/ops \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"ops": [
{
"op": "pageOp",
"args": {}
}
]
}' Example response
{
"seq": 1,
"results": [
{}
]
} Save the draft as a new version
POST /documents/{documentId}/session/versions sessions.saveVersion
Stores the draft as the document's next version, the way an upload does: content the workspace already stores is reused, the version gets its thumbnail job and audit entry, and a live publication moves to it. The draft then starts again from the new version; edits applied while the save ran stay in it.
Refused with 409 locked while another member holds the lease, 409 no_changes when nothing changed since the version the draft started from, and 409 save_in_progress while another save runs. A draft that does not fit the plan's storage is 402 plan_required and stays in the session.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
documents_session_save
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
filename | string | The new version's file name. Default the file name of the version the draft started from. At most 200 characters. |
Response
201 Created. A JSON object:
Response fields (16)
| Name | Type | Description |
|---|---|---|
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. |
seq | number | The draft's seq that was saved. |
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/session/versions \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"filename": "catalogue.pdf"
}' 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
}
},
"seq": 1
} Give up an API caller's lease, and optionally discard the draft
POST /documents/{documentId}/session/close sessions.close
Gives up the write lease an API caller holds for this member, so others can take it. It needs edit access to the document (403 forbidden without it). With discard: true the draft is thrown away as well and the working copy goes back to the current version; that is 409 locked while another member holds the lease. Without it the draft is kept, and autosaved at once when nobody is connected.
- Scopes
documents.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
documents_session_close
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
discard | boolean | True also throws the draft away. Default false. |
Response
200 OK. A JSON object:
Response fields (1)
| Name | Type | Description |
|---|---|---|
discarded | boolean | Whether the draft was thrown away. |
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/session/close \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"discard": true
}' Example response
{
"discarded": true
} Download the draft as it is now
GET /documents/{documentId}/session/working-copy sessions.workingCopy
The draft's PDF as it is now, with every applied edit. The x-flipbird-seq header says which seq the bytes are at. A document with no version is 409 no_version, and one larger than a session holds (2 MiB or 200 pages) is 422 too_heavy.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
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/session/working-copy \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Download the draft as a password-protected PDF
POST /documents/{documentId}/session/protected-copy sessions.protectedCopy
The draft as it is now, encrypted with AES-256 (PDF 2.0, revision 6): userPassword opens it, ownerPassword lifts its permissions, and permissions say what a reader with only the user password may do (everything, when absent). An empty owner password is the user password. An empty user password opens without a prompt and still carries the permissions; at least one password is required.
Passwords are used for this copy alone and are not stored. The draft itself is unchanged. A POST so the passwords travel in the body; it changes nothing, so an Idempotency-Key is ignored. The x-flipbird-seq header says which seq the bytes are at.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
userPassword | string | The password that opens the copy. Empty or absent opens it without a prompt. At most 127 characters. |
ownerPassword | string | The password that lifts the copy's permissions. Empty or absent means the user password. At most 127 characters. |
permissions | object | What a reader with only the user password may do. Absent allows everything. |
permissions.print required | boolean | May print. |
permissions.printHq required | boolean | May print at full quality. |
permissions.copy required | boolean | May copy text and pictures. |
permissions.edit required | boolean | May change the content. |
permissions.annotate required | boolean | May add and change comments, and fill in forms. |
permissions.form required | boolean | May fill in form fields. |
permissions.accessibility required | boolean | May extract text for accessibility tools. |
permissions.assemble required | boolean | May insert, rotate and delete pages. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/session/protected-copy \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userPassword": "string",
"ownerPassword": "string"
}' \
-OJ Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | invalid_op | An op's arguments fail its schema. |
| 401 | signed_out | The credential was revoked or expired during the session. |
| 409 | locked | Someone else holds the write lease. |
| 409 | stale | baseSeq is not the draft's seq: it changed since you read it. |
| 409 | no_version | The document has no version to edit. |
| 409 | no_changes | Saving a draft with no edits. |
| 409 | save_in_progress | Another save is running. |
| 422 | too_heavy | The document is, or would become, larger than 2 MiB or 200 pages. |
| 422 | unsupported | The op needs something the engine cannot do, such as redaction. |
| 422 | engine_error | The op failed on this document. |
| 503 | replay_failed | The draft could not be rebuilt. Try again. |