Welcome

Welcome to FileSpin Headless DAM API Documentation!

This documentation covers everything you need as a developer to:-

• Upload and manage Assets
• Create and manage Users
• Process Image and Video
• Request Dynamic Image Transformations
• Provide streaming video playback
• Use addons, manage Integrations
• and much more

Contact us

For developer support, email us at support@filespin.io, use the Help button on the Dashboard once you have logged-in or visit the Support site

DAM Basics

Within FileSpin, the following terms have specific and actionable meaning:-

What is an Asset

Within FileSpin an Asset is the main entity. It contains the file you want to manage and associated metadata.

A simple way to remember what an Asset is:

ASSET = CONTENT + METADATA

• CONTENT is:-
  • Original file and
  • One or more derivative content such as image conversions, video transcodes, etc
• METADATA is:-
  
  • Core metadata such as file size, image height/width, that cannot be updated by user, and
  • Custom metadata added by user

Who is a User

Access to FileSpin is through a User (a.k.a. User Account). A User Account provides login-based access to Web Dashboard and API-based access to headless DAM API.

What is a User Role

The User Role determines the actions a User Account can perform within FileSpin. Each User has a Role assigned.

FileSpin provides the following system-defined user roles:-

What are User Permissions

Permissions are string tokens that define what actions a user is allowed to perform. Permissions are determined by User Role as below.

What are User Groups

Users are grouped under the Administrator User who created the Users. Users within a User Group can access assets created by other users is they have Group Asset Access enabled.

Asset Access Security

Here's a quick rundown of how FileSpin implements secure access for Assets using Users, Roles, Permissions and Groups:-

• All access is either API key or JWT (see Authentication for details)
• Assets are owned by the User who created it
• What a User can do with an Asset is determined by the User's Role
• A User can access an asset only if atleast one of the below two conditions are met:-
  • if the User created the asset or
  • if the User has Group Asset Access setting enabled and one of their group members created the asset

Before you begin

Service endpoints

Our service endpoints are listed below. All our services are over https.

Code examples

The column on the right has code examples. When you are at a specific API within the documentation, checkout the side panel.

Asset ID and API Keys

A quick introduction to some of the IDs used within FileSpin service that you should be aware of.

Asset ID

This is a unique identifier for a file within our service. It is composed of 36 alphanumeric characters, like 678d1dbb934c4a42aa4833e893346857

When you integrate an application with FileSpin.io, most often this is the ID you would store within your application.

API KEY

This is the secret key that you will use to access FileSpin API. FileSpin will not disclose this to anyone except you. You should keep this well protected.

The API Key is unique to you. It is composed of 36 alphanumeric characters.

UPLOAD KEY

This is the Key for use in the File Picker for associating a file upload with your FileSpin account. The Upload Key is unique to you. It is composed of 36 alphanumeric characters.

UPLOAD KEY cannot be used anywhere except with File Picker to upload assets. It cannot be used to view or access uploaded assets.

Access ID

This is a unique ID associated with a user account. This may be required to retrieve signed URLs using certain APIs.

Asset Storage

Amazon S3

You may use FileSpin's storage or alternately use your own Amazon AWS S3 storage for storing assets and conversions.

If you are using your own S3 storage, please add the policy shown below to all the S3 Buckets you use in your FileSpin Storage settings. This policy allows FileSpin to store assets and processed files into your bucket.

FileSpin.io S3 Bucket Policy

• Replace YOUR-BUCKET below with your actual bucket name while applying the policy.
• YOUR-BUCKET must have ACLs enabled in Object Ownership settings. This allows FileSpin to assign object ownership to bucket owner.
• YOUR-BUCKET must have Block all public access setting turned OFF. If this is not done, Make Public API will fail to set public access.

{
  "Id": "FileSpinBucketPolicy",
  "Statement": [
    {
      "Sid": "Stmt1295042087538",
      "Effect": "Allow",
      "Principal": {
        "AWS": ["arn:aws:iam::103679559772:root"]
      },
      "Action": [
        "s3:GetObject",
        "s3:PutObjectAcl",
        "s3:ListMultipartUploadParts",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET/*"
    },
    {
      "Sid": "Stmt1295042087538",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::103679559772:root"
      },
      "Action": "s3:DeleteObject",
      "Resource": "arn:aws:s3:::YOUR-BUCKET/*"
    },
    {
      "Sid": "Stmt1295042087538",
      "Effect": "Allow",
      "Principal": {
        "AWS": ["arn:aws:iam::103679559772:root"]
      },
      "Action": [
        "s3:GetBucketAcl",
        "s3:ListBucket",
        "s3:ListBucketMultipartUploads",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET"
    }
  ]
}

File Picker Web Widget

FileSpin File Picker is a web widget for your users to upload files from their computer or pick files from their Cloud accounts and send it to your application.

Get started with File Picker

Start by including filespin.js just before the closing body tag in your HTML.

<script type="text/javascript"
src="https://js.filespin.io/embed/dist/filespin.min.js"></script>

Then, initialize Picker for use with the UPLOAD_KEY associated with the FileSpin account. You can get the UPLOAD_KEY from FileSpin Account Dashboard.

FileSpin.initPicker({
    uploadKey: "UPLOAD_KEY"
});

Example HTML

Here is a complete example that shows how to setup an "Upload Files" button on a web page

<body>
<!-- a button for user to start file uploads-->
<button id="upload">Upload Files </button>

<!-- Insert this just before the closing body tag -->
<script type="text/javascript"
src="https://js.filespin.io/embed/dist/filespin.min.js"></script>

<script>
  //initialize and open File Picker on button press
  document.getElementById('upload').addEventListener('click', function() {
    FileSpin.initPicker({
      uploadKey: "UPLOAD_KEY"
    });
  });
</script>
</body>

Picker Limitations

• Cloud Uploads is limited by Cloud provider's API limitations
• Picker does not support uploading entire cloud folders except for Dropbox
• Dropbox uploads require additional setup (see Dropbox Support below)
• Picker may not display more than 500 files (approx) in a cloud folder
• Display order of Cloud files is not guaranteed to be in any particular order

Picker API

Picker provides a rich set of APIs so you can control how the Picker works to suit your web application needs.

initPicker API

This API is the starting point for Picker. Use this to initialize the Picker. It uses sensible default options which can be overridden.

//Initialize the Picker. Replace UPLOAD_KEY with the correct key

FileSpin.initPicker({
  uploadKey: "UPLOAD_KEY",
});

initPicker API with callback on ready event

FileSpin.initPicker(settings, function() {}) API can be used to safely take actions only when the Picker is ready. You can pass a callback function as the second argument which will be called when the Picker is ready.

//Initialize the Picker with `display` set to `false`
//When Picker is ready, display an alert using the callback function.

FileSpin.initPicker(
  {
    uploadKey: "UPLOAD_KEY",
    display: false,
  },
  function () {
    //this function is called when picker is initialized and ready
    alert("Picker ready!");
    FileSpin.showPicker();
  }
);

showPicker API

Use this API to programmatically show the File Picker dialog. Using this in conjunction with hidePicker() API and display parameter of initPicker() API, you can realize advanced user interactions.

//Show Picker API
FileSpin.showPicker();

hidePicker API

Use this API to programmatically hide the File Picker dialog.

//Hide Picker API
FileSpin.hidePicker();

resetPicker API

If you need to return the user to file selection after an upload, use this API. Reset will not alter the Picker's initialization state. It is purely a UI reset.

//Reset Picker API
FileSpin.resetPicker();

minimizePicker API

Use this API to programmatically minimize Picker modal and place it at bottom-right of user window.

//Minimize Picker Modal
FileSpin.minimizePicker();

maximizePicker API

Use this API to programmatically maximize a minimized Picker modal.

//Maximize Picker Modal
FileSpin.maximizePicker();

delete API to delete uploaded files

Use this API to delete uploaded files in one upload session.

This API takes three parameters:-

1. Upload ID, a unique ID that is returned when you open the Upload dialog with FileSpin.initPicker() API
2. A list of Asset IDs - note that Asset ID is returned in the complete upload event
3. A callback function as a third parameter to handle API call success or error

Example code to delete a file that was uploaded

//Initialize Picker and get an uploadID
var uploadID = FileSpin.initPicker({
  uploadKey: "UPLOAD_KEY",
});

//setup Asset IDs list payload by listening to 'complete' event
//note that we are attempting to delete all the uploaded files here
// normally, this will not be the case
var file_ids;
FileSpin.on("complete", function (data) {
  file_ids = data.files.map(function (item) {
    return item.id;
  });
});

//trigger delete with a delete button click and call the 'delete' API
document.getElementById("delete-button").onclick = function (e) {
  FileSpin.delete(uploadID, file_ids, function (err, response) {
    if (err) {
      // delete failed
      // err will be "UPDATE_UNAUTHORIZED" or "UPDATE_FAILED"
    } else {
      // delete succeeded
    }
  });
  return false;
};

Picker configuration

The Picker can be initialized with the following parameters.

Only the uploadKey is mandatory, all other parameters are optional.

By default, the FileSpin widget will allow users to upload local device. Dropbox uploads require additional setup (see Dropbox Support below).

Dropbox Support

Please note that in order to use dropbox provider you must provide your own App Key and App Secret for OAuth2 flow. You can create an app and get the App Key and Secret from Dropbox App Console. After obtaining the details from Dropbox, you can specify the Dropbox App Key and Secret in your FileSpin Account Authorization Settings.

Picker configuration with all options

Here is a sample initPicker API with all available options set to their defaults (excluding Asset replace mode).

//Initialize Picker with all available options

FileSpin.initPicker({
  uploadKey: "UPLOAD_KEY",
  lang: "en", //Picker Dialog language - en, fr, de, es, zh, ja
  providers: ["local", "weburl", "flickr", "box", "onedrive", "googledrive"],
  maxFilesize: 5000,
  minFilesize: 0.01,
  maxFiles: 100,
  allowedTypes: ["jpg", "png", "gif", "mp4", "wav", "mp3"],
  css: { headerColor: "#fff", headerTextColor: "#000" },
  display: true,
  maximizeOnOpen: true,
  minimizeOnUpload: false,
  hideOnUpload: false,
  hideAfterUpload: false,
  autoUpload: false,
});

Picker Events

"start" event - JSON Sample

{
  "provider": "local",
  "files": [
    {
      "name": "sample.pdf",
      "size": 884888
    }
  ]
}

"complete" event - JSON Sample

{
  "provider": "local",
  "files": [
    {
      "id": "54dcbfbe2b124361a6ff4c62814789c7",
      "name": "sample.pdf",
      "size": 884888,
      "success": true,
      "message": "UPLOAD_SUCCESS"
    }
  ]
}

When users upload files using filespin.js, it will emit start and complete events detailed below:-

Listening to Picker Events

To listen for events, use the FileSpin.on API. You can listen to start, complete or all events using the special * event.

//listen to 'start' event
FileSpin.on("start", function (data) {
  console.log(data);
});

//listen to 'complete' event
FileSpin.on("complete", function (data) {
  console.log(data);
});

//listen to all events
FileSpin.on("*", function (data, eventName) {
  console.log(eventName, "triggered with data", data);
});

//Stop listening to 'complete' event
FileSpin.off("complete", myEventHandler);

Event data JSON format and samples

"complete" event - Upload success JSON Sample

{
  "provider": "local",
  "files": [
    {
      "id": "54dcbfbe2b124361a6ff4c62814789c7",
      "name": "sample.pdf",
      "size": 884888,
      "success": true,
      "message": "UPLOAD_SUCCESS"
    }
  ]
}

Upload events raised provide JSON formatted data. The data format is intentionally simple and the keys are as below:-

Event data samples for start event raised when upload starts and complete event raised when upload completes are shown in the code samples to the right.

Upload failures

"complete" event - Upload failed JSON Sample

{
  "provider": "local",
  "files": [
    {
      "id": null,
      "name": "sample.pdf",
      "size": 884888,
      "success": false,
      "message": "UPLOAD_FAILED"
    }
  ]
}

"complete" event - Upload unauthorized JSON Sample

{
  "provider": "local",
  "files": [
    {
      "id": null,
      "name": "sample.pdf",
      "size": 884888,
      "success": false,
      "message": "UPLOAD_UNAUTHORIZED"
    }
  ]
}

When uploads fail, it could be due to any of the following reasons:-

• File upload is not authorized for the website
• Picker was initialized with incorrect Upload Key
• Network or server error

For network or server error, "message" will be set to UPLOAD_FAILED. In both failure cases, "id" is null and "success" is false.

For unauthorized or incorrect upload key, message will be set to UPLOAD_UNAUTHORIZED.

Picker Replace mode

Using Picker's Asset replace mode you can replace a file that was uploaded earlier. In order to use this mode, you'll need:-

1. ID of the file you want to replace
2. uploadKey to initialize the Picker
3. serviceToken to open Picker in replacement mode

How to get the ServiceToken

serviceToken is a short-lived token that must be retrieved using a API call to FileSpin Service. Call the API by supplying your API_KEY and scope=EDIT_ASSET parameter. cURL example is shown below:-

curl -X "GET" \
"https://app.filespin.io/api/v1/authentication/service_token?scope=EDIT_ASSET" \
-H "X-FileSpin-Api-Key:API_KEY"

Using ServiceToken in Picker for replacing a file

The following code sample shows how to use ServiceToken to start a file replace.

FileSpin.initPicker({
  uploadKey: "UPLOAD_KEY",
  serviceToken: "SERVICE_TOKEN",
  fileToReplaceId: "REPLACEABLE_ASSET_ID",
});

Save form data

Sometimes you may wish to store additional data with files that users upload such as form data or custom JSON data. The FileSpin.update API allows you to easily do this. The API takes three parameters:-

1. Upload ID, a unique ID that is returned when you open the Upload dialog with FileSpin.initPicker() API
2. A dictionary object with Asset ID as key and JSON data as value - note that file ID is returned in the complete upload event
3. A callback function as a third parameter to handle API call success or error

Example that shows how to save some data with a file including searcheable keywords

//Initialize Picker and get an uploadID
var uploadID = FileSpin.initPicker({
  uploadKey: "UPLOAD_KEY",
});

//prepare JSON data you want to save with the file
//use "filespin_search_txt" to add searcheable keywords
var payload = {
  "Asset ID 1": {
    foo: "bar",
    filespin_search_txt: "sample search keywords",
  },
  "Asset ID 2": { foo: "bar" },
};

//Save the data
FileSpin.update(uploadID, payload, function (err) {
  if (err) {
    // data update failed
    // err will be "UPDATE_UNAUTHORIZED" or "UPDATE_FAILED"
  } else {
    // data storage succeeded
  }
});

If filespin_search_txt is present in the JSON data, it is treated as a special key whose value will be indexed for search using Search API.

You can update arbitrary data against all or any file id returned in the complete event. Simply pass the data against each file id you would like to be updated.

JSON Schema for Custom Data

FileSpin optionally supports JSON Schema for Asset Form Data. Assigning schema to asset data enables versatile field-based search and additional data validations.

Once Asset schemas have been setup for an account, you can pass the schema id __data_schema_id as shown below along with form data to automatically assign a schema to the asset data.

//pass "__data_schema_id" to assign a JSON Schema for the asset data

var payload = {
  "Asset ID 1": {
    fieldA: "value1",
    fieldB: "value2",
    "__data_schema_id": 1,
  },
  "Asset ID 2": {
    fieldA: "value11",
    fieldB: "value22",
    __data_schema_id: 1,
  },
};

Note that __data_schema_id is a reserved key to indicate the schema to be used and will not be stored as part of the form data.

Showing a thumbnail after upload

To display a thumbnail of the uploaded file immediately within your web page, use the On-demand Image URL:-

<img
  src="https://cdn.filespin.io/api/v1/assets/{ASSET_ID}/conversions?resize=WIDTH,HEIGHT"
/>

Replace {ASSET_ID} with the actual file ID and set the resize WIDTH, HEIGHT parameters.

An example on-demand URL would look like below:-

<img
  src="https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=180,180"
/>

Internationalization (i18n) of Picker

The following languages are supported out-of-the-box by File Picker UI.

The Picker will detect the browser's language and will set the language automatically with English as the default fallback. This behavior can be overridden by passing the lang parameter to the initPicker API.

Opening Picker in a specific language

To open Picker in a specific language, use lang parameter.

FileSpin.initPicker({
  uploadKey: "UPLOAD_KEY",
  lang: "zh", //sets chinese language for the interface
});

Web Connector Widget

FileSpin Connector simplifies integration of FileSpin.io with your web application so that users can search and use images, videos and documents hosted in FileSpin.io from right within your application.

With FileSpin Connector, users can:-

1. Search for files using image annotation search. For example, they can search for all images that contain, say, Eiffel tower
2. Find files using advanced search with various parameters such as file name, size, etc
3. Preview images and videos
4. Select files for use within your application, such as embedding thumbnails and videos
5. Dynamically create secure File Distributions that can be used within your application

Get started with FileSpin Connector

Start by including filespin.js just before the closing body tag in your HTML.

<script type="text/javascript"
src="https://js.filespin.io/embed/dist/filespin.min.js"></script>

Then, initialize Connector with Service Token. For obtaining a ServiceToken, see below Get Service Token section.

FileSpin.initConnector({
  serviceToken: "INSERT_YOUR_SERVICE_TOKEN",
});

How to get the ServiceToken

serviceToken is a short-lived token that must be retrieved using a API call to FileSpin.io Service. Call the API by supplying your API_KEY and scope=READ_ASSET. cURL example is shown below:-

curl -X "GET" \
"https://app.filespin.io/api/v1/authentication/service_token?scope=READ_ASSET" \
-H "X-FileSpin-Api-Key:API_KEY"

The following code sample shows how to use ServiceToken to initialize the connector.

FileSpin.initConnector({
  serviceToken: "INSERT_YOUR_SERVICE_TOKEN",
});

Connector configuration

The Connector specific options are listed below. serviceToken is mandatory. All other parameters are optional.

Connector dialog title in multiple languages

Supply custom dialog title in multiple languages like below:-

{
  "en": "Dialog title english",
  "fr": "Dialog title french"
}

Title will be set based on user browser's language or based on lang parameter. Default fallback is english title FileSpin Connector.

Connector with all options

Here is a code sample that initializes the Connector with all available options set to their defaults.

FileSpin.initConnector({
  serviceToken: "INSERT_YOUR_SERVICE_TOKEN",
  lang: "en", //Connector Dialog language - en, fr, de, es, zh, ja
  maxSelection: 30,
  hideOnMaxSelect: false,
  dialogTitle: {
    en: "FileSpin Connector",
  },
});

Connector - User File Selection

Users can select files listed in the Connector by clicking on the thumbnail.

Each file selected by user triggers a connector-file-selected event. By listening to this event, you can receive the selected file's details and take action within your application (such as adding selected files to user's basket within your application).

For more details about events, see Connector Events.

Connector API

Connector provides a rich set of APIs so you can control how it works to suit your web application needs.

initConnector

This API is the starting point for Connector. Use this to initialize the Connector. It uses sensible default options which can be overridden.

initConnector with default options

Initialze Connector with default options. serviceToken is a mandatory parameter.

FileSpin.initConnector({
  serviceToken: "INSERT_YOUR_SERVICE_TOKEN",
});

initConnector with callback on ready

FileSpin.initConnector(settings, function() {}) API can be used to safely take actions only when the Connector is ready. You can pass a callback function as the second argument which will be called when the Connector is ready.

Below code initializes the Connector, and using the callback function when the Connector is ready, it displays an alert and shows the Connector.

FileSpin.initConnector(
  {
    serviceToken: "INSERT_YOUR_SERVICE_TOKEN",
  },
  function () {
    //this function is called when Connector is initialized and ready
    alert("Connector ready!");
  }
);

showConnector

Use this API to programmatically show the Connector dialog.

FileSpin.showConnector();

hideConnector

Use this API to programmatically hide the Connector dialog.

FileSpin.hideConnector();

resetConnector

This API resets the Connector by clearing current search and any file selections. It does not change the initialization parameters.

FileSpin.resetConnector();

updateConnectorSettings

Convenience method to update Connector with the new settings without reloading it.

FileSpin.updateConnectorSettings(connectorSettings);

connectorSettings are the same as for initConnector API as defined in Connector configuration above.

Here is a sample connectorSettings:-

FileSpin.updateConnectorSettings({
  serviceToken: "INSERT_YOUR_SERVICE_TOKEN",
  lang: "en",
  maxSelection: 30,
  hideOnMaxSelect: false,
  dialogTitle: {
    en: "FileSpin Connector",
  },
});

Connector Events

When users select and deselect files or create File Distributions, filespin.js will emit events as detailed below:-

Listening to Connector Events

To listen to events, use the FileSpin.on API. You can listen to a specific event or all events using the special * event.

//listen to 'connector-file-selected' event
FileSpin.on("connector-file-selected", function (data) {
  console.log(data);

  //Perhaps, hide the Connector once a file is selected
  FileSpin.hideConnector();
});

//listen to all events
FileSpin.on("*", function (data, eventName) {
  console.log(eventName, "triggered with data", data);
});

Connector Event Data

The events provide file data in the following formats:-

Internationalization (i18n) of Connector

The following languages are supported out-of-the-box by File Connector:-

The Connector will detect the browser's language and will set the language automatically with English as the default fallback. This behavior can be overridden by passing the lang parameter to the initConnector API.

Opening Connector in a specific language

To open Connector in a specific language, use lang parameter.

FileSpin.initConnector({
  serviceToken: "INSERT_YOUR_SERVICE_TOKEN",
  lang: "zh", //sets chinese language for the interface
});

Image Transformations

FileSpin provides two ways to transform and display images:-

• On-demand Image Transformation that can be requested with dynamic URL parameters. These are image transformations are generated and supplied on-the-fly and do not use any storage quota. For example, when you request a 300x300 resize of an image asset via a URL such as https://cdn.filespin.io/api/v1/assets//conversions?resize=300,300 , the resize transformation is generated on-demand and delivered instantly).
• Static Image Conversion which are presets configured in an account to be generated and stored in storage before they can be requested

On-demand Image Transformations

Get started with on-demand images

Use the Asset ID and request a image transformation like below:-

https://cdn.filespin.io/api/v1/assets/{ASSET_ID}/conversions?resize=200,200

Where resize=200,200 requests a resized image of width 200px and height 200px.

By default, the returned images will be webp or avif format for supported browsers with JPG as fallback format. This can be changed using the format option.

Here is a sample on-demand image request URL used in a img tag:-

<img
  src="https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=200,200"
/>

The following sections describe all the image transformations supported.

ODI Limitations

• On-demand image (ODI) is available for assets after they are processed. Availability of ODI for an asset is indicated with the ON_DEMAND_IMAGE key in addons_info. See Asset Data Format for more info.
• For large images and cloud files, FileSpin would return a low-resolution image if ODI is requested immediately after upload. A short expiration time will be returned in HTTP response header in this case. The ODI URL will be updated with a high-resolution image after the file is processed.

resize

Request a resized image that fits in a rectangle of given width and height without changing the aspect ratio.

The transformation parameters are described below:-

crop

Get a cropped region from the original image, with optional face detection.

The transformation parameters are described below:-

watermark

Watermarked image transformations can be done in two ways:-

1. Providing dynamic watermark options such as watermark image, placement, etc as URL parameters
2. Using the pre-defined watermark options already setup in the user's account settings

Watermark option can be combined with all other transformation options such as resize, crop, etc.

Using dynamic watermark options

watermark={watermark_image},{x},{y}{opacity},{width_scale},{height_scale}

Generate a watermarked image transformation by providing all the watermark options as URL parameters. This method allows you to apply different watermarks for the same image depending on the use case.

Examples

The complete URL would look like:- https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=1200,1200&watermark=https://app.filespin.io/static/img/logo.png,-0,-0

watermark=https://app.filespin.io/static/img/logo.png,-0,-0,0

Uses FileSpin logo as watermark and places it to the bottom right of the image. Watermark image is used with the original size. Note tha use of -0,-0 to place the watermark at the bottom right of the image.

The complete URL would look like:- https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=1200,1200&watermark=https://app.filespin.io/static/img/logo.png,-0,0,0,40,40

watermark=https://app.filespin.io/static/img/logo.png,-0,0,0,40,40

Uses FileSpin logo as watermark and places it to the right top of the image. Watermark takes 40% of the image's width and height and opacity is 0 for fully opaque.

The complete URL would look like:- https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=1200,1200&watermark=https://app.filespin.io/static/img/logo.png,repeat,-0,0,40,40

watermark=https://app.filespin.io/static/img/logo.png,repeat,-0,0,40,40

Uses FileSpin logo as watermark and repeats it horizontally at the bottom. Watermark takes 40% of the image's width and height.

Using User's default watermark

The complete URL would look like:- https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=1200,1200&watermark=https://app.filespin.io/api/v1/user/watermark/{USER_ID},0,0,0

watermark=https://app.filespin.io/api/v1/user/watermark/{USER_ID},0,0,0

Where {USER_ID} should be replaced with the user's ID. Note that https://app.filespin.io/api/v1/user/watermark/{USER_ID} is accessible publicly.

This option applies the watermark setup in the user's account settings.

background color

Fill transparent parts of a PNG image with a specified color. This is useful when you want fill an image that has transparent background with a specific color dynamically to match the web page style (such as in retail product image pages).

Example

Consider this original PNG image with transparent background. As it has transparent background, you see the page color as the background color.

Below are some transformations with bgcolor that fills the background transparency with a specified color.

Transformation	Examples	Description
bgcolor=f00000		request a image with red background
bgcolor=008080		request a image with teal background

The transformation parameters are described below:-

quality

Specify the quality of the returned image (a value from 1 to 100). If not specified, default quality of 90 is applied. Quality determines the returned file size in bytes. Lower quality will yield smaller file size and hence faster page loads.

The transformation parameters are described below:-

format

Specify the format of the returned image. If not specified, format is implicitly set to avif or webp for supported browsers with JPG as fallback format.

The transformation parameters are described below:-

trim

Trim removes the same color pixels from the edges of the image. This is useful when you want to remove the white space around an image.

The transformation parameters are described below:-

rotate

Rotate the image anti-clockwise by an angle.

Transformation	Examples	Description
rotate=angle	rotate=90&resize=100,100	request a image rotated 90 degrees anti-clockwise
rotate=angle&resize=width,height	rotate=180&resize=100,100	request a 180 degress rotated resized image

The transformation parameters are described below:-

flip

Flip an image left to right (horizontal) or top to bottom (vertical).

Transformation	Examples	Description
flip=type	flip=v&resize=100,100	request a image flipped vertically
flip=type&resize=width,height	flip=h&resize=100,100	request a image flipped horizontally and resized

The transformation parameters are described below:-

Effects

Effects are transformations applied after all other conversion options such as width, height, etc are applied.

grayscale

Request a grayscale image

Transformation	Example	Description
effects=grayscale		request a grayscale image
effects=grayscale&resize=200,200		request resized grayscale image

blur

Request a blurred image

Transformation	Example	Description
effects=blur&resize=100,100		request a blurred image with default blur value of 20
effects=blur:5&resize=200,200		request resized blurred image with blur value of 5

roundcorner

Request a image with round corner

Transformation	Example	Description
effects=roundcorner&resize=100,100		request a roundcorner image
effects=roundcorner:50:128:128:128&resize=100,100		request roundcorner resized image with a radius of 50 and gray background behind rounded corner

Multiple effects

Combine multiple effects

Transformation	Example	Description
effects=grayscale,roundcorner:30&resize=200,200		request grayscale roundcorner resized image
effects=blur:5,roundcorner&resize=200,200		request roundcorner blurred resized image

Signed URL for image transformations

Signed URL with php

<?php
$api_key = '0c3c6d026858460abc4de1dcb4de15ac'
$string_to_sign = '0c3c6d026858460abc4de1dcb4de15ac?resize=300,300&expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT'
$signature = urlencode(base64_encode(hash_hmac('sha1', $string_to_sign, $api_key, true)));
$signed_url = 'https://cdn.filespin.io/api/v1/conversions/'.$string_to_sign.'&signature='.$signature
?>

Signed URL with python

import base64, hmac, hashlib, urllib
from six import text_type, b

API_KEY = '0c3c6d026858460abc4de1dcb4de15ac'
string_to_sign = '0c3c6d026858460abc4de1dcb4de15ac?resize=300,300&expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT'
signature = urllib.quote_plus(base64.urlsafe_b64encode(hmac.new(b(API_KEY), text_type(string_to_sign).encode('utf-8'), hashlib.sha1).digest()))
signed_url = '%s%s&signature=%s' % ('https://cdn.filespin.io/api/v1/conversions/',string_to_sign,signature)

Signed URL with java

import java.security.SignatureException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

String api_key = "0c3c6d026858460abc4de1dcb4de15ac";
String string_to_sign = "0c3c6d026858460abc4de1dcb4de15ac?resize=300,300&expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT";
SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), "HmacSHA1");
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(api_key);
byte[] hmac = mac.doFinal(string_to_sign.getBytes());
String signature = Encoding.EncodeBase64(hmac);
String signed_url = "https://cdn.filespin.io/api/v1/conversions/" + string_to_sign + "&signature=" + signature;

If Secure On-demand Images option is enabled in your settings, then you must use signed URLs for on-demand images.

Steps to generate signed URL

Besides the File Id and size parameters, you'll need the below:-

Signing a image URL is done by setting an expiry and signing the URL using your FileSpin API_KEY and Access Id. The signing process is as below:-

1. Take the URL part staring with the ASSET_ID, excluding the signature part, like 0c3c6d026858460abc4de1dcb4de15ac?resize=300,300&expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT, where expiry is seconds since Epoch time
2. Using your API Key, Access Id and the above URL part as the string-to-sign, calculate the HMAC signature
3. Encode the signature to a base64 string, then URL encode the resulting string and append it to the URL as signature query parameter value

Example signed image URL

https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=300,300&expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT&signature=vsR0_NFfeLEJPc8MXWMh2xI2Qvg%3D

Downloadable URL for image transformations

These options allow you to set additional URL parameters that sets Content-Disposition HTTP headers such that when user accesses the URL via a browser, the image transformation downloads to their device as a file with appropriate extension.

The parameters are described below:-

Example downloadable image URL

The URL below will download a 300x300 image transformation called testimage.jpg to user's device.

https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=300,300&delivery=download&dl_prefix=testimage&format=jpg

Static Image Conversions

Static Image Conversions are image sizes that are pre-generated and stored in cloud storage before they can be delivered. Usually, these are image transformations that cannot be done on-demand (for example, Zoomable image conversion).

Static Image Conversions can be setup within an account's Image Settings page to be generated automatically on image uploads. They can also be done via /process API call. See Asset Processing API section on how to use the /process API.

Requesting a static image conversion for display

To request a static image conversion, use the same URL as the On-demand image with the static image conversion name appended, like

/api/v1/assets/{ASSET_ID}/conversions/{conversion_name}?resize=300,300

where, conversion_name is the custom name specified for the static conversion in your Image Settings.

For example, if the account has a static image conversion called black_and_white, this can be requested via:

https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions/black_and_white

A 300x300 resized static conversion can be requested via:

https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions/black_and_white?resize=300,300

Requesting a non-public static image conversion

If a static image conversion is not public, the request must be authenticated. This can be done in two ways:-

• by passing X-FileSpin-Api-Key:{API_KEY} if the request is made from a server-side application (see Authentication)
• by passing Authorization: Bearer {JWT} header in the request if the request is made from a client-side application (see JWT Authentication)
• by signing the request URL. A signed URL can be generated using the same method detailed for On-demand Image Conversion. Please see Signed URL for image transformations.

Video Transcoding & Streaming

FileSpin provide extensive video transcoding capabilities to process many video input formats into standard output formats suitable for various devices.

Following outputs are supported:-

• Low-resolution video (360p)
• Standard Definition (480p)
• High Definition (720p)
• Full-HD (1080p)
• Ultra-HD (4k)
• Adaptive Bitrate Streams (HLS)

In addition to above, FileSpin supports:-

• Video Previews with SD, HD, UHD presets
• Video watermarking for all outputs
• Clip Creation API for creating video clips
• Video Storyboard Addon and other video addons such as ML-based video subtitles
• Global video CDN for delivery of videos

Transcoding a video

FileSpin provides a number of ways to transcode videos:-

• Enable trancodes in account's video settings to generate transcodes when videos are uploaded
• Request a transcode to be generated via /process API at any time after a video is ingested (see Video Transcoding API under Asset Processing API section for more details)
• Clip creation API to create clips of specified video segments. Please see Video Clip Creation API under Asset Processing API section for more details.

Streaming a Video

Example Video stream URL

https://cdn.filespin.io/api/v1/assets/f99255d2bf8142b29561641491e9940c/transcodes/480p-video.mp4

Example Video Thumbnail/Poster Image URL

https://cdn.filespin.io/api/v1/assets/f99255d2bf8142b29561641491e9940c/conversions?resize=800,600

Video transcodes are stored in cloud storage and can be requested via FileSpin CDN for global playback with ultra-low latency. Video Stream URL for playback takes the below format:-

Video Stream URL

https://cdn.filespin.io/api/v1/assets/{ASSET_ID}/transcodes/{TRANSCODE_KEY}

Poster image URL

https://cdn.filespin.io/api/v1/assets/{ASSET_ID}/conversions?resize={width},{height}

Note: Poster image is supplied as On-demand image. All On-demand Image conversions can be applied to this image.

Embedding Video in a Web page

Displaying a video in a webpage is as simple as providing the correct URLs.

<video
  src="https://cdn.filespin.io/api/v1/assets/f99255d2bf8142b29561641491e9940c/transcodes/480p-video.mp4"
  type="video/mp4"
  poster="https://cdn.filespin.io/api/v1/assets/f99255d2bf8142b29561641491e9940c/conversions?resize=800,600"
  width="800"
></video>

HLS Video playback

Displaying a HLS video requires you to provide a stream info file.

To stream video in HTTP Live Streaming (HLS) format, the video URL must be provided as below:

HLS Video URL

https://cdn.filespin.io/api/v1/assets/{ASSET_ID}/transcodes/playlist.m3u8

FileSpin dynamically generates and supplies playlist.m3u8 if HLS streams have been generated for a video.

Signed URL for video transcodes

Code example in php

<?php
$api_key = '678d1dbb934c4a42aa4833e893346857'
$string_to_sign = 'f99255d2bf8142b29561641491e9940c/transcodes/480p-video.mp4?expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT'
$signature = urlencode(base64_encode(hash_hmac('sha1', $string_to_sign, $api_key, true)));
$signed_url = 'https://cdn.filespin.io/api/v1/assets/'.$string_to_sign.'&signature='.$signature

Code example in python

import base64, hmac, hashlib, urllib
from six import text_type, b

API_KEY = '678d1dbb934c4a42aa4833e893346857'
string_to_sign = 'f99255d2bf8142b29561641491e9940c/transcodes/480p-video.mp4?expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT'
signature = urllib.quote_plus(base64.urlsafe_b64encode(hmac.new(b(API_KEY), text_type(string_to_sign).encode('utf-8'), hashlib.sha1).digest()))
signed_url = '%s%s&signature=%s' % ('https://cdn.filespin.io/api/v1/assets/',string_to_sign,signature)

Code example in java

import java.security.SignatureException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

String api_key = "678d1dbb934c4a42aa4833e893346857";
String string_to_sign = "f99255d2bf8142b29561641491e9940c/transcodes/480p-video.mp4?expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT";
SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), "HmacSHA1");
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(api_key);
byte[] hmac = mac.doFinal(string_to_sign.getBytes());
String signature = Encoding.EncodeBase64(hmac);
String signed_url = "https://cdn.filespin.io/api/v1/assets/" + string_to_sign + "&signature=" + signature;

In order to use a signed URL that provides URL expiry and security, you must generate the URL by setting an expiry and signing the URL using your FileSpin API_KEY and Access Id.

Besides the File Id and the transcode type (such as 480p-video.mp4), you'll need the below:-

The signing process is as below (see code samples to the right):-

1. Take the URL part staring with the FILE_ID and add an expiry in seconds since Epoch time and your Access Id, like 678d1dbb934c4a42aa4833e893346857/transcodes/480p-video.mp4?expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT
2. Using your API Key and the above URL part as the string-to-sign, calculate the HMAC signature
3. Encode the signature to a base64 string and append as signature query parameter value

Example of a signed video URL

https://cdn.filespin.io/api/v1/assets/f99255d2bf8142b29561641491e9940c/transcodes/480p-video.mp4?expiry=1452894790&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT&signature=vsR0_NFfeLEJPc8MXWMh2xI2Qvg%3D

Downloadable URL for video transcodes

These options allow you to set additional URL parameters that sets Content-Disposition HTTP header such that when user accesses the URL via a browser, the video transcode downloads to their device as a file.

The parameters are described below:-

Example downloadable video URL

The URL below will downloads the 480p watermarked video transcode called testvideo.mp4 to user's device.

https://cdn.filespin.io/api/v1/assets/f99255d2bf8142b29561641491e9940c/transcodes/480p-wm-video.mp4?delivery=download&dl_prefix=testvideo

API Overview

FileSpin exposes all its features via a comprehensive API. Use this API to manage Assets, Users, Asset Collections, Addons, etc.

Authentication

FileSpin API calls require a valid API Key or Authorization HTTP Header.

Using API Key

Replace {API_KEY} with your API Key

curl -H "X-FileSpin-Api-Key:{API_KEY}"

Send API request with API key in request header like:-

X-FileSpin-Api-Key:{API_KEY}

Where {API_KEY} should be replaced with your API Key

Using JSON Web Token (JWT)

Replace {JWT} with the token from Login API response

curl -H "Authorization: Bearer {JWT}"

JSON Web Token (JWT) is an open standard (RFC 7519) for secure communication. You can use FileSpin JWT to create rich Web applications such as such as reactjs apps that run inside the web browser. The entire FileSpin API is available for use opening up the possibility to create custom web interfaces that suit your business needs.

Send API request with JWT in request header like:-

Authorization: Bearer {JWT}

Where {JWT} should be replaced with the token obtained via /login API.

Web Application Login & JWT

Web applications should use this API to retrieve JWT and user profile.

Login and obtain JWT and User profile

curl -X "POST" -H "Content-Type: application/json" \
-d '{  "email": "user@example.org",
   "password": "PASSWORD"
}' https://app.filespin.io/api/v1/login

HTTP REQUEST

POST https://app.filespin.io/api/v1/login

HTTP HEADER

None

API PARAMETERS

API RESPONSE

A JSON with JWT and other user details.

Response with JWT

{
  "user_id": 42,
  "user_email": "user@example.org",
  "username": "John Doe",
  "jwt": "JWT",
  "role_id": 1,
  "role_name": "ADMIN",
  "uploadkey": "ec5139a372f6478d97365ec0df9c9a814",
  "notifications": ["Notification message 1"]
}

API Response Codes

API calls return the following HTTP response codes:

Asset API

FileSpin exposes all its features via a comprehensive API. Use this API to manage Assets, Users, Asset Collections, Addons, etc.

Asset Data Format

FileSpin returns Asset data in a standard JSON format as below for all Asset API calls. In addition, data posted to your Webhooks will also be of this format.

Asset Data JSON Format - Example

{
  "id": "99d819953914402babbdeb68337ea6a3",
  "status": "OK",
  "name": "sample.mov",
  "size": 8836363,
  "checksum": "5f5f26bd7c0f62c6e02e44c73d09734e",
  "provider": "local",
  "storage_type": "AMAZON_S3",
  "bucket": "filespin-labs",
  "key": "/99d819953914402babbdeb68337ea6a3/sample.jpg",
  "public": false,
  "content_type": "video/quicktime",
  "creator_id": 272,
  "upload_time": "2015-07-02T08:12:56Z",
  "update_user_id": 272,
  "update_time": "2015-07-02T08:12:56Z",
  "upload_source": "upload.example.com",
  "data_schema_id": 1,
  "metadata": {
    "width": 1200,
    "height": 800,
    "duration": 30
  },
  "data": {
    "foo": "bar"
  },
  "conversions": {
    "720p-video": {
      "storage_type": "s3",
      "bucket": "filespin-labs",
      "key": "/99d819953914402babbdeb68337ea6a3/720p-video.mp4",
      "width": 1280,
      "height": 720,
      "duration": 30,
      "size": 716000,
      "public": true,
      "watermarked": false
    },
    "hls-video": {
      "storage_type": "s3",
      "bucket": "filespin-labs",
      "key": "/99d819953914402babbdeb68337ea6a3/hls/playlist.m3u8",
      "width": 1280,
      "height": 720,
      "duration": 30,
      "size": 716000,
      "public": true,
      "watermarked": false
    }
  },
  "addons_info": {
    "ON_DEMAND_IMAGE": {
      "available": true
    }
  }
}

JSON Parameters

Asset Upload

Upload a single file and receive asset id (sample.jpg file should be present in the folder where the program is invoked)

curl -H "X-FileSpin-Api-Key:API_KEY" \
-X "POST" -F "file=@sample.jpg" \
https://app.filespin.io/api/v1/assets/new/content/original/upload

Upload multiple files in a single request (use file1, file2, file3, etc. as field names. Each file will result in a new asset being created)

curl -H "X-FileSpin-Api-Key:API_KEY" \
        -X "POST" \
        -F "file1=@sample1.jpg" \
        -F "file2=@sample2.jpg" \
        -F "file3=@sample3.jpg" \
        /api/v1/assets/new/content/original/upload

Use this API to upload one or more files and create assets within FileSpin. Once asset has been created, custom metadata can be added to the asset using Asset Update Data API.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/new/content/original/upload (multipart/form-data)

Note:

• To upload a single file, use file as multipart-form field name for file.
• To upload multiple files in a single request, use file1, file2, file3, etc. as multipart-form field names for files.
• Each uploaded file will result in a new asset being created.
• file , file1, file2, file3, etc. are conventional names for multipart-form field names. You can use any name for the field names.

HTTP RESPONSE

Standard HTTP Status Code (200 or 202) and a JSON response like the one shown in the code sample to the right.

Response JSON - Example

{
  "files": [
    {
      "id": "99d819953914402babbdeb68337ea6a3",
      "name": "sample.jpg",
      "size": 8836363,
      "checksum": "5f5f26bd7c0f62c6e02e44c73d09734e",
      "content_type": "image/jpeg",
      "metadata": {
        "Make": "Apple",
        "ColorSpace": "sRGB",
        "Model": "iPhone 3G",
        "Orientation": "Horizontal (normal)",
        "width": 1200,
        "height": 800
      }
    }
  ],
  "success": true,
  "provider": "local"
}

Asset Ingest from URI

Use of this API to request FileSpin to retrieve a file from external HTTP URL or a S3 Bucket and create an asset.

Note

• If S3 source is provided, the S3 Bucket must have S3 Access policy to authorize FileSpin access (see Asset Storage section for policy details)
• If HTTP URL is provided, the URL must supply downloadable content and should not require authentication. Downloads from external websites will be rate-limited.

HTTP REQUEST

cURL sample request

curl -X "POST" "https://app.filespin.io/api/v1/assets/new/content/original/external" \
     -H "X-FileSpin-Api-Key: 0de9d8e207974dc7b29c76372890e4ca" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
  "name": "test.jpg",
  "key": "s3://my-bucket/test.jpg"
    }'

Using your API Key send a request as below:-

HTTP POST https://app.filespin.io/api/v1/assets/new/content/original/external

The request body should contain a JSON with name and key.

{
  "name": "test.jpg",
  "key": "https://example.com/test.jpg"
}

Example request JSON payload

Request to pull a S3 file

{
  "name": "test.jpg",
  "key": "s3://my-bucket/test.jpg"
}

Request to pull a file from a https URL

{
  "name": "test.jpg",
  "key": "https://example.com/test.jpg"
}

HTTP RESPONSE

Standard HTTP Status code (202 or 200) and a JSON response like the one shown in the code sample to the right.

Response JSON - Example

{
  "id": "ceace459cd2a4d2c904e38e9ab352ebb",
  "status": "QUEUED",
  "message": "Queued for processing"
}

Asset Replace

Replace API_KEY with your API Key. sample.jpg file should be present in the folder where the program is invoked

curl -H "X-FileSpin-Api-Key:API_KEY" \
-X "POST" -F "file=@sample.jpg" \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/original/replace

API to replace the original content file of an asset while keeping the Asset ID unchanged.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/original/replace (multipart/form-data)

HTTP RESPONSE

HTTP Status code and JSON response like the one shown in the code sample to the right.

Response JSON - Example

{
  "files": [
    {
      "id": "99d819953914402babbdeb68337ea6a3",
      "name": "sample.jpg",
      "size": 8836363,
      "checksum": "5f5f26bd7c0f62c6e02e44c73d09734e",
      "content_type": "image/jpeg",
      "metadata": {
        "Make": "Apple",
        "ColorSpace": "sRGB",
        "Model": "iPhone 3G",
        "Orientation": "Horizontal (normal)",
        "width": 1200,
        "height": 800
      }
    }
  ],
  "success": true,
  "provider": "local"
}

Asset Add Conversion

Replace API_KEY with your API Key. my_edited_copy.jpg file should be present in the folder where the program is invoked

curl -H "X-FileSpin-Api-Key:API_KEY" \
-X "POST" -F "file=@my_edited_copy.jpg" \
https://app.filespin.io/api/v1/assets/99d819953914402babbdeb68337ea6a3/content/my_edited_copy

Use this API to upload and add a custom conversion file to an asset (such a manually edited copy of an image). The uploaded file will be stored as an asset's conversion in the Cloud Storage.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/{CONVERSION_NAME} (multipart/form-data)

HTTP RESPONSE

Standard HTTP Status code - 202 or 200

Asset Get Conversion

Asset conversions can be retrieved:-

As Static Image Conversion URL

Use the URL https://app.filespin.io/api/v1/assets/{ASSET_ID}/conversions/{conversion_name} and passing X-FileSpin-Api-Key:{API_KEY} or Authorization: Bearer {JWT} header

When using this option, all On-demand Image transformation options such as resize, crop, etc can be applied.

As a signed URL via /get_link API

Use /get_link API providing the conversion_name as CONTENT_KEY as described in Asset Get Link section

Asset Delete Conversion

Replace API_KEY with your API Key

curl -H "X-FileSpin-Api-Key:API_KEY" \
-X "POST" \
https://app.filespin.io/api/v1/assets/99d819953914402babbdeb68337ea6a3/content/my_edited_copy

Use this API to delete a conversion file of an asset.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/{CONVERSION_NAME}/delete

HTTP RESPONSE

Appropriate HTTP Status Code as specified in API Overview section.

Asset Get Data

Get Asset Data

curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/data

Retrieve an Asset's data that includes Core metadata, Custom metadata, conversions and addon details.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

GET https://app.filespin.io/api/v1/assets/{ASSET_ID}/data

REQUEST QUERY PARAMETERS

HTTP RESPONSE

HTTP Status code and JSON response that follows Standard Asset Data Format.

Asset Update Data

Update Asset's custom data

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" -d \
'{"data": {"input1": "value1"}, "mode":  "APPEND"}' \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/data/update

Save arbitrary JSON data with a file.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/data/update

REQUEST QUERY PARAMETERS

REQUEST JSON BODY

The request body should be a JSON with data and mode keys.

Example request

To update file data, send a JSON payload like below to store with the file.

{
  "data": {
    "input1": "value1",
    "input2": "value2",
    "filespin_search_txt": "MY_OWN_FILE_ID"
  },
  "mode": "APPEND"
}

JSON Schema support

FileSpin supports JSON Schema for Asset Data. Assigning schema to asset data enables versatile field-based search and additional data validations.

Once one or more schemas have been setup for an account, you can pass the optional schema id data_schema_id as shown below to automatically assign a schema to the asset data.

{
  "data": {
    "input1": "value1",
    "input2": "value2",
    "filespin_search_txt": "MY_OWN_FILE_ID"
  },
  "mode": "APPEND",
  "data_schema_id": 1  
}

HTTP RESPONSE

Response JSON

{
  "status": "OK",
  "message": "Data updated"
}

HTTP Status code and JSON response like the one shown in the code sample to the right.

Asset Download

Replace API_KEY with your API Key. sample.jpg file should be present in the folder where the program is invoked

#cURL sample

curl -H "X-FileSpin-Api-Key:API_KEY" \
-X "GET"
https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/{CONTENT_KEY}/download \
-o original.jpg

Use this API to retrieve the original file or a pre-defined image conversion or a video transcode. HTTP Range header can also be used to retrieve large file as multiple parts.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

GET https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/{CONTENT_KEY}/download

URL PARAMETERS

HTTP RESPONSE

The file is returned. Mime type and length of the content returned will be set in the response header.

Download large file as multiple parts

# Example using HTTP Range header to get a file as two parts. Assume the file size is 200 MB original video file.
#Get first 100 MB
curl -H "X-FileSpin-Api-Key:API_KEY" \
-X "GET" \
-r 0-104857600 \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/{CONTENT_KEY}/download \
-o part1

#Get second and final part
curl -H "X-FileSpin-Api-Key:API_KEY" \
-X "GET" \
-r 104857601-209715200 \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/{CONTENT_KEY}/download \
-o part2

#Merge the parts to get the original file
cat part1 part2 > original.mp4

You can use HTTP Range header parameter to download a large file as multiple parts. For details about the HTTP Range header, please visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35

Asset Get Link

To retrieve links for asset original or conversions

#Example to get a link for the original file with maximum expiry
curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/get_link?key=original&expiry=MAX&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT

#returns a link such as below:-
https://cdn.filespin.io/api/v1/files/content/e31c8dae2e934caf9cdbbacf60091a38?key=original&expiry=1486556379&delivery=display&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT&signature=ScdZeFTEs41edgmfgk-XJbO2ACk%3D

Use this API to retrieve links for Asset original content file and asset conversions.

You can use this API to get a content link that can be presented as a downloadable link in a web page or an app.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST (HTTP GET for single content file)

GET https://app.filespin.io/api/v1/assets/{ASSET_ID}/get_link?key={CONTENT_KEY}&expiry={SECONDS}&delivery={DELIVERY_MODE}&accessId={ACCESS_ID}

HTTP REQUEST (HTTP POST for multiple content files)

Retrieve lilnks for multiple Assets

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '["{ASSET_ID}", "{ASSET_ID}"]' \
https://app.filespin.io/api/v1/assets/get_link?key={CONTENT_KEY}&expiry={SECONDS}&delivery={DELIVERY_MODE}&accessId={ACCESS_ID}

POST https://app.filespin.io/api/v1/assets/get_link?key={CONTENT_KEY}&expiry={SECONDS}&delivery={DELIVERY_MODE}&accessId={ACCESS_ID}

Pass the Asset IDs in the request body as a list.

REQUEST PARAMETERS

HTTP RESPONSE

Response for a single asset GET request

https://cdn.filespin.io/api/v1/files/content/c5651f8783f64d09985f0dd38359d846?key=thumbnail&expiry=1486556379&delivery=display&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT&signature=ScdZeFTEs41edgmfgk-XJbO2ACk%3D

HTTP Status code and JSON response like the one shown in the code sample to the right.

• For GET request for a single Asset, the link is returned in response as shown in the code samples to the right.

• For POST request with multiple Asset IDs, a JSON with links is returned as shown.

{
  "ASSET_ID": "https://URL",
}

Response JSON with links for multiple assets POST request

{
  "c5651f8783f64d09985f0dd38359d846": "https://cdn.filespin.io/api/v1/files/content/c5651f8783f64d09985f0dd38359d846?key=thumbnail&expiry=1486556379&delivery=display&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT&signature=ScdZeFTEs41edgmfgk-XJbO2ACk%3D",
  "aa2e7cce8a1e479daf5eb94cc413e8cb": "https://cdn.filespin.io/api/v1/files/content/ca2e7cce8a1e479daf5eb94cc413e8cb?key=thumbnail&expiry=1486556379&delivery=display&accessId=IZJTAMBQGAYDAMBQGAYDAMBQGAYDANKT&signature=ScdZeFTEs41edgmfgk-XJbO2ACk%3D"
}

Asset Search

#HTTP POST - Get fist page of results
curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d  '{ "keyword": "test*", "content_type": "image*", \
"upload_time_range": {"start": "2013-01-01T10:25:11Z","end": "2013-02-01T10:25:11Z"}, \
"file_size_range": {"start": 10240, "end": 402600}, "limit_per_page": 30 }' \
https://app.filespin.io/api/v1/assets/search

#HTTP GET - Get additional search result pages
curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assets/search/{SEARCH_RESULT_ID}/{PAGE_NO}

Search API provides a powerful way to find files based on file name, mime type, size and other Asset properties. Search API has two invocation methods:

• HTTP POST to run the search and get first page of results (default 50 per page)
• HTTP GET to get additional result pages

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP POST - Get first page with results

Run search and get first results page

POST https://app.filespin.io/api/v1/assets/search

REQUEST JSON PARAMETERS

All parameters are optional. A complete JSON payload for search request below:-

{
  "keyword": "sample",
  "file_name": "test*",
  "content_type": "image* OR video* OR audio*",
  "creator_id": 100,
  "upload_time_range": {
    "start": "2013-01-01T10:25:11Z",
    "end": "2013-02-01T10:25:11Z"
  },
  "file_size_range": {
    "start": 10240,
    "end": 402600
  },
  "sort_by": [
    "upload_time_range_DESC",
    "file_size_range_ASC",
    "content_type_DESC"
  ],
  "limit_per_page": 30
}

HTTP GET - Get additional result pages

To get the result pages, use HTTP GET with the SEARCH_RESULT_ID and page required

GET https://app.filespin.io/api/v1/assets/search/{SEARCH_RESULT_ID}/{PAGE_NO}

REQUEST QUERY PARAMETERS

The HTTP GET response JSON is the same as for HTTP POST that provides one page of search result.

HTTP RESPONSE

HTTP Status code and JSON response like the one shown in the code sample to the right.

//Response JSON with {Asset Data}
{
    "status": "OK",
    "search_result_id": "0a9761f2f9",
    "total_files": 1,
    "page": 1,
    "total_pages": 1,
    "result": ["116f6a2a266d45d58d067f7c39a2e4dd"],
    "extended_result": {
       "116f6a2a266d45d58d067f7c39a2e4dd": {Asset Data}
    }
}

Asset Data is as specified in Asset Data Format - the JSON format used across all Asset API responses.

#HTTP POST - Search for exact match for word "a+b"
#note the escaped double quotes around the search word
curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d  '{ "keyword": "\"a+b\""}' \
https://app.filespin.io/api/v1/assets/search

#HTTP POST - Search for exact match for word "abc 123"
#note the escaped double quotes around the search word
curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d  '{ "keyword": "\"abc 123\""}' \
https://app.filespin.io/api/v1/assets/search

Search for exact match

To search for exact match for a word, enclose the word in double quotes " and escape the doouble quotes as shown in the examples.

For example,

• to search for ABC 123, you need to search for "ABC 123" (the double quote escaped format is "\"ABC 123\"")

Search for words with special characters

+ - && | | ! ( ) { } [ ] ^ " ~ * ? : \ / are special characters in the search query. To search for a word that contains special characters you should enclose the word in double quotes.

For example,

• to search for a+b, enclose the word in double quotes like "a+b"
• to search for ABC-123, provide the search word as "ABC-123"

Search using Custom Schema Fields

FileSpin supports searching on custom schema fields defined as searchable in Custom Asset Schema. You can provide search criteria for custom schema via a JSON as below:-

This search with below schema_criteria will return with all assets whose schema ID is 1 and which contain "john" in the "name" field.

{
  "schema_criteria": {
    "data_schema_id": 1,
    "fields": {
      "name": "john"
    }
  }
}

#Search and retrieve assets that contain word starting `john` anywhere in a custom field called `customerName`
curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d  '{
            "schema_criteria": {
              "data_schema_id": 1,
              "fields": {
                "customerName": "john"
              }
            }
          }' \
https://app.filespin.io/api/v1/assets/search

#HTTP POST - Custom Schema search with wildcards
#Search and retrieve assets that contain word starting with `john` in a custom field called `customerName`
curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d  '{
            "schema_criteria": {
              "data_schema_id": 1,
              "fields": {
                "customerName": "john*"
              }
            }
          }' \
https://app.filespin.io/api/v1/assets/search

#Search and retrieve assets that contain word `john` or `dan` in a custom field called `customerName`
curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d  '{
            "schema_criteria": {
              "data_schema_id": 1,
              "fields": {
                "customerName": "john OR dan"
              }
            }
          }' \
https://app.filespin.io/api/v1/assets/search

Custom Schema search with AND, OR and wildcards

Custom Schema search supports AND, OR and wildcards with certain limitations.

• AND and OR cannot be used together in the same search criteria.
• Search criteria can contain upto 5 AND or OR operators.
• * wildcard can only be used in suffix of search terms like test*, image*.

Examples

• to search and retrieve assets that contain for john or dan in a custom field called customerName, use "customerName":"john OR dan"
• to search and retrieve assets that contain the term john in the custom field called customerName, use "customerName":"john"
• to search and retrieve assets that contain the term john or johny or johnny in a custom field called customerName, use "customerName":"john*"

Notes & tips on Search API

• To search for exact string match, quote the search string, e.g. "\"my exact search string\"". This will search for the exact string "my exact search string".
• Custom Schema Fields search using "schema_criteria" can be used in combination with other standard search parameters such as keyword, content_type, sort_by, etc.
• Rules for searching words with special characters and exact match apply to custom schema fields as well.
• Search results are sorted by relevance by default. You can sort the results by other supported sort fields such as upload_time, file_size, etc. using the sort_by parameter.
• Search conditions are additive. FileSpin applies AND when searching for more than one condition, e.g. if you provide keyword and content_type, the search will return files that match both the keyword and content type.

Asset Find Duplicates

Find asset duplicates

#get duplicates. returns default first page
curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/original/duplicates

#get second page
curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/original/duplicates/2

Retrieve duplicates of an asset original file by checking for the Asset file's MD5 checksum.

HTTP REQUEST

GET https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/original/duplicates/{PAGE_NO}

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

REQUEST QUERY PARAMETERS

RESPONSE JSON

Response JSON with duplicates

{
  "id": "99d819953914402babbdeb68337ea6a3",
  "name": "example.jpg",
  "size": 8836363,
  "content_type": "image/jpeg",
  "checksum": "5f5f26bd7c0f62c6e02e44c73d09734e",
  "total_files": 62,
  "total_pages": 3,
  "page": 3,
  "duplicates": [
    "425f6a2a266d45d58d067f7c39a2e4bd",
    "a563da2a266d45d58d067b8c39a3d5ad"
  ]
}

HTTP Status code and JSON response like the one shown in the code sample to the right.

Asset Delete

API to delete an asset or it's conversions.

Delete an original asset or a conversion. Below deletes 480p-video conversion of a video asset.

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys":  ["480p-video"]}' \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/delete

• Deleting the original is a soft-delete within FileSpin. It will mark Asset as deleted and hide it from view (See Purge API to completely purge an Asset)
• Asset administrators can retrieve deleted Assets using Search API by setting trashed option to true
• Unknown custom keys and keys that do not apply to the file type will be ignored

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP Request

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/delete

Query parameters

Request JSON Parameters

Request JSON payload

{
  "keys": ["480p-video", "720p-video"]
}

HTTP RESPONSE

Standard HTTP Status code - 202 or 200

Webhook callback on delete completion

Once the delete request is completed, callback is issued to configured Webhook.

Please see Tools & Integration- > Webhooks section for file-deleted event callback to learn about the callback JSON structure.

Asset Undelete

Undelete an asset

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys":  ["original"]}' \
https://app.filespin.io/api/v1/assets/trash/{ASSET_ID}/undelete

API to undelete an asset that has been deleted.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP Request

POST https://app.filespin.io/api/v1/assets/trash/{ASSET_ID}/undelete

Query parameters

Request JSON Parameters

HTTP RESPONSE

Standard HTTP Status code - 202 or 200

Webhook callback on undelete completion

Once the undelete request is completed, callback is issued to configured Webhook.

Please see Tools & Integration- > Webhooks section for file-undeleted event callback to learn about the callback JSON structure.

Asset Purge

Purge deleted assets

curl -H "X-FileSpin-Api-Key:ASSET_KEY" \
-X DELETE https://app.filespin.io/api/v1/assets/trash/purge

This is a ADMIN-only API

API to completely purge all assets that are in Trash (i.e. in deleted state) across all users within a User Group.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

DELETE https://app.filespin.io/api/v1/assets/trash/purge

HTTP RESPONSE

Standard HTTP Status code - 202 or 200

Asset Access - Make Public

Make an asset or its conversion public

curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"keys": ["480p-wm-video"]}'\
     https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/set_public_access

This API can be used to set public-read access to a file or its conversions in the Cloud Storage (such as S3).

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP Request

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/set_public_access

REQUEST QUERY PARAMETERS

REQUEST JSON

Possible Key values

HTTP RESPONSE

Standard HTTP Status code - 202 or 200

Asset Access - Remove Public Access

Remove public access permission from an asset or its conversion

curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"keys": ["480p-wm-video"]}'\
 https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/remove_public_access

This API can be used to remove public-read access permission from a file or its conversions in the Cloud Storage (such as S3).

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP Request

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/content/remove_public_access

REQUEST QUERY PARAMETERS

REQUEST JSON

Possible Key values

HTTP RESPONSE

Standard HTTP Status code - 202 or 200

Asset Processing API

Assets can be processed for image transformations, video transcodes and other custom workflows using /process API.

Image Processing API

Process an image asset for deepzoom

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys":  ["deepzoom"]}' \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/process

The /process API is useful in the following scenarios:-

• Create static image conversions that are not covered by On-demand Image Conversion
• Re-process a static image conversion to apply a new watermark
• Re-process an image if there are any on-demand image conversion errors
• Re-process an image if auto-tags have not been generated

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/process

REQUEST QUERY PARAMETERS

REQUEST JSON BODY

Unknown keys and keys that do not apply to the file type will be ignored.

Built-in Image processing keys

Re-generate on-demand image

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys":  ["smart_imaging"]}' \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/process

HTTP RESPONSE

Standard HTTP Status code - 202 or 200

Also, once processing completes, Asset Data JSON will contain process state for smart_imaging as below:

"addons_info": {
    "ON_DEMAND_IMAGE": {
      "available": true
    }
  }

Video Transcoding API

Process a 720p-video

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys":  ["720p-video"]}' \
https://app.filespin.io/api/v1/assets/{ASSET_ID}/process

This API uses the same endpoint as image conversion API. It is useful in the following scenarios:-

1. Generate standard video transcodes that do not exist for a video file
2. Re-apply a new watermark to existing video transcodes

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/process

REQUEST QUERY PARAMETERS

REQUEST JSON BODY

Built-in Video processing keys

• Built-in keys that correspond to video quality and sizes: 360p-video, 480p-video, 720p-video, 1080p-video, hls-video
• Watermarked transcodes: 360p-wm-video, 480p-wm-video,720p-wm-video,1080p-wm-video

Special video processing keys

Note that unknown keys and keys that do not apply to the file type will be ignored.

HTTP RESPONSE

Standard HTTP Status code - 202 or 200 and JSON response body as below:-

{
    "status": "QUEUED",
    "message": "Job queued",
    "job_id": 42
}

Video Custom Transcoding API

You can make use of /clip/process API to create custom transcodes to :-

• create a clip from specific section of a video
• add a custom watermark to a video other than the default watermark

The transcode output will be added as a conversion to the asset and stored in Video transcodes bucket specified in account settings. Webhook callback will be issued once output is created.

Using your API Key send a request as below:-

HTTP REQUEST

Example transcode requests

#Create a clip with 480p preset from a video starting from 10 seconds and length of 5 seconds.
#Name the clip as "sample.mp4"
#Make access public in Storage to allow playback using /transcodes API without signed URL

curl -X "POST" "https://app.filespin.io/api/v1/assets/{ASSET_ID}/clip/process" \
     -H "X-FileSpin-Api-Key: 0de9d8e207974dc7b29c76372890e4ca" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
       "name": "sample",
       "preset": "480p-video",
       "start": 10,
       "length": 5,
       "public": true,
        }'

#Transcode the entire video using 720p preset and add a custom watermark.
#Name the clip as "720p-custom-wm-video.mp4"

curl -X "POST" "https://app.filespin.io/api/v1/assets/{ASSET_ID}/clip/process" \
     -H "X-FileSpin-Api-Key: 0de9d8e207974dc7b29c76372890e4ca" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
             "name": "720p-custom-wm-video",
             "preset": "720p-video",
             "watermark": {
                 "url": "http://app.filespin.io/api/v1/user/watermark/1",
                 "placement": "top-right",
                 "scale": 0.2
             }
          }'

HTTP POST https://app.filespin.io/api/v1/assets/{ASSET_ID}/clip/process

REQUEST QUERY PARAMETERS

REQUEST JSON

Asset Data - Example custom conversion added to Asset

 "480p-custom-wm-video": {
      "key": "/transcodes/12bc22852739447c956b97580977fdf4/480p-custom-wm-video.mp4",
      "bucket": "my-bucket",
      "width": 640,
      "height": 480,
      "public": true,
      "watermarked": true,
      "size": 346344,
      "duration": 5
    }

Note:

• Transcode output will be added to Asset as a Conversion automatically using the given name key
• Transcode output details can be retrieved using the Get Data API (see Asset Data Storyboard JSON example)
• Transcode output is stored in Video Transcodes storage bucket specified in account settings

HTTP RESPONSE

Standard HTTP Status code - 202 or 200 and JSON response body as below:-

{
    "status": "QUEUED",
    "message": "Job queued",
    "job_id": 42
}

Batch Processing API

Process one or more assets in a single API call for creating or re-creating image conversions, video transcodes and addon processing.

# Example: use Asset IDs to re-process assets for specified conversions, transcodes and addons

curl -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{
        "ids": [
           "7204fbc866d94805ad3fab3e1a194abd"
        ],
       "conversions": ["smart_imaging"],
       "transcodes": ["480p-video"],
       "addons": ["storyboard"]
    }' \
https://app.filespin.io/api/v1/assets/content/original/reprocess

The asset batch processing API is useful in the following scenarios:-

• process multiple assets to apply updated watermark
• process multiple assets to create a specific conversion, transcode or addon

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP REQUEST

POST https://app.filespin.io/api/v1/assets/content/original/reprocess

REQUEST JSON BODY

Note:

• A maximum of 100 assets can be re-processed in one API call
• If conversions, transcodes or addons are all empty, or not provided, all conversions, transcodes and addons enabled in caller's account settings will be re-processed.
• Unknown keys in conversions, transcodes or addons and keys that do not apply to the file type will be ignored.

HTTP RESPONSE

Standard HTTP Status codes

Asset Schema API

Asset Schema provides the ability to store custom metadata (provided as JSON) that conform to a standard schema. Asset Schema is defined using JSON Schema 2020-12 with a simple FileSpin envelope as below. FileSpin extends JSON Schema to support additional properties using filespin_properties for rendering in frontend UI.

Asset Schema JSON

Build-in default Asset Schema

When a new Asset is created, it is assigned a default Asset Schema with a single field filespin_search_txt which is a searchable text field. This field is a build-in field that cannot be altered. It can be used to store keywords for searching.

{
  "id": 0,
  "name": { "en": "FileSpin Asset Schema" },
  "status": "ACTIVE",
  "schema": {
    "$id": "https://app.filespin.io/json-schema/Asset.CustomMetadata.v1.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "Default Asset Metadata",
    "required": [],
    "properties": {
      "filespin_search_txt": {
        "type": "string",
        "description": "Searchable keywords",
        "minLength": 0,
        "maxLength": 200,
        "filespin_properties": {
          "title": { "en": "Searchable keywords" },
          "hint": { "en": "Keywords associated with this asset for seaching" },
          "placeholder": { "en": "Enter keywords separated by a space" },
          "searchable": true,
          "keyword_searchable": true,
          "ui": {
            "order": 1,
            "readonly": false,
            "disabled": false,
            "hidden": false
          }
        }
      }
    }
  }
}

Example Schema with a custom field

This example shows a custom schema with a single field a_name of type string and a field a_date of type string with format set to date according to JSON Schema 2020-12 specification

{
  "name": { "en": "Sample Asset Schema" },
  "status": "ACTIVE",
  "schema": {
    "$id": "https://app.filespin.io/json-schema/Asset.CustomMetadata.v1.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "Default Asset Metadata",
    "required": ["a_date"],
    "properties": {
      "a_name": {
        "type": "string",
        "description": "A name",
        "minLength": 0,
        "maxLength": 200,
        "filespin_properties": {
          "title": { "en": "A name" },
          "hint": { "en": "A name" },
          "placeholder": { "en": "A name" },
          "searchable": true,
          "keyword_searchable": true,
          "ui": {
            "order": 1,
            "readonly": false,
            "disabled": false,
            "hidden": false
          }
        }
      },
      "a_date": {
        "type": "string",
        "description": "A date",
        "minLength": 0,
        "maxLength": 24,
        "format": "date",
        "filespin_properties": {
          "title": { "en": "Important date" },
          "hint": { "en": "Important date" },
          "placeholder": { "en": "Important date" },
          "searchable": true,
          "ui": {
            "order": 1,
            "readonly": false,
            "disabled": false,
            "hidden": false
          }
        }
      }
    }
  }
}

Built-in support for string sub-types

JSON Schema string type has built-in support for these optional format sub-types: "date", "email".

For a more details, please consult with your FileSpin technical contact who can help setup appropriate schema for your asset data.

FileSpin Asset Schema properties

filespin_properties within $schema->properties contains FileSpin specific properties per field defined as below:-

UI rendering

{"order": 1, "readonly": false, "disabled": false, "hidden": false }

where order is for display order of the field, readonly is to make the field read-only, disabled is non-selectable read-only, hidden is to render as hidden field

Asset Schema - Get

Retrieve an Asset Schema definition.

# Retrieve Asset Schema Definition using FileSpin Schema ID.
curl -H "X-FileSpin-Api-Key:API_KEY" \
 https://app.filespin.io/api/v1/assetschemas/SCHEMA_ID

HTTP REQUEST

GET https://app.filespin.io/api/v1/assetschemas/{SCHEMA_ID}

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP QUERY PARAMETERS

HTTP Response

HTTP Status code and JSON response with Asset Schema definition. See Asset Schema JSON Format.

Asset Schema - Get All

# Retrieve all Asset Schema Definitions
curl -H "X-FileSpin-Api-Key:ASSET_KEY" \
https://app.filespin.io/api/v1/assetschemas

Retrieve all Asset Schema definitions available.

HTTP REQUEST

GET https://app.filespin.io/api/v1/assetschemas

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP RESPONSE

HTTP Status code and JSON response like the one shown in the code sample to the right.

{

  "status": "OK",
  "data": [ {Asset Schema JSON} ]

}

Asset Schema - Create

Create a new Asset Schema definition

curl -X "POST" -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ASSET_SCHEMA_JSON}' \
     https://app.filespin.io/api/v1/assetschema

Create a new Asset Schema definition.

HTTP REQUEST

POST https://app.filespin.io/api/v1/assetschema

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

REQUEST PARAMETERS

Pass {ASSET_SCHEMA_JSON} in request body. See Asset Schema JSON for the JSON format. Note that when creating Asset Schema id should not be provided.

HTTP RESPONSE

Response JSON

{
  "id": 27
}

HTTP Status code and JSON response like the one shown in the code sample to the right.

Asset Schema - Update

Update an existing Asset Schema definition.

Update an existing Asset Schema Definition using.

curl -H "X-FileSpin-Api-Key:API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ASSET_SCHEMA_JSON}' \
     https://app.filespin.io/api/v1/assetschema

HTTP REQUEST

POST https://app.filespin.io/api/v1/assetschema

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

REQUEST PARAMETERS

Include id of Asset Schema to be updated in {ASSET_SCHEMA_JSON} request payload as below:-

{
  "id": 26,
  "name": {
    "en": "My Asset Schema"
  },
  "status": "ACTIVE",
  "schema": {
    "$id": "https://app.filespin.io/api/v1/json-schema/Asset/CustomMetadata.v1.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "My Asset Metadata",
    "required": [],
    "properties": {
      "email": {
        "title": "An Email",
        "type": "string",
        "format": "email",
        "minLength": 5,
        "maxLength": 200,
        "filespin_properties": {
          "title": {
            "en": "an email"
          },
          "hint": {
            "en": "an email"
          },
          "placeholder": {
            "en": "an email"
          },
          "searchable": true,
          "keyword_searchable": false,
          "ui": {
            "order": 4,
            "readonly": false,
            "disabled": false,
            "hidden": false
          }
        }
      }
    }
  }
}

See Asset Schema JSON for the JSON format.

HTTP RESPONSE

Response JSON

{
  "id": 27
}

HTTP Status code and JSON response like the one shown in the code sample to the right.

Asset Collection API

Asset Collections provide a robust method for managing assets and collaborating with other users. Collections can be private to a user or can be shared within a user group.

Asset Collection JSON Format

Asset Collection has the below JSON structure.

{
  "id": 21,
  "user_id": 45,
  "name": "My Collection",
  "description": "An example description",
  "last_update": "2022-01-24T09:11:05Z",
  "assets": ["3b5123160c474720931292c33eb46c52"],
  "group_access": false,
  "user_name": "John Doe",
  "user_email": "john@example.org",
  "extended_result": {}
}

Asset Collection - Get

Retrieve a Collection. When no Collection ID is passed, the API returns the Default Basket Collection.

get basket (Default collection)

curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assetcollection

get a collection by id

curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assetcollection/2

HTTP REQUEST

GET https://app.filespin.io/api/v1/assetcollection/{id}[?load_assets=y]

If the optional URL parameter load_assets=y, the response will contain the entire Asset Data for each asset under extended_result key.

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP RESPONSE

Respone JSON as shown.

API response JSON

{
  "status": "OK",
  "data": {
    "id": 21,
    "user_id": 45,
    "name": "SELECTED_ASSETS",
    "description": "",
    "last_update": "2022-01-24T09:11:05Z",
    "assets": ["3b5123160c474720931292c33eb46c52"],
    "group_access": false,
    "user_name": "John Doe",
    "user_email": "john@example.org",
    "extended_result": {}
  }
}

Asset Collection - Get All

Retrieve Collections upto a maximum of 30. For retrieving additional collections, use the Collection Search API with pagination.

# get all collections
curl -H "X-FileSpin-Api-Key:API_KEY" \
https://app.filespin.io/api/v1/assetcollections

HTTP REQUEST

GET https://app.filespin.io/api/v1/assetcollections

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP RESPONSE

Collections API response JSON looks like below:-

{
  "status": "OK",
  "data": {
    "total_collections": 1,
    "collections": [
      {COLLECTION_JSON}
    ]
  }
}

Asset Collection - Search

Search and retrieve Collections with pagination. Use the total_collections and limit to calculate offset to paginate.

Search asset collections

curl -X "POST" -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{
        "keyword": "test",
        "private_only": false,
        "last_update_range": {"start": "2022-03-18T01:01:01Z", "end": "2022-04-24T01:01:01Z"},
        "sort_by": ["group_access ASC", "name ASC", "last_update DESC"],
        "offset": 0,
        "limit": 30
}' \
https://app.filespin.io/api/v1/collections

HTTP REQUEST

POST https://app.filespin.io/api/v1/assetcollections

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

REQUEST JSON

The request payload JSON keys are as below.

HTTP RESPONSE

Same as /api/v1/collections response above.

Asset Collection - Create

Create new Asset Collection

curl -X "POST" -H "X-FileSpin-Api-Key:API_KEY" \
-H "Content-Type: application/json" \
-d '{  "name": "Test Collection",
   "public": false,
   "assets": ["b3ad7854e1ad4ce8a8c83272447f980b","caf2b5f2e80a40729e32489ee65ef0d8"]
}' https://app.filespin.io/api/v1/assetcollection

HTTP REQUEST

POST https://app.filespin.io/api/v1/assetcollection