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 with Content-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 an Idempotency-Key header, 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 stable code to switch on and an X-Request-Id header 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