Self-hosted Storage

This feature is available with the Plugin for Business plan and higher.

If you're on the Plugin for Startup or Plugin Expansion plan, consider upgrading to access this feature. For more details, visit our pricing page or contact support.

Self-hosted storage swaps the File Manager's API endpoints for your own, which keeps listing, uploads and deletions on your infrastructure while users keep the built-in File Manager interface.

If our integrated storage providers (Google Cloud Storage, Amazon S3, Cloudflare R2, DigitalOcean Spaces) don't meet your specific requirements, this is the way to connect your own.

WARNING

Before implementing the endpoints, check how to work with API endpoints.

How it works

By defining a set of custom backend endpoints, you can connect our File Manager UI directly to your infrastructure for:

• Listing files and folders
• Uploading images
• Creating new folders
• Deleting files or folders
• Saving edited images from the built-in image editor

All API responses must follow the expected structure to work correctly within the editor.

Authentication and shared params

The FOLDERS URL can include a {key} placeholder, which is replaced with the API key. Without the placeholder, the key is appended as a key query parameter instead, so plan for one or the other.

Listing carries hostname, userId and uuid; folder creation and deletion additionally carry id. userId and uuid always hold the same value, so either one can be used.

API endpoints

List Images & Folders

Used when File Manager opens. This call is used for retrieving files and folders.

• URL: /{API.FOLDERS}
• Method: GET
• Params: path, userId, uuid, hostname
• Content-Type: application/json

Response example:

[
  {
    "name": "filename.jpg",
    "date": "2024-12-01T14:23:00Z", // last-date-modified
    "size": "512000", // string
    "path": "/path/", // current directory path
    "type": "file", // "file" | "folder"
    "extension": ".jpg",
    "url": "https://url-to-image.com/image.jpeg"
},
{
    "name": "holiday-images",
    "path": "/",
    "type": "folder"
  }
]

A bare array is expected, though an { "items": [...] } envelope is accepted too.

name, type and path are required on every entry, for folders as well as files. url, size, extension and date are optional, and a value of the wrong type is dropped rather than failing the entry. size in particular has to be a string, so a numeric one disappears from the UI.

To support deletion by storage key, return an all object carrying OriginalKey. That value is what the editor sends back as key when the item is deleted.

Create New Folder

Used when user adds a new folder in the File Manager.

• URL: /{API.FOLDERS}
• Method: POST
• Content-Type: application/json

Body:

{
  "name": "new-folder",
  "path": "/"
}

Response:

HTTP 200 on success. The body is not read, so no particular shape is required.

Delete Images or Folders

Used when user deletes selected images or folders. We automatically append /delete to the FOLDERS API path.

• URL: /{API.FOLDERS}/delete
• Method: POST
• Content-Type: application/json

Body:

[
  {
    "name": "filename.jpg",
    "type": "file",
    "path": "/",
    "key": "storage-key-from-all-OriginalKey"
  },
  {
    "name": "old-folder",
    "type": "folder",
    "path": "/",
    "key": null
  }
]

key is present on every entry, for files and folders alike, and is null whenever the listing carried no all.OriginalKey.

Response:

HTTP 200 or 204 on success (no body required).

Image Upload

Used when user uploads a file via File Manager or when user drops an image onto an image block.

• URL: /{API.IMAGE_UPLOAD}
• Method: POST
• Content-Type: multipart/form-data

Body: three form fields.

field	value
image	The file itself, sent as a binary part with a filename
path	Target directory
uuid	User identifier

Response:

{
  "success": true,
  "name": "uploaded-image.jpg",
  "url": "https://your-domain.com/images/uploaded-image.jpg"
}

success has to be true, otherwise the editor treats the upload as incomplete. name becomes the file's canonical name in the File Manager, which lets you return a name adjusted for collisions or sanitization.

Upload Image from Image Editor

Used when user saves an image from the integrated image editor.

• URL: /{API.IMAGE_EDITOR_UPLOAD}
• Method: POST
• Content-Type: application/json

Request:

{
  "content": "data:image/png;base64,...", // full base64 data URL
  "filename": "edited-image.png"
}

Response:

{
  "url": "https://your-domain.com/images/edited-image.png"
}

Only url is read here, so no success flag is needed.