Media JS APIs

Media JS APIs

The fliplet-media package contains the following namespaces:


Get the list of folders and files for your organization or a specific app

// By default, this gets all top-level folders and files for the current app
Fliplet.Media.Folders.get().then(function (response) {
  // response.folders
  // response.files

// Get a list of all top-level folders and files for an organization by its ID
Fliplet.Media.Folders.get({ organizationId: 1 }).then(function (response) {});

// Get a list of all top-level folders and files for an app by its ID
Fliplet.Media.Folders.get({ appId: 2 }).then(function (response) {});

// Get a list of files and subfolders for a specific folder by its ID
Fliplet.Media.Folders.get({ folderId: 3 }).then(function (response) {});

Sample response for the above methods:

  "files": [
      "appId": null,
      "contentType": "image/jpeg",
      "createdAt": "2019-01-07T16:58:43.609Z",
      "id": 1,
      "isEncrypted": true,
      "mediaFolderId": null,
      "name": "Foo.jpg",
      "organizationId": 123,
      "path": "apps/1/2895a2611b753a74f2ae5097411579e4223-234-2632.jpg",
      "size": [ 640, 480 ],
      "metadata": {
        "size": 10438,
        "checksum": "29b5d83988d3d4c28af2109418674e20"
      "thumbnail": "https://path/to/thumbnail.jpg",
      "updatedAt": "2019-01-07T16:58:43.619Z",
      "url": "https://path/to/secure-file.jpg",
      "userId": 1
  "folders": [
      "appId": null,
      "createdAt": "2019-01-08T17:06:03.377Z",
      "deletedAt": null,
      "id": 1,
      "name": "My folder",
      "organizationId": 2,
      "parentId": null,
      "updatedAt": "2019-01-08T17:06:03.377Z"


  • parentId on a folder indicates whether this folder is a subfolder of another folder. If you want to query for all subfolders of a folder, provide the folderId parameter to the above JS APIs with the required ID.
  • size is an array with the width and height for images.
  • metadata is an object containing the file size in bytes and its md5 checksum.

Create a new folder

// Create a folder belonging to the current app
Fliplet.Media.Folders.create({ name: 'foo' }).then(function (folder) { });

Delete a folder

// Delete a folder given its id
Fliplet.Media.Folders.delete(1).then(function onComplete() { });

Rename a folder

Fliplet.Media.Folders.update(123, {
  name: 'Foo'

Move a folder

Fliplet.Media.Folders.update(123, {
  appId: 123,         // move to an app
  parentId: 456,      // move to a folder
  organizationId: 789 // move to the organization

Note: when moving a folder out from a subfolder (and to an app or organization), please set its parentId to null.


Upload one or more files

Files can be added using the standard HTML APIs for FormData.

Note: Fliplet scans all uploaded files for viruses. If a file is found to be infected the system will automatically quarantine it and not allow apps to download it. Quarantined files can be seen in the trash folder of the File Manager in Fliplet Studio.

  data: FormData,
  folderId: 1 // optional folderId
}).then(function (files) {


Please note that the following image content types are automatically resized to have both dimensions no larger than 3840px; when a resizing occurs, the scale of the image will be kept intact:

  • image/apng: Animated Portable Network Graphics (APNG)
  • image/avif: AV1 Image File Format (AVIF)
  • image/jpeg: Joint Photographic Expert Group image (JPEG / JPG)
  • image/png: Portable Network Graphics (PNG)
  • image/svg+xml: Scalable Vector Graphics (SVG)
  • image/webp: Web Picture format (WEBP)

Delete a file

// Delete a file given its id
Fliplet.Media.Files.delete(2).then(function onComplete() { });

Rename a file

Fliplet.Media.Files.update(123, {
  name: 'Foo'

Move a file

Fliplet.Media.Files.update(123, {
  appId: 123,         // move to an app
  mediaFolderId: 456, // move to a folder
  organizationId: 789 // move to the organization

Note: when moving a file from a folder to an app or organization, please set its mediaFolderId to null.

Search folders and files

Use the search() method fo find folders and files in your app or organization or a specific folder.

  • You can search by name
  • You can filter results by appId, organizationId or folderId
  • You can search for deleted files and folders by specifying deletedOnly as true
  • Results will include a type (folder or file)
  • Results will include app and organization properties with { id, name } when available
  • Results will include a parentFolder with { id, name } which recursively include any folder up to their app or organization folder
// search by file name{ name: 'foo' })

// search by app{ appId: 123 })

// search by organization{ organizationId: 456 })

// search by folder{ folderId: 789 })

// search for deleted files and folders only{ deletedOnly: true })

Sample response:

    "appId": null,
    "contentType": "image/jpeg",
    "createdAt": "2019-06-07T14:39:04.194Z",
    "dataSourceEntryId": null,
    "dataTrackingId": null,
    "deletedAt": null,
    "id": 267,
    "isEncrypted": true,
    "isOrganizationMedia": false,
    "masterMediaFileId": null,
    "mediaFolderId": 54,
    "name": "Foo bar.jpg",
    "organization": {
      "id": 11,
      "name": "Otro company"
    "organizationId": 11,
    "parentFolder": {
      "app": {
        "id": 147,
        "name": "Hello world"
      "id": 54,
      "name": "Subfolder in app",
      "parentFolder": {
        "app": {
          "id": 147,
          "name": "Hello world"
        "id": 53,
        "name": "Folder in app"
    "size": [ 4400, 2750 ],
    "thumbnail": "https://path/to/thumbnail/54/05bbf86878931661858c42441db0c2ce614-439-6054-t.jpg",
    "type": "file",
    "updatedAt": "2019-06-07T14:39:04.202Z",
    "url": "",
    "userId": 245


Authenticate encrypted files

Media files might require an auth token to be accessed if your organization has encryption enabled. We have a little helper available to do the heavy lifting for you, just pass any media file url or even a string with many URLs in it and they’ll get patched automatically:

// Authenticate a URL by passing the mediaFile URL
var authenticatedUrl = Fliplet.Media.authenticate(mediaFile.url);

// Authenticate all URLs found in a String
var authenticatedHtml = Fliplet.Media.authenticate('<img src="" />');

If you’re using Handlebars to print out your URLs, you can use our built-in auth helper:

<img src="{{{auth someFileUrl}}}" />

You can also create your own helper if you need more control:

Handlebars.registerHelper('addAuthentication', function(str) {
  return new Handlebars.SafeString(Fliplet.Media.authenticate(str));

And then use it in your directory templates like:

<img src="{{{addAuthentication someFileUrl}}}" />

<p>The authenticated URL is {{{addAuthentication someContent}}}</p>

Download files to devices

As per most or Fliplet JS APIs, all the following methods return a promise. There is experimental support on Chrome (for webapps) and full support is only available on native platforms (iOS and Android).

Get the list of files downloaded on the device, including files being downloaded

// Get an array of downloaded filed and files pending to be downloaded
Fliplet.Media.Files.Storage.get().then(function (files) {
  // Each file has status (downloaded or downloading), size, downloadedAt,
  // name and url (the original http(s) url used to download the file)

// Get downloaded files only

// Search for a downloaded file by url. "file" is undefined when not found
Fliplet.Media.Files.Storage.getDownloaded(url).then(function (file) {});

// Search for downloaded files by providing a filter identity sent to lodash "filter"
Fliplet.Media.Files.Storage.getDownloaded({ size: 100 }).then(function (files) {});

// Get downloading (pending) files only

Download a file

// Downloads a file (this gets added to a queue and will be downloaded in background);

// You can also add to the download queue an array of files[url1, url2, url3]);

Resume pending operations

// Call this in your screen JS after registering hooks

Return most appropriate URL to a file

Fliplet.Media.Files.Storage.resolve(url).then(function (fileUrl) {
  // fileUrl can be used to play an audio, display an image, etc

Get the raw FileEntry for a local file

// requires the fileName from any ""
Fliplet.Media.Files.Storage.getFile(fileName).then(function (file) {


Deletes one or more files

// Deletes a file. Requires the "" or "file.url"

// Deletes an array of files
Fliplet.Media.Files.Storage.delete([fileName1, fileName2, fileURL3])

// Deletes all files

Cancels one or more pending downloads

// Cancels the download a file. Requires the file URL

// Cancels the download of more files at once
Fliplet.Media.Files.Storage.cancelDownload([fileURL1, fileURL2, fileURL3])


Fliplet.Hooks.on('mediaFileDownloadCompleted', function (file) {

  // Resolve URL
  Fliplet.Media.Files.Storage.resolve(file).then(function (url) {
    // Add audio player
    $('body').append('<div data-title="Offline file" data-audio-url="' + url + '"></div>');

    // Init player so file can be played

Fliplet.Hooks.on('mediaFileDownloadFailed', function (error) {
 console.error('error downloading file', this, 'with error', error);

Fliplet.Hooks.on('mediaFileDownloadCanceled', function (fileData) {
 console.error('canceled a download', fileData);

Fliplet.Hooks.on('mediaFileDownloadProgress', function (file) {
 console.debug('progress', file.progress.loaded, 'of',;

Back to JS API documentation