API
Flipbird API
A REST API for documents, flipbooks, links and QR codes, and the people and settings around them, in your own systems.
Everything a member can do in the workspace, from uploading a PDF to publishing it and reading its analytics, your software can do through the API. Requests and responses are JSON over HTTPS, and every endpoint, parameter and field is listed in the reference below.
Base URL
Every endpoint is under one base URL. The version is part of the path.
Base URL
https://api.flipbird.io/api/v1 Quick start
Make an API key in your workspace under Settings, API keys. Give it the scopes your software needs; for this walk-through, documents.read, documents.edit and documents.publish. The key is shown once: keep it somewhere secret, such as your server's environment.
List your documents:
List documents
curl https://api.flipbird.io/api/v1/documents \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Upload a PDF of up to 700 KiB in one call, as base64. A larger file, up to 1 GiB, goes up in parts of 8 MiB through the Uploads endpoints.
Upload a PDF
printf '{"title": "Spring catalogue", "data": "%s"}' "$(base64 < catalogue.pdf | tr -d '\n')" > upload.json
curl -X POST https://api.flipbird.io/api/v1/uploads/inline \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
--data-binary @upload.json The response holds the new document. Publish it as a flipbook with its id:
Publish it
curl -X PUT https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/publication \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"mode": "public"}' The response's publication.publicId is the flipbook's address, which never changes: readers open it at https://view.flipbird.io/v/{publicId}. To hear when processing or an export finishes, subscribe a webhook endpoint instead of polling.
Authentication
Send an API key, or an OAuth access token, as a bearer token on every request. A key is for your own software acting for the workspace; OAuth is for an app that people connect to their own workspace. Either one acts for the member who made or approved it, with that member's current role narrowed to the credential's scopes. An API key also needs a plan that includes API access.
Header
Authorization: Bearer xbk_… Requests and responses
- Send a body as JSON with
Content-Type: application/json. A JSON body may be at most 64 KiB unless the endpoint says otherwise. Upload parts are raw bytes withContent-Type: application/octet-stream. - Responses are JSON, except downloads, which are the file itself. A field the reference does not list is never sent.
- Ids start with their kind:
doc_for a document,lnk_for a link, and so on, then 20 characters. Pass them back exactly as given. - Times are epoch milliseconds (UTC), and sizes are bytes.
- Every mutation (anything but
GET) takes anIdempotency-Keyheader, which makes a retry safe. assets.upload ignores it: an upload sent again is the same asset. - An error is
{ "error": { "code", "message", "details"? } }, with a stablecodeto switch on and anX-Request-Idheader to quote to support.
Pagination
A list that can be long comes a page at a time. Most take limit, and answer with a cursor to pass back for the next page: send the response's nextCursor as cursor, until it is null. A few name their cursor differently, such as next, or after with hasMore. Some lists also take before, the createdAt of the last item you have; it skips items that share that time, so use cursor where a list offers it. Each list endpoint's parameters and response say which it takes, and its largest limit.
Rate limits
Each credential may make 600 requests a minute, and a workspace 1,800 across all its credentials. Past that, the API answers 429 rate_limited with Retry-After in seconds.
OpenAPI and MCP
The same reference is an OpenAPI 3.1 document, for generating a client or importing into an API tool. Each operation lists the scopes it needs in x-scopes, and the plan feature in x-plan-feature.
OpenAPI document
https://api.flipbird.io/api/docs An assistant can call the same endpoints as tools through the Model Context Protocol, with OAuth instead of a key.
Reference
- DocumentsList, read, make and change documents, and read and download their versions.
- UploadsUpload a PDF as a new version of a document, in one call or in resumable parts.
- Editing sessionsEdit a document's draft on the server, then save it as a new version or throw it away.
- TrashMove documents and versions to the trash, and take them out again.
- ExportsExport a version as SVG, pictures, an HTML flipbook or an offline zip.
- Text recognitionRecognise the text on a scanned version and store a searchable PDF.
- JobsFollow the background work on a document.
- PublishingPut a document in front of readers at a fixed address, choose who may read it, and schedule or expire it.
- Flipbook looksSave named flipbook looks and choose which a document uses.
- EnrichmentLay hotspots, calls to action, videos and image galleries over a published document's pages.
- Lead captureAsk a publication's readers for their details before they read on, then list, export and erase what they send.
- CollectionsGroup published documents into a bookshelf or kiosk under one address, with its own look, order and access.
- LinksMake short links and QR codes, change where they send people, route them by rules, and make variants per recipient.
- QR codesDraw a link's QR code as SVG or PNG, save named QR designs, and choose the documents a QR code may be placed on.
- Links in documentsRecord where QR codes and link annotations sit in a document, and read its scan-to-open QR code.
- AnalyticsRead and export how documents are read, and how short links and QR codes are visited.
- MediaKeep the workspace's pictures (SVG and raster originals) and videos, with previews and a record of which documents use them.
- FontsUpload the workspace's own font faces for editing documents and for flipbooks, and see which fonts a document uses.
- Folders and accessList, make, rename, move and delete folders, and restrict who may see or change folders and documents.
- TeamList members and change their roles, invite people, and gather members into groups for access.
- Audit logRead and export the workspace's record of who did what, and when.
- WebhooksReceive signed events, and manage the endpoints they are sent to and each delivery.
- Plan and billingWhat the plan allows, the credit balance and its history, usage, invoices and saved cards.