API

Media

Keep the workspace's pictures (SVG and raster originals) and videos, with previews and a record of which documents use them.

An asset is an original the workspace keeps in its media library: an SVG the editor rasterised into a page (svg-original), a PNG, JPEG, GIF or WebP it placed (image), or an MP4, QuickTime or WebM video (video). The kind is read from the bytes and the file's structure is checked, so a file cut short, damaged, or not what its name says is refused with a code saying why. An upload of bytes already kept returns the existing asset, and every original counts toward the plan's storage. An SVG must load nothing from outside the file, and is never served where it could run: downloads are attachments, and an SVG's thumbnail, like a video's poster frame, is a raster preview the client sends (assets.setPreview).

Assets are filed in media folders, paths such as /brand/2026/ (assetFolders.*; assets.list takes folder, assets.upload a folder to file in, assets.move refiles). Media folders are their own tree, apart from document folders, and have no access rules: whoever can list the media library sees every folder. A folder is renamed or moved with everything in it, and deleted only when it is empty.

A video is at most 95 MiB, sent with a Content-Length and streamed into storage as it arrives; its width, height and durationMs are read from the file. A video is never placed as a picture: picture pickers list kind=image,svg-original, and assets.recordUsages, a look's pictures, an enrichment gallery and a document's imageLayout refuse one.

After saving a version that contains pictures made from assets, record them with assets.recordUsages. assets.get then lists the documents that use an asset. While any do, or while an enrichment gallery shows it, assets.delete refuses with 409 asset_in_use unless force=true. Documents keep their pictures when an original is deleted. Documents in folders the caller cannot see are counted, never named.

A PNG, JPEG, GIF or WebP picture can be converted to PNG (animated PNG when it moves), JPEG, WebP, AVIF, GIF, TIFF, BMP, ICO, HEIC or JPEG XL, with each format's options and crop, turn, flip and resize applied to every frame (assets.transform, or assetTransforms.download for bytes sent as the body), and the result downloaded or kept as a new asset (assets.transformSave, assetTransforms.save; the library keeps PNG, JPEG, WebP and GIF). assets.animation says whether a picture moves; assets.extractFrames keeps an animation's frames in a new folder. Conversions run in the engine container, within limits each route states, and are limited to 20 a minute per caller and per address.

Store a picture or a video in the media library

POST /assets assets.upload

Send an SVG (at most 10 MiB), a PNG, JPEG, GIF or WebP image (at most 25 MiB), or an MP4, QuickTime (.mov) or WebM video (at most 95 MiB) as the body.

The kind is read from the bytes, never the name, and the file's structure is checked, not just its first bytes: a PNG's chunks from IHDR to IEND, with the checksums of IHDR, PLTE, IDAT and IEND; a JPEG's segments from SOI to the EOI that ends its image (bytes after that EOI, such as a phone's motion-photo video, are kept); a GIF's blocks to its trailer; a WebP's RIFF size against the file.

Bytes after a picture's end (IEND, the trailer, the RIFF size) are kept, as browsers ignore them. Then an MP4's or MOV's top-level boxes tiling the whole file, one moov with a duration and a video track with a picture size, and at least one mdat; a WebM's EBML header (DocType webm), Segment, Info, Tracks with a video track, and Clusters, every element within the file.

An SVG must be UTF-8 with an <svg> root, no DOCTYPE or entity declarations, and nothing that loads from outside the file (images and fonts in it must be data: URLs); it is kept as sent. For a picture, width, height and dpi record what the editor made of it; for a video they are ignored, and its width, height and durationMs are read from the file.

A video is streamed into storage as it arrives, so it must be sent with a Content-Length (411 length_required without one), and it is measured against the plan's storage before it is read. Bytes the workspace already keeps return the stored asset, so sending an upload again is safe: an Idempotency-Key is not needed here and is ignored (the body is streamed, never held for a replay).

Refused with a 402 when it would take the workspace past its plan's storage; nothing stored is ever removed for that. Other refusals: 400 empty_body for an empty body; 400 length_mismatch when the body is not as long as its Content-Length; 415 unsupported_asset for anything but those eight types; 415 malformed_svg for an SVG that fails those checks; 413 too_large past the size for its type.

A file whose structure does not hold is refused with 415 and one of these codes, its message saying what is wrong: truncated (the file ends before its structure does (an upload or export cut short)); trailing_data (bytes after an MP4's, MOV's or WebM's end that are not part of it (a picture's are kept)); malformed_structure (a box, chunk, segment or element whose header cannot be right); bad_checksum (a PNG IHDR, PLTE, IDAT or IEND chunk whose CRC does not match); ftyp_not_first (an MP4 whose ftyp box is not its first); no_header (an MP4 or MOV with no moov box, or a WebM with no Segment or Info); duplicate_header (an MP4 or MOV with more than one moov box); no_media_data (no media data: an MP4 without mdat, a WebM without a Cluster, a picture without image data); no_duration (a video that does not say how long it is); no_video_track (a file with no video track, such as audio only); no_video_size (a video track with no picture size); not_webm (a Matroska file whose DocType is not webm (an .mkv)); index_too_large (an MP4 moov over 16 MB, or WebM Info or Tracks over 1 MB); unsupported_brand (an ISO media file that is a HEIF or AVIF image rather than a video).

Scopes
documents.edit

Query parameters

NameTypeDescription
filename string The name the library shows it by and the original downloads as. Control and direction characters are removed. Left out, it has none. At most 200 characters.
width number A picture's width as the editor reports it, stored with the asset. Not checked against the bytes. Ignored for a video. More than 0. At most 1,000,000.
height number A picture's height as the editor reports it, stored with the asset. Not checked against the bytes. Ignored for a video. More than 0. At most 1,000,000.
dpi number A picture's resolution in dots per inch as the editor reports it, stored with the asset. Not checked against the bytes. Ignored for a video. More than 0. At most 1,000,000.
folder string The media folder to file it in, made with its ancestors if it does not exist: a path such as /brand/2026/. Left out, /. Bytes the workspace already keeps stay where they are. 1 to 1,100 characters.

Request body

The raw bytes, at most 95 MiB, sent as application/octet-stream.

Response

201 Created. A JSON object:

Response fields (17)
NameTypeDescription
asset object The stored asset: the new one, or the one the workspace already kept with these bytes.
asset.id string The asset's id.
asset.kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
asset.contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
asset.filename string The name the library shows it by and the original downloads as. Empty when none was given.
asset.size number The original's size in bytes.
asset.sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
asset.width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
asset.height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
asset.dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
asset.durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
asset.folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
asset.hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
asset.previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
asset.createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
asset.createdAt number When it was uploaded, in epoch milliseconds.
deduplicated boolean True when the workspace already kept these bytes: the existing asset is returned unchanged, and the query values given are ignored.

Example request

curl -X POST https://api.flipbird.io/api/v1/assets \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @part-1.bin
Example response
{
  "asset": {
    "id": "string",
    "kind": "svg-original",
    "contentType": "string",
    "filename": "catalogue.pdf",
    "size": 1,
    "sha256": "string",
    "width": 1,
    "height": 1,
    "dpi": 1,
    "durationMs": 1,
    "folder": "/catalogues",
    "hasPreview": true,
    "previewSize": 1,
    "createdBy": "string",
    "createdAt": 1767225600000
  },
  "deduplicated": true
}

List the workspace's media library, newest first

GET /assets assets.list

kind keeps one kind, or several separated by commas: image,svg-original lists the pictures, which is what a picture picker shows. q matches part of the filename, or an asset id. Pass next back as cursor for the following page. documents counts the documents using a picture that you may open; hiddenDocuments counts those in folders you cannot see. A video is never used by a document, so both are 0.

folder keeps the assets in that media folder and, unless subfolders=false, in the folders under it, as documents.list does.

Scopes
documents.read
MCP tool
assets_list

Query parameters

NameTypeDescription
kind string One kind (svg-original, image, video), or several separated by commas. Left out, every kind. Matches ^(?:svg-original|image|video)(?:,(?:svg-original|image|video))*$.
folder string Only this media folder and, unless subfolders is false, those under it. Left out, /: every folder. 1 to 1,100 characters.
subfolders string false lists only the assets filed in folder itself. Left out, true: the folders under it too. One of true, false.
q string Part of a filename to match, without regard to case, or an asset's whole id. At most 200 characters.
cursor string The previous page's next. Left out, the first page. Matches ^\d{1,16}\.ast_[0-9a-z]{20}$.
limit integer Most assets to return. Default 50. 1 to 200.

Response

200 OK. A JSON object:

Response fields (19)
NameTypeDescription
assets array of objects This page's assets, newest first. Deleted assets are not listed.
assets[].id string The asset's id.
assets[].kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
assets[].contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
assets[].filename string The name the library shows it by and the original downloads as. Empty when none was given.
assets[].size number The original's size in bytes.
assets[].sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
assets[].width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
assets[].height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
assets[].dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
assets[].durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
assets[].folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
assets[].hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
assets[].previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
assets[].createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
assets[].createdAt number When it was uploaded, in epoch milliseconds.
assets[].documents number How many documents the caller may open contain a picture made from it.
assets[].hiddenDocuments number How many documents in folders the caller cannot see contain a picture made from it: counted, never named.
next string Pass it back as cursor for the next page. Null when this page holds fewer than limit. Can be null.

Example request

curl https://api.flipbird.io/api/v1/assets \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "assets": [
    {
      "id": "string",
      "kind": "svg-original",
      "contentType": "string",
      "filename": "catalogue.pdf",
      "size": 1,
      "sha256": "string",
      "width": 1,
      "height": 1,
      "dpi": 1,
      "durationMs": 1,
      "folder": "/catalogues",
      "hasPreview": true,
      "previewSize": 1,
      "createdBy": "string",
      "createdAt": 1767225600000,
      "documents": 1,
      "hiddenDocuments": 1
    }
  ],
  "next": "string"
}

One asset, with the documents that contain a picture made from it

GET /assets/{assetId} assets.get

usedIn names only documents you may open; hiddenDocuments counts the others, in folders you cannot see. galleries names the documents you may open whose enrichment galleries show it, and hiddenGalleries counts the others. Documents that have been purged from the trash are not counted. An unknown or deleted asset answers 404 not_found.

Scopes
documents.read
MCP tool
assets_get

Path parameters

NameTypeDescription
assetId required string The asset's id. An id starting ast_.

Response

200 OK. A JSON object:

Response fields (27)
NameTypeDescription
asset object The asset.
asset.id string The asset's id.
asset.kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
asset.contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
asset.filename string The name the library shows it by and the original downloads as. Empty when none was given.
asset.size number The original's size in bytes.
asset.sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
asset.width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
asset.height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
asset.dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
asset.durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
asset.folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
asset.hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
asset.previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
asset.createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
asset.createdAt number When it was uploaded, in epoch milliseconds.
usedIn array of objects The documents the caller may open whose recorded versions contain a picture made from it (assets.recordUsages), most recently recorded first.
usedIn[].documentId string The document's id.
usedIn[].title string The document's title.
usedIn[].trashed boolean Whether the document is in the trash.
usedIn[].versions array of numbers The document's version numbers that contain the picture, newest first.
hiddenDocuments number How many other documents, in folders the caller cannot see, contain it: counted, never named.
galleries array of objects The documents the caller may open whose enrichment galleries show it, by title.
galleries[].documentId string The document's id.
galleries[].title string The document's title.
galleries[].trashed boolean Whether the document is in the trash.
hiddenGalleries number How many other documents' galleries show it, in folders the caller cannot see: counted, never named.

Example request

curl https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "asset": {
    "id": "string",
    "kind": "svg-original",
    "contentType": "string",
    "filename": "catalogue.pdf",
    "size": 1,
    "sha256": "string",
    "width": 1,
    "height": 1,
    "dpi": 1,
    "durationMs": 1,
    "folder": "/catalogues",
    "hasPreview": true,
    "previewSize": 1,
    "createdBy": "string",
    "createdAt": 1767225600000
  },
  "usedIn": [
    {
      "documentId": "…",
      "title": "Spring catalogue",
      "trashed": true,
      "versions": [
        1
      ]
    }
  ],
  "hiddenDocuments": 1,
  "galleries": [
    {
      "documentId": "…",
      "title": "Spring catalogue",
      "trashed": true
    }
  ],
  "hiddenGalleries": 1
}

Download an asset's original

GET /assets/{assetId}/file assets.download

The original's bytes as stored, with its media type. Always an attachment, named by its filename with its type's extension, with a sandboxing Content-Security-Policy, so an SVG never runs on this site. A video is streamed as it is decrypted, so damage found in storage part way through ends the response early rather than answering 410.

An unknown or deleted asset answers 404 not_found; 410 gone when its file can no longer be read.

Scopes
documents.read

Path parameters

NameTypeDescription
assetId required string The asset's id. An id starting ast_.

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/assets/ast_7m2kq9vx4c8d1r5t6wnb/file \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

Store a rasterised preview of an asset

PUT /assets/{assetId}/preview assets.setPreview

A PNG, JPEG or WebP of at most 1 MiB, for the library's thumbnails, replacing any earlier one. The editor sends the raster it already made, so an SVG is never drawn on this site to show it; for a video, the library sends a poster frame it drew. Counts toward the plan's storage: refused with a 402 when it would take the workspace past it.

Other refusals: 415 unsupported_preview when the body is not a PNG, JPEG or WebP; 409 preview_changed when another preview was stored at the same moment; 404 not_found for an unknown or deleted asset. Returns the asset with its new previewSize.

Scopes
documents.edit.any
Retries
Safe with an Idempotency-Key

Path parameters

NameTypeDescription
assetId required string The asset's id. An id starting ast_.

Request body

The raw bytes, at most 1 MiB, sent as application/octet-stream.

Response

200 OK. A JSON object:

Response fields (16)
NameTypeDescription
asset object The asset, with its new preview.
asset.id string The asset's id.
asset.kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
asset.contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
asset.filename string The name the library shows it by and the original downloads as. Empty when none was given.
asset.size number The original's size in bytes.
asset.sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
asset.width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
asset.height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
asset.dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
asset.durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
asset.folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
asset.hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
asset.previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
asset.createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
asset.createdAt number When it was uploaded, in epoch milliseconds.

Example request

curl -X PUT https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/preview \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @part-1.bin
Example response
{
  "asset": {
    "id": "string",
    "kind": "svg-original",
    "contentType": "string",
    "filename": "catalogue.pdf",
    "size": 1,
    "sha256": "string",
    "width": 1,
    "height": 1,
    "dpi": 1,
    "durationMs": 1,
    "folder": "/catalogues",
    "hasPreview": true,
    "previewSize": 1,
    "createdBy": "string",
    "createdAt": 1767225600000
  }
}

An asset's rasterised preview

GET /assets/{assetId}/preview assets.preview

The stored preview, or a raster image itself, served inline with its media type. An SVG or a video with no preview has none (404 no_preview); neither is ever served as its own preview. 410 gone when the file can no longer be read; 404 not_found for an unknown or deleted asset.

Scopes
documents.read

Path parameters

NameTypeDescription
assetId required string The asset's id. An id starting ast_.

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/assets/ast_7m2kq9vx4c8d1r5t6wnb/preview \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

Rename an asset

PATCH /assets/{assetId} assets.update

Changes the name the library shows it by and the original downloads as. The bytes, their kind and where they are used stay as they are. A name that is empty once control and direction characters are removed answers 400 invalid_filename. An unknown or deleted asset answers 404 not_found.

Scopes
documents.edit.any
Retries
Safe with an Idempotency-Key
MCP tool
assets_update

Path parameters

NameTypeDescription
assetId required string The asset's id. An id starting ast_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
filename required string The new name. Control and direction characters are removed. 1 to 200 characters.

Response

200 OK. A JSON object:

Response fields (16)
NameTypeDescription
asset object The asset as renamed.
asset.id string The asset's id.
asset.kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
asset.contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
asset.filename string The name the library shows it by and the original downloads as. Empty when none was given.
asset.size number The original's size in bytes.
asset.sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
asset.width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
asset.height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
asset.dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
asset.durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
asset.folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
asset.hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
asset.previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
asset.createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
asset.createdAt number When it was uploaded, in epoch milliseconds.

Example request

curl -X PATCH https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "catalogue.pdf"
}'
Example response
{
  "asset": {
    "id": "string",
    "kind": "svg-original",
    "contentType": "string",
    "filename": "catalogue.pdf",
    "size": 1,
    "sha256": "string",
    "width": 1,
    "height": 1,
    "dpi": 1,
    "durationMs": 1,
    "folder": "/catalogues",
    "hasPreview": true,
    "previewSize": 1,
    "createdBy": "string",
    "createdAt": 1767225600000
  }
}

Delete an asset

DELETE /assets/{assetId} assets.delete

Refused (409 asset_in_use, naming in error.details.documents the documents you may open and counting the rest as hiddenDocuments) while a document that is not purged contains a picture made from it, or while a document's enrichment gallery shows it (galleries and hiddenGalleries, likewise), unless force=true.

Documents keep their pictures either way: what goes is the original, and its preview; a gallery that showed it shows its other images, and a look that used it shows nothing in its place. The record of which documents used it stays. An unknown or already deleted asset answers 404 not_found.

Scopes
documents.edit.any
Retries
Safe with an Idempotency-Key
MCP tool
assets_delete

Path parameters

NameTypeDescription
assetId required string The asset's id. An id starting ast_.

Query parameters

NameTypeDescription
force string true deletes it even while documents contain pictures made from it or galleries show it. Left out, false. One of true, false.

Response

200 OK. An empty JSON object, {}.

Example request

curl -X DELETE https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Record which pictures from the library a saved version contains

POST /documents/{documentId}/versions/{version}/assets assets.recordUsages

Call it after saving a version, with the asset ids the editor placed in it. It needs edit access to the document. Every id must be a live asset of this workspace (422 unknown_assets, listing those that are not in error.details.missing, and nothing is recorded), and a picture: a video is never placed in a document (422 not_pictures, listing the videos in error.details.videos, and nothing is recorded).

Recording one twice is harmless. A version the document does not have answers 404 not_found; 403 forbidden when the caller may only view the document.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.
version required integer The version's number. At least 1.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
assetIds required array of strings The ids of the pictures (SVG originals and images) the version contains. An id given twice counts once. 1 to 200 items.

Response

200 OK. A JSON object:

Response fields (2)
NameTypeDescription
recorded number How many were new: an asset already recorded for this version is not counted again.
assetIds array of strings The asset ids recorded for the version, each once.

Example request

curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/assets \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "assetIds": [
    "ast_7m2kq9vx4c8d1r5t6wnb"
  ]
}'
Example response
{
  "recorded": 1,
  "assetIds": [
    "string"
  ]
}

The pictures from the library a version is recorded as containing

GET /documents/{documentId}/versions/{version}/assets assets.versionUsages

What assets.recordUsages recorded for this version, oldest first, each with whether the original has since been deleted (a deleted one cannot be recorded again). The editor reads it when it saves the next version, to record the pictures that version still holds. It needs access to open the document: one in a folder you cannot see is a 404, as is a document of another workspace.

A version the document does not have answers 404 not_found.

Scopes
documents.read

Path parameters

NameTypeDescription
documentId required string The document's id. An id starting doc_.
version required integer The version's number. At least 1.

Response

200 OK. A JSON object:

Response fields (4)
NameTypeDescription
version number The version's number.
assets array of objects The assets recorded for the version, oldest record first.
assets[].id string The asset's id.
assets[].deleted boolean Whether the asset has been deleted since it was recorded.

Example request

curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/versions/1/assets \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "version": 1,
  "assets": [
    {
      "id": "string",
      "deleted": true
    }
  ]
}

List the media library's folders

GET /asset-folders assetFolders.list

Every media folder, sorted: /, each folder made with assetFolders.create or by filing an asset in it (empty ones included), and the folders above each. Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.

Scopes
documents.read
MCP tool
asset_folders_list

Response

200 OK. A JSON object:

Response fields (1)
NameTypeDescription
folders array of strings Media folder paths, sorted, / first.

Example request

curl https://api.flipbird.io/api/v1/asset-folders \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "folders": [
    "string"
  ]
}

Create a media folder, including its ancestors

POST /asset-folders assetFolders.create

Makes the folder and any folder above it that does not exist yet, and returns the path as stored. A folder that exists already is left as it is (created false). A path that is not a valid folder answers 400 invalid. Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
asset_folders_create

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
path required string The folder's path: a path such as /brand/2026/. 1 to 1,100 characters.

Response

201 Created. A JSON object:

Response fields (2)
NameTypeDescription
path string The folder's path as stored, ending in /.
created boolean Whether it was made now; false when it existed already.

Example request

curl -X POST https://api.flipbird.io/api/v1/asset-folders \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "string"
}'
Example response
{
  "path": "string",
  "created": true
}

Rename or move a media folder

POST /asset-folders/move assetFolders.move

Moves the folder from to the path to: the folder, every folder under it and every asset in or under it take the new path together, and the folders above to are made. Folders are not merged: a to that exists already (a folder, or an asset filed there or under it) answers 409 folder_exists.

Moving /, moving a folder into itself or a folder under it, or a move that would put a folder under it more than 12 levels deep answers 400 invalid_folder_move; a from with nothing in it and no folder answers 404 not_found; a path that is not a valid folder answers 400 invalid.

Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
asset_folders_move

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
from required string The folder to move: a path such as /brand/2026/. 1 to 1,100 characters.
to required string Its new path. To rename /brand/old/, give /brand/new/; to move it, give a path under another folder. 1 to 1,100 characters.

Response

200 OK. A JSON object:

Response fields (4)
NameTypeDescription
from string The folder's old path, as stored.
to string Its new path, as stored.
folders number How many folders moved: the folder and those under it that were kept as folders.
assets number How many assets moved with it.

Example request

curl -X POST https://api.flipbird.io/api/v1/asset-folders/move \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "string",
  "to": "string"
}'
Example response
{
  "from": "string",
  "to": "string",
  "folders": 1,
  "assets": 1
}

Delete an empty media folder

DELETE /asset-folders assetFolders.delete

Deletes the folder and the folders under it, only while no asset is filed in it or under it: 409 folder_not_empty otherwise, with error.details.assets counting them. Move or delete those first. / cannot be deleted (400 invalid); a folder that does not exist answers 404 not_found.

Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
asset_folders_delete

Query parameters

NameTypeDescription
path required string The folder to delete: a path such as /brand/2026/. 1 to 1,100 characters.

Response

200 OK. A JSON object:

Response fields (1)
NameTypeDescription
folders number How many folders were deleted: the folder and the empty ones under it.

Example request

curl -X DELETE "https://api.flipbird.io/api/v1/asset-folders?path=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response
{
  "folders": 1
}

File assets in a media folder

POST /asset-folders/assets assets.move

Moves each of these assets to the folder, made with its ancestors if it does not exist. Every id must be a live asset of this workspace (422 unknown_assets, listing those that are not in error.details.missing, and nothing moves); a path that is not a valid folder answers 400 invalid.

Media folders are a tree of their own, apart from document folders, and carry no access rules: whoever can list the media library sees every folder.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
assets_move

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
assetIds required array of strings The assets to move. An id given twice counts once. 1 to 200 items.
folder required string The folder to file them in: a path such as /brand/2026/. 1 to 1,100 characters.

Response

200 OK. A JSON object:

Response fields (2)
NameTypeDescription
folder string The folder as stored.
moved number How many assets were filed there.

Example request

curl -X POST https://api.flipbird.io/api/v1/asset-folders/assets \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "assetIds": [
    "ast_7m2kq9vx4c8d1r5t6wnb"
  ],
  "folder": "/catalogues"
}'
Example response
{
  "folder": "/catalogues",
  "moved": 1
}

Convert a picture in the library and download the result

POST /assets/{assetId}/transform assets.transform

Converts the asset's original to any of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl, with its options, and the geometry the editor applied (ops) replayed on every frame, so an animation stays one where the format can hold it.

The converted file is the response: its media type, an attachment named after the source with the format's extension, a sandboxing Content-Security-Policy, and X-Image-Width, X-Image-Height, X-Image-Frames and X-Image-Adjusted (true when a faster setting than the one asked was used to fit the time) headers. Nothing is stored.

It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.

Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).

A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits. An SVG or a video answers 422 unsupported_image; an unknown or deleted asset 404 not_found.

Scopes
documents.edit

Path parameters

NameTypeDescription
assetId required string The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
transform required object The conversion: output says what to write; geometry, background, animation and metadata choices apply to every format.
transform.output required object The format to write, one of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl, and that format's own options. One of 10 shapes, chosen by format.
transform.output.format required string png: PNG. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl.
transform.output.options object PNG's options. Each left out takes its default. Only when format is png. Default {}.
transform.output.options.compression string Compression: How hard to work at making the file smaller. The pixels are the same either way. One of fast, balanced, smallest; left out, balanced. One of fast, balanced, smallest. Default balanced.
transform.output.options object JPEG's options. Each left out takes its default. Only when format is jpeg. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 85. 1 to 100. Default 85.
transform.output.options.progressive boolean Progressive: Shows a rough picture first while it loads. Left out, true. Default true.
transform.output.options.chroma string Chroma subsampling: How much colour detail to keep. 4:4:4 keeps it all, for text and sharp edges; 4:2:0 is smallest. One of 4:2:0, 4:2:2, 4:4:4; left out, 4:2:0. One of 4:2:0, 4:2:2, 4:4:4. Default 4:2:0.
transform.output.options object WebP's options. Each left out takes its default. Only when format is webp. Default {}.
transform.output.options.lossless boolean Lossless: Keeps every pixel exactly. Quality then sets how hard it works at a small file. Left out, false. Default false.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 80. 0 to 100. Default 80.
transform.output.options.effort integer Effort: 0 is fastest, 6 makes the smallest file. 0 to 6; left out, 4. 0 to 6. Default 4.
transform.output.options object AVIF's options. Each left out takes its default. Only when format is avif. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 60. 0 to 100. Default 60.
transform.output.options.speed integer Speed: 6 makes the smallest file, 10 is fastest. 6 to 10; left out, 6. 6 to 10. Default 6.
transform.output.options.lossless boolean Lossless: Keeps every pixel exactly; the file is much larger. Left out, false. Default false.
transform.output.options object GIF's options. Each left out takes its default. Only when format is gif. Default {}.
transform.output.options.colours integer Colours: Fewer colours make a smaller file. 2 to 256; left out, 256. 2 to 256. Default 256.
transform.output.options.dither string Dithering: How the missing colours are mixed from those kept. One of floyd-steinberg, riemersma, none; left out, floyd-steinberg. One of floyd-steinberg, riemersma, none. Default floyd-steinberg.
transform.output.options.optimise boolean Optimise: Stores only what changes between frames. Left out, true. Default true.
transform.output.options.lossy integer Lossy compression: 0 is off. Higher trades some noise for a smaller file. 0 to 200; left out, 0. 0 to 200. Default 0.
transform.output.options object TIFF's options. Each left out takes its default. Only when format is tiff. Default {}.
transform.output.options.compression string Compression: LZW and ZIP are lossless; JPEG is lossy and drops transparency. One of none, lzw, zip, jpeg; left out, lzw. One of none, lzw, zip, jpeg. Default lzw.
transform.output.options object BMP's options. Each left out takes its default. Only when format is bmp. Default {}.
transform.output.options object ICO (icon)'s options. Each left out takes its default. Only when format is ico. Default {}.
transform.output.options.sizes array of numbers Sizes: The square sizes, in pixels, the icon holds. Any of 16, 24, 32, 48, 64, 128, 256; left out, 16, 32, 48. 1 to 7 items. Default [16,32,48].
transform.output.options object HEIC's options. Each left out takes its default. Only when format is heic. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 50. 1 to 100. Default 50.
transform.output.options object JPEG XL's options. Each left out takes its default. Only when format is jxl. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail; 100 is lossless. 1 to 100; left out, 90. 1 to 100. Default 90.
transform.output.options.effort integer Effort: 1 is fastest, 7 makes the smallest file. 1 to 7; left out, 7. 1 to 7. Default 7.
transform.output.options.lossless boolean Lossless: Keeps every pixel exactly (the same as quality 100). Left out, false. Default false.
transform.ops array of objects Geometry applied in order to every frame, at most 16: what the image editor did to a picture, replayed on the original so an animation keeps its frames. Coordinates are in the picture as it stands after the operations before. Left out, none. At most 16 items. Default [].
transform.ops[].op required string crop: keep a rectangle of the picture as it stands after the operations before this one. One of crop, rotate, flip, resize.
transform.ops[].x required integer The rectangle's left edge, in pixels from the top left. Only when op is crop. 0 to 15,999.
transform.ops[].y required integer The rectangle's top edge, in pixels from the top left. Only when op is crop. 0 to 15,999.
transform.ops[].width required integer The rectangle's width, in pixels. Only when op is crop. 1 to 16,000.
transform.ops[].height required integer The rectangle's height, in pixels. Only when op is crop. 1 to 16,000.
transform.ops[].degrees required number 90, 180 or 270, clockwise. Only when op is rotate. One of 90, 180, 270.
transform.ops[].direction required string horizontal mirrors left to right; vertical turns it upside down without turning it. Only when op is flip. One of horizontal, vertical.
transform.ops[].width integer The box's width in pixels. Left out, it follows from height and the picture's shape. Only when op is resize. 1 to 16,000.
transform.ops[].height integer The box's height in pixels. Left out, it follows from width and the picture's shape. Only when op is resize. 1 to 16,000.
transform.ops[].fit string contain fits the picture inside the box, keeping its shape; cover fills the box, keeping its shape and cutting what spills over from the centre (needs width and height); stretch makes it exactly the box (needs width and height). Left out, contain. Only when op is resize. One of contain, cover, stretch. Default contain.
transform.ops[].upscale boolean Whether a picture smaller than the box is made larger. Left out, false: it keeps its size (cover then cuts it to the box). Only when op is resize. Default false.
transform.animation string For an animated source: keep keeps every frame where the format can hold them, first keeps the first frame only. Left out, keep. One of keep, first. Default keep.
transform.loop integer How many times an animation plays, 0 for ever. Left out, as the source says. AVIF ignores it and always loops for ever. 0 to 65,535.
transform.stripMetadata boolean Removes EXIF, XMP, comments and the colour profile. Left out, true. A JPEG is turned upright by its EXIF orientation first either way. Kept only in a still PNG, JPEG, WebP, GIF, TIFF or HEIC; an animated PNG or WebP, AVIF and JPEG XL never keep them. Default true.
transform.background string The colour, as #rrggbb, a picture is laid on for a format without transparency (JPEG, BMP, TIFF with JPEG compression). Left out, white. Matches ^#[0-9a-fA-F]{6}$. Default #ffffff.

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/assets/ast_7m2kq9vx4c8d1r5t6wnb/transform \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transform": {
    "output": {
      "format": "png"
    }
  }
}' \
  -OJ

Convert a picture in the library and keep the result as a new asset

POST /assets/{assetId}/transform/save assets.transformSave

The conversion of assets.transform, kept. Kept as a new asset in the media library, which keeps PNG, JPEG, WebP, GIF (the other formats are only downloaded: 422 not_kept). The result is checked as an upload is (its structure, from its bytes) and counts toward the plan's storage: refused with a 402 when it would take the workspace past it, checked before the converter runs and again as the asset is recorded.

Bytes the workspace already keeps return the stored asset. The original is never replaced. A repeat with the same Idempotency-Key returns the first answer. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.

Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).

A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key

Path parameters

NameTypeDescription
assetId required string The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
transform required object The conversion: output says what to write; geometry, background, animation and metadata choices apply to every format.
transform.output required object The format to write, one of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl, and that format's own options. One of 10 shapes, chosen by format.
transform.output.format required string png: PNG. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl.
transform.output.options object PNG's options. Each left out takes its default. Only when format is png. Default {}.
transform.output.options.compression string Compression: How hard to work at making the file smaller. The pixels are the same either way. One of fast, balanced, smallest; left out, balanced. One of fast, balanced, smallest. Default balanced.
transform.output.options object JPEG's options. Each left out takes its default. Only when format is jpeg. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 85. 1 to 100. Default 85.
transform.output.options.progressive boolean Progressive: Shows a rough picture first while it loads. Left out, true. Default true.
transform.output.options.chroma string Chroma subsampling: How much colour detail to keep. 4:4:4 keeps it all, for text and sharp edges; 4:2:0 is smallest. One of 4:2:0, 4:2:2, 4:4:4; left out, 4:2:0. One of 4:2:0, 4:2:2, 4:4:4. Default 4:2:0.
transform.output.options object WebP's options. Each left out takes its default. Only when format is webp. Default {}.
transform.output.options.lossless boolean Lossless: Keeps every pixel exactly. Quality then sets how hard it works at a small file. Left out, false. Default false.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 80. 0 to 100. Default 80.
transform.output.options.effort integer Effort: 0 is fastest, 6 makes the smallest file. 0 to 6; left out, 4. 0 to 6. Default 4.
transform.output.options object AVIF's options. Each left out takes its default. Only when format is avif. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 0 to 100; left out, 60. 0 to 100. Default 60.
transform.output.options.speed integer Speed: 6 makes the smallest file, 10 is fastest. 6 to 10; left out, 6. 6 to 10. Default 6.
transform.output.options.lossless boolean Lossless: Keeps every pixel exactly; the file is much larger. Left out, false. Default false.
transform.output.options object GIF's options. Each left out takes its default. Only when format is gif. Default {}.
transform.output.options.colours integer Colours: Fewer colours make a smaller file. 2 to 256; left out, 256. 2 to 256. Default 256.
transform.output.options.dither string Dithering: How the missing colours are mixed from those kept. One of floyd-steinberg, riemersma, none; left out, floyd-steinberg. One of floyd-steinberg, riemersma, none. Default floyd-steinberg.
transform.output.options.optimise boolean Optimise: Stores only what changes between frames. Left out, true. Default true.
transform.output.options.lossy integer Lossy compression: 0 is off. Higher trades some noise for a smaller file. 0 to 200; left out, 0. 0 to 200. Default 0.
transform.output.options object TIFF's options. Each left out takes its default. Only when format is tiff. Default {}.
transform.output.options.compression string Compression: LZW and ZIP are lossless; JPEG is lossy and drops transparency. One of none, lzw, zip, jpeg; left out, lzw. One of none, lzw, zip, jpeg. Default lzw.
transform.output.options object BMP's options. Each left out takes its default. Only when format is bmp. Default {}.
transform.output.options object ICO (icon)'s options. Each left out takes its default. Only when format is ico. Default {}.
transform.output.options.sizes array of numbers Sizes: The square sizes, in pixels, the icon holds. Any of 16, 24, 32, 48, 64, 128, 256; left out, 16, 32, 48. 1 to 7 items. Default [16,32,48].
transform.output.options object HEIC's options. Each left out takes its default. Only when format is heic. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail and makes a larger file. 1 to 100; left out, 50. 1 to 100. Default 50.
transform.output.options object JPEG XL's options. Each left out takes its default. Only when format is jxl. Default {}.
transform.output.options.quality integer Quality: Higher keeps more detail; 100 is lossless. 1 to 100; left out, 90. 1 to 100. Default 90.
transform.output.options.effort integer Effort: 1 is fastest, 7 makes the smallest file. 1 to 7; left out, 7. 1 to 7. Default 7.
transform.output.options.lossless boolean Lossless: Keeps every pixel exactly (the same as quality 100). Left out, false. Default false.
transform.ops array of objects Geometry applied in order to every frame, at most 16: what the image editor did to a picture, replayed on the original so an animation keeps its frames. Coordinates are in the picture as it stands after the operations before. Left out, none. At most 16 items. Default [].
transform.ops[].op required string crop: keep a rectangle of the picture as it stands after the operations before this one. One of crop, rotate, flip, resize.
transform.ops[].x required integer The rectangle's left edge, in pixels from the top left. Only when op is crop. 0 to 15,999.
transform.ops[].y required integer The rectangle's top edge, in pixels from the top left. Only when op is crop. 0 to 15,999.
transform.ops[].width required integer The rectangle's width, in pixels. Only when op is crop. 1 to 16,000.
transform.ops[].height required integer The rectangle's height, in pixels. Only when op is crop. 1 to 16,000.
transform.ops[].degrees required number 90, 180 or 270, clockwise. Only when op is rotate. One of 90, 180, 270.
transform.ops[].direction required string horizontal mirrors left to right; vertical turns it upside down without turning it. Only when op is flip. One of horizontal, vertical.
transform.ops[].width integer The box's width in pixels. Left out, it follows from height and the picture's shape. Only when op is resize. 1 to 16,000.
transform.ops[].height integer The box's height in pixels. Left out, it follows from width and the picture's shape. Only when op is resize. 1 to 16,000.
transform.ops[].fit string contain fits the picture inside the box, keeping its shape; cover fills the box, keeping its shape and cutting what spills over from the centre (needs width and height); stretch makes it exactly the box (needs width and height). Left out, contain. Only when op is resize. One of contain, cover, stretch. Default contain.
transform.ops[].upscale boolean Whether a picture smaller than the box is made larger. Left out, false: it keeps its size (cover then cuts it to the box). Only when op is resize. Default false.
transform.animation string For an animated source: keep keeps every frame where the format can hold them, first keeps the first frame only. Left out, keep. One of keep, first. Default keep.
transform.loop integer How many times an animation plays, 0 for ever. Left out, as the source says. AVIF ignores it and always loops for ever. 0 to 65,535.
transform.stripMetadata boolean Removes EXIF, XMP, comments and the colour profile. Left out, true. A JPEG is turned upright by its EXIF orientation first either way. Kept only in a still PNG, JPEG, WebP, GIF, TIFF or HEIC; an animated PNG or WebP, AVIF and JPEG XL never keep them. Default true.
transform.background string The colour, as #rrggbb, a picture is laid on for a format without transparency (JPEG, BMP, TIFF with JPEG compression). Left out, white. Matches ^#[0-9a-fA-F]{6}$. Default #ffffff.
filename string The new asset's name. Control and direction characters are removed. Left out, the source's name with the format's extension. At most 200 characters.
folder string The media folder to file it in, made with its ancestors if it does not exist: a path such as /brand/2026/. Left out, the source's folder. 1 to 1,100 characters.

Response

201 Created. A JSON object:

Response fields (30)
NameTypeDescription
asset object The asset the result is kept as: a new one, or the one the workspace already kept with these bytes.
asset.id string The asset's id.
asset.kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
asset.contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
asset.filename string The name the library shows it by and the original downloads as. Empty when none was given.
asset.size number The original's size in bytes.
asset.sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
asset.width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
asset.height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
asset.dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
asset.durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
asset.folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
asset.hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
asset.previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
asset.createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
asset.createdAt number When it was uploaded, in epoch milliseconds.
deduplicated boolean True when the workspace already kept these exact bytes: that asset is returned, where it is filed, and nothing new is stored.
result object What the conversion made.
result.format string The format written. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl.
result.contentType string Its media type.
result.extension string Its file extension, without the dot.
result.width number The result's width in pixels (an icon's largest size).
result.height number The result's height in pixels.
result.frames number Frames in the result: 1 unless an animation was kept.
result.animated boolean Whether the result is an animation.
result.loop number How many times the animation plays, 0 for ever; null for a still. Can be null.
result.sourceFrames number Frames in the source.
result.size number The result's size in bytes.
result.settings map of anys The format's options the result was written with: those asked for, defaults filled, or a faster setting when those would not have fitted the time.
result.adjusted boolean True when settings differ from what was asked: a conversion that would take too long at the setting asked is written at the slowest faster setting that fits (a higher AVIF speed, a lower WebP or JPEG XL effort) rather than refused.

Example request

curl -X POST https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/transform/save \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "transform": {
    "output": {
      "format": "png"
    }
  }
}'
Example response
{
  "asset": {
    "id": "string",
    "kind": "svg-original",
    "contentType": "string",
    "filename": "catalogue.pdf",
    "size": 1,
    "sha256": "string",
    "width": 1,
    "height": 1,
    "dpi": 1,
    "durationMs": 1,
    "folder": "/catalogues",
    "hasPreview": true,
    "previewSize": 1,
    "createdBy": "string",
    "createdAt": 1767225600000
  },
  "deduplicated": true,
  "result": {
    "format": "png",
    "contentType": "string",
    "extension": "string",
    "width": 1,
    "height": 1,
    "frames": 1,
    "animated": true,
    "loop": 1,
    "sourceFrames": 1,
    "size": 1,
    "settings": {},
    "adjusted": true
  }
}

Convert a picture sent as the body and download the result

POST /asset-transforms assetTransforms.download

For the image editor's flattened canvas: send a PNG, JPEG, GIF or WebP of at most 25 MiB as application/octet-stream, and the conversion as the transform query value.

The converted file is the response: its media type, an attachment named after the source with the format's extension, a sandboxing Content-Security-Policy, and X-Image-Width, X-Image-Height, X-Image-Frames and X-Image-Adjusted (true when a faster setting than the one asked was used to fit the time) headers. Nothing is stored.

To keep an animation under the editor's crop, turn, flip and resize, convert the asset itself (assets.transform) with those as ops. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.

Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).

A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.

Scopes
documents.edit

Query parameters

NameTypeDescription
transform required string The conversion as JSON, the same object as the body of assets.transform's transform (URL-encoded): {"output":{"format":"webp","options":{"quality":80}}}. 400 invalid_request when it is not valid JSON or not a valid conversion. 2 to 8,192 characters.
filename string The name the download is given, its extension replaced by the format's. Left out, image. At most 200 characters.

Request body

The raw bytes, at most 25 MiB, sent as application/octet-stream.

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/asset-transforms?transform=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @part-1.bin \
  -OJ

Convert a picture sent as the body and keep the result as a new asset

POST /asset-transforms/save assetTransforms.save

The conversion of assetTransforms.download, kept. Kept as a new asset in the media library, which keeps PNG, JPEG, WebP, GIF (the other formats are only downloaded: 422 not_kept). The result is checked as an upload is (its structure, from its bytes) and counts toward the plan's storage: refused with a 402 when it would take the workspace past it, checked before the converter runs and again as the asset is recorded.

Bytes the workspace already keeps return the stored asset. The original is never replaced. A repeat with the same Idempotency-Key returns the first answer. The picture sent is not kept, only the result. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.

Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).

A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key

Query parameters

NameTypeDescription
transform required string The conversion as JSON, the same object as the body of assets.transform's transform (URL-encoded): {"output":{"format":"webp","options":{"quality":80}}}. 400 invalid_request when it is not valid JSON or not a valid conversion. 2 to 8,192 characters.
filename string The new asset's name. Control and direction characters are removed. Left out, image with the format's extension. At most 200 characters.
folder string The media folder to file it in, made with its ancestors if it does not exist: a path such as /brand/2026/. Left out, /. 1 to 1,100 characters.

Request body

The raw bytes, at most 25 MiB, sent as application/octet-stream.

Response

201 Created. A JSON object:

Response fields (30)
NameTypeDescription
asset object The asset the result is kept as: a new one, or the one the workspace already kept with these bytes.
asset.id string The asset's id.
asset.kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
asset.contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
asset.filename string The name the library shows it by and the original downloads as. Empty when none was given.
asset.size number The original's size in bytes.
asset.sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
asset.width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
asset.height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
asset.dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
asset.durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
asset.folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
asset.hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
asset.previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
asset.createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
asset.createdAt number When it was uploaded, in epoch milliseconds.
deduplicated boolean True when the workspace already kept these exact bytes: that asset is returned, where it is filed, and nothing new is stored.
result object What the conversion made.
result.format string The format written. One of png, jpeg, webp, avif, gif, tiff, bmp, ico, heic, jxl.
result.contentType string Its media type.
result.extension string Its file extension, without the dot.
result.width number The result's width in pixels (an icon's largest size).
result.height number The result's height in pixels.
result.frames number Frames in the result: 1 unless an animation was kept.
result.animated boolean Whether the result is an animation.
result.loop number How many times the animation plays, 0 for ever; null for a still. Can be null.
result.sourceFrames number Frames in the source.
result.size number The result's size in bytes.
result.settings map of anys The format's options the result was written with: those asked for, defaults filled, or a faster setting when those would not have fitted the time.
result.adjusted boolean True when settings differ from what was asked: a conversion that would take too long at the setting asked is written at the slowest faster setting that fits (a higher AVIF speed, a lower WebP or JPEG XL effort) rather than refused.

Example request

curl -X POST "https://api.flipbird.io/api/v1/asset-transforms/save?transform=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @part-1.bin
Example response
{
  "asset": {
    "id": "string",
    "kind": "svg-original",
    "contentType": "string",
    "filename": "catalogue.pdf",
    "size": 1,
    "sha256": "string",
    "width": 1,
    "height": 1,
    "dpi": 1,
    "durationMs": 1,
    "folder": "/catalogues",
    "hasPreview": true,
    "previewSize": 1,
    "createdBy": "string",
    "createdAt": 1767225600000
  },
  "deduplicated": true,
  "result": {
    "format": "png",
    "contentType": "string",
    "extension": "string",
    "width": 1,
    "height": 1,
    "frames": 1,
    "animated": true,
    "loop": 1,
    "sourceFrames": 1,
    "size": 1,
    "settings": {},
    "adjusted": true
  }
}

Keep an animation's frames as pictures in a new media folder

POST /assets/{assetId}/frames assets.extractFrames

Takes frames out of an animated GIF, WebP or PNG, each drawn whole (as the animation shows it, not just the part that changed), with ops applied to each, as PNG, JPEG or WebP, at most 100 frames and 24 MiB together (422 too_many_frames or too_large otherwise). They are kept in a new folder inside folder, named after the picture (name (2) and so on when that name is taken), each named after its frame.

A frame whose bytes the workspace already keeps is that asset, where it is filed.

Each frame is checked as an upload is and counts toward the plan's storage: the frames together are checked against it before the first is stored (402 otherwise); should storage fill between that check and the last frame (another upload at the same moment), the frames stored by then stay and the answer is a 402 whose error.details gives folder and stored.

The folder is made with the first frame not already kept, so when every frame is (a repeat), none is made and folder is null. A still answers with its one frame. A repeat with the same Idempotency-Key returns the first answer. It runs in the engine container: a source of at most 25 MiB, 16000 pixels a side, 50 million pixels a frame, 1000 frames and 100 million pixels in all; a result of at most 24 MiB; 60 seconds.

Refusals: 422 with a code saying why (unsupported_image, malformed_image, crop_outside, too_large, too_many_frames, too_many_pixels, no_frames, timed_out); 503 engine_busy when the converter is busy (try again shortly); 504 image_timeout; 502 engine_failed; 429 rate_limited past 20 conversions a minute for a caller, an address or the workspace, and 429 conversion_in_progress while another conversion for the workspace runs (one at a time).

A workspace whose credits are throttled is refused with 402 credits_required, as for other work the container runs; a conversion itself spends no credits.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key

Path parameters

NameTypeDescription
assetId required string The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
frames object Which frames to take and how to write them: at most 100 frames, together at most 24 MiB. Default {}.
frames.format string Each frame's format: png, jpeg or webp (lossy). Left out, png. One of png, jpeg, webp. Default png.
frames.quality integer For jpeg and webp: 1 to 100. Left out, 85 for JPEG and 80 for WebP. Ignored for png. 1 to 100.
frames.start integer The first frame to take, counted from 0. Left out, 0. 0 to 999. Default 0.
frames.end integer The last frame to take, counted from 0 and included. Left out, the animation's last frame. Past the last, the last. 0 to 999.
frames.every integer Take every nth frame from start: 1 takes them all, 2 every other. Left out, 1. 1 to 1,000. Default 1.
frames.ops array of objects Geometry applied in order to every frame, at most 16: what the image editor did to a picture, replayed on the original so an animation keeps its frames. Coordinates are in the picture as it stands after the operations before. Left out, none. At most 16 items. Default [].
frames.ops[].op required string crop: keep a rectangle of the picture as it stands after the operations before this one. One of crop, rotate, flip, resize.
frames.ops[].x required integer The rectangle's left edge, in pixels from the top left. Only when op is crop. 0 to 15,999.
frames.ops[].y required integer The rectangle's top edge, in pixels from the top left. Only when op is crop. 0 to 15,999.
frames.ops[].width required integer The rectangle's width, in pixels. Only when op is crop. 1 to 16,000.
frames.ops[].height required integer The rectangle's height, in pixels. Only when op is crop. 1 to 16,000.
frames.ops[].degrees required number 90, 180 or 270, clockwise. Only when op is rotate. One of 90, 180, 270.
frames.ops[].direction required string horizontal mirrors left to right; vertical turns it upside down without turning it. Only when op is flip. One of horizontal, vertical.
frames.ops[].width integer The box's width in pixels. Left out, it follows from height and the picture's shape. Only when op is resize. 1 to 16,000.
frames.ops[].height integer The box's height in pixels. Left out, it follows from width and the picture's shape. Only when op is resize. 1 to 16,000.
frames.ops[].fit string contain fits the picture inside the box, keeping its shape; cover fills the box, keeping its shape and cutting what spills over from the centre (needs width and height); stretch makes it exactly the box (needs width and height). Left out, contain. Only when op is resize. One of contain, cover, stretch. Default contain.
frames.ops[].upscale boolean Whether a picture smaller than the box is made larger. Left out, false: it keeps its size (cover then cuts it to the box). Only when op is resize. Default false.
frames.background string The colour, as #rrggbb, a picture is laid on for a format without transparency (JPEG, BMP, TIFF with JPEG compression). Left out, white. Matches ^#[0-9a-fA-F]{6}$. Default #ffffff.
folder string The folder to make the new folder in: a path such as /brand/2026/. Left out, the picture's own folder. 1 to 1,100 characters.
name string The new folder's name, without slashes. Left out, the picture's name without its extension, or Frames when it has none. At most 70 characters.

Response

201 Created. A JSON object:

Response fields (25)
NameTypeDescription
folder string The new folder's path, as stored; null when every frame was already kept, in which case no folder is made. Can be null.
format string The frames' format. One of png, jpeg, webp.
width number Each frame's width in pixels.
height number Each frame's height in pixels.
sourceFrames number Frames in the animation.
frames array of objects The frames taken, in order.
frames[].index number The frame's place in the animation, counted from 0.
frames[].delayMs number How long the animation shows it, in milliseconds.
frames[].asset object The asset the frame is kept as.
frames[].asset.id string The asset's id.
frames[].asset.kind string svg-original: an SVG file, kept as sent. image: a PNG, JPEG, GIF or WebP image, kept as uploaded. video: an MP4, QuickTime (.mov) or WebM video, kept as uploaded. A video is never placed as a picture. One of svg-original, image, video.
frames[].asset.contentType string The original's media type, read from its bytes: image/svg+xml, image/png, image/jpeg, image/gif, image/webp, video/mp4, video/quicktime or video/webm.
frames[].asset.filename string The name the library shows it by and the original downloads as. Empty when none was given.
frames[].asset.size number The original's size in bytes.
frames[].asset.sha256 string The SHA-256 of the original's bytes, in hex. The workspace keeps one asset for each distinct content.
frames[].asset.width number A picture's width as given when it was uploaded (stored as given, not read from the bytes), or a video's picture width read from the file. Null when not known. Can be null.
frames[].asset.height number A picture's height as given when it was uploaded (stored as given, not read from the bytes), or a video's picture height read from the file. Null when not known. Can be null.
frames[].asset.dpi number A picture's resolution as given when it was uploaded, or null. Stored as given, not read from the bytes. Null for a video. Can be null.
frames[].asset.durationMs number A video's length in milliseconds, read from the file. Null for a picture, and for a video whose file gives a length past a day or none a number can hold: it is kept, its length unknown. Can be null.
frames[].asset.folder string The media folder it is filed in: a path such as /brand/2026/, or / for the top level.
frames[].asset.hasPreview boolean Whether a rasterised preview is stored (assets.setPreview): an SVG's thumbnail or a video's poster frame, drawn by the client. A raster image serves itself as its preview either way (assets.preview).
frames[].asset.previewSize number The stored preview's size in bytes, or null when there is none. Can be null.
frames[].asset.createdBy string The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null.
frames[].asset.createdAt number When it was uploaded, in epoch milliseconds.
frames[].deduplicated boolean True when the workspace already kept these bytes, so the existing asset is returned where it is filed.

Example request

curl -X POST https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/frames \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "frames": {},
  "folder": "/catalogues"
}'
Example response
{
  "folder": "/catalogues",
  "format": "png",
  "width": 1,
  "height": 1,
  "sourceFrames": 1,
  "frames": [
    {
      "index": 1,
      "delayMs": 1,
      "asset": {
        "id": "string",
        "kind": "svg-original",
        "contentType": "string",
        "filename": "catalogue.pdf",
        "size": 1,
        "sha256": "string",
        "width": 1,
        "height": 1,
        "dpi": 1,
        "durationMs": 1,
        "folder": "/catalogues",
        "hasPreview": true,
        "previewSize": 1,
        "createdBy": "string",
        "createdAt": 1767225600000
      },
      "deduplicated": true
    }
  ]
}

Whether a picture is animated, and how

GET /assets/{assetId}/animation assets.animation

Read from the picture's bytes without decoding it, for an editor deciding whether to offer to keep an animation or take its frames out. convertible says whether it is within the conversion limits, and refusal why not. An SVG or a video answers 422 unsupported_image; an unknown or deleted asset 404 not_found; 410 gone when its file can no longer be read.

Scopes
documents.read

Path parameters

NameTypeDescription
assetId required string The asset's id: a PNG, JPEG, GIF or WebP picture. An id starting ast_.

Response

200 OK. A JSON object:

Response fields (9)
NameTypeDescription
contentType string The picture's media type, read from its bytes.
width number Its width as shown, in pixels (a JPEG's EXIF orientation applied).
height number Its height as shown, in pixels.
animated boolean Whether it has more than one frame.
frames number Its frames: 1 for a still.
loop number How many times it plays, 0 for ever; null for a still. Can be null.
durationMs number How long one play lasts, in milliseconds, as the file says; null for a still. Can be null.
convertible boolean Whether it is within the limits a conversion or a frame extraction takes.
refusal string Why it is not, as the conversion would say; null when it is. Can be null.

Example request

curl https://api.flipbird.io/api/v1/assets/ast_7m2kq9vx4c8d1r5t6wnb/animation \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "contentType": "string",
  "width": 1,
  "height": 1,
  "animated": true,
  "frames": 1,
  "loop": 1,
  "durationMs": 1,
  "convertible": true,
  "refusal": "string"
}

Errors

Besides the errors any endpoint can answer, these endpoints answer:

StatusCodeWhen
400empty_bodyThe upload has no bytes.
400length_mismatchA video's body is not as long as its Content-Length.
400invalid_filenameThe name is empty once cleaned.
400invalidA media folder path that is not one, or deleting /.
400invalid_folder_moveMoving /, moving a media folder into itself or a folder under it, or past 12 levels deep.
404no_previewAn SVG or a video with no stored preview.
409asset_in_useDocuments or galleries still use the asset. details lists them; send force=true to delete it anyway.
409preview_changedAnother preview was stored at the same moment.
409folder_existsMoving a media folder to a path that exists already: folders are not merged.
409folder_not_emptyDeleting a media folder with assets in or under it. details.assets counts them.
410goneThe stored file can no longer be read.
411length_requiredA video sent without a Content-Length.
413too_largePast the size for its type: an SVG 10 MiB, an image 25 MiB, a video 95 MiB.
415unsupported_assetThe bytes are not SVG, PNG, JPEG, GIF, WebP, MP4, QuickTime or WebM.
415malformed_svgThe SVG fails its safety checks.
415truncatedThe upload's structure does not hold: the file ends before its structure does (an upload or export cut short).
415trailing_dataThe upload's structure does not hold: bytes after an MP4's, MOV's or WebM's end that are not part of it (a picture's are kept).
415malformed_structureThe upload's structure does not hold: a box, chunk, segment or element whose header cannot be right.
415bad_checksumThe upload's structure does not hold: a PNG IHDR, PLTE, IDAT or IEND chunk whose CRC does not match.
415ftyp_not_firstThe upload's structure does not hold: an MP4 whose ftyp box is not its first.
415no_headerThe upload's structure does not hold: an MP4 or MOV with no moov box, or a WebM with no Segment or Info.
415duplicate_headerThe upload's structure does not hold: an MP4 or MOV with more than one moov box.
415no_media_dataThe upload's structure does not hold: no media data: an MP4 without mdat, a WebM without a Cluster, a picture without image data.
415no_durationThe upload's structure does not hold: a video that does not say how long it is.
415no_video_trackThe upload's structure does not hold: a file with no video track, such as audio only.
415no_video_sizeThe upload's structure does not hold: a video track with no picture size.
415not_webmThe upload's structure does not hold: a Matroska file whose DocType is not webm (an .mkv).
415index_too_largeThe upload's structure does not hold: an MP4 moov over 16 MB, or WebM Info or Tracks over 1 MB.
415unsupported_brandThe upload's structure does not hold: an ISO media file that is a HEIF or AVIF image rather than a video.
415unsupported_previewThe preview is not a PNG, JPEG or WebP.
422unknown_assetsSome of the ids are not live assets. details.missing lists them.
422not_picturesSome of the ids are videos, which a version cannot contain. details.videos lists them.