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

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

Response

200 OK. A JSON object:

Response fields (24)
NameTypeDescription
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

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

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
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)
NameTypeDescription
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

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

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
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)
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.
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

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

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
discard boolean True also throws the draft away. Default false.

Response

200 OK. A JSON object:

Response fields (1)
NameTypeDescription
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

NameTypeDescription
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

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

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
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:

StatusCodeWhen
400invalid_opAn op's arguments fail its schema.
401signed_outThe credential was revoked or expired during the session.
409lockedSomeone else holds the write lease.
409stalebaseSeq is not the draft's seq: it changed since you read it.
409no_versionThe document has no version to edit.
409no_changesSaving a draft with no edits.
409save_in_progressAnother save is running.
422too_heavyThe document is, or would become, larger than 2 MiB or 200 pages.
422unsupportedThe op needs something the engine cannot do, such as redaction.
422engine_errorThe op failed on this document.
503replay_failedThe draft could not be rebuilt. Try again.