API Reference
Guides

Teleport API

The FileSpin Teleport is a native application that provides a reliable and efficient way to upload assets by continuously monitoring specific folders, known as Watched Folders, while automatically managing bandwidth usage and handling connectivity loss seamlessly. In addition to the dashboard interface, the Teleport exposes APIs that allow programmatic access to its features.

First-time Login & Activation

To get started with Teleport, visit the Teleport Dashboard and login using your FileSpin Cloud Login. The login will be validated against the FileSpin Cloud account. Once logged in, you will be able to use Teleport without having to login again.

Asset Archival Policy

On successful upload of hot-folder asset to the Cloud, these assets are archived. Assets are archived for 30 days by default. This can be changed by the IT administrator. Once an asset is archived, it will be available in read-only mode and cannot be updated via Teleport API.

Please note the following limitations for archived assets:

  • /data - Asset Get Data API will return ARCHIVED status for archived assets. This is a special status available only for archived assets.
  • /update Asset Update Data API cannot be used for assets that have been archived.
  • /conversions - Asset Get Conversion API cannot be used for assets that have been archived.
  • Archived assets will be completely deleted after the period specified in archival policy

Asset metadata can be updated by adding a JSON file alongside the asset file. The JSON file should have the same name as the asset file with .json extension. For example, for an asset file test.jpg the corresponding JSON metadata file should be named test.json.

JSON file based metadata update follows these rules:-

  • JSON file must be added first to the hot-folder before the asset file. If this is not followed, metadata will not be updated.
  • JSON file must follow the same JSON payload structure as update API (see below)
{
  "data": {
    "field1": "data1",
    "field2": "data2"
  },
  "mode": "APPEND",
  "data_schema_id": 42
}
  • If JSON is invalid or the schema ID is incorrect, Teleport will move the file to .rejected folder under the hot folder and write a .error file to indicate the error.

Using Teleport API

Teleport API can be used only for assets uploaded via the on-premise Teleport deployment where the API is used. There are exceptions to this as listed in Pass-through API and Local Caching API sections below.

Supported API

The Teleport API follows the same semantics as the FileSpin Cloud API for supported APIs. Please see below for APIs supported by Teleport.

📘

Replace {FILESPIN_TELEPORT_HOST} with the on-premise deployment hostname as provided by your IT administrator.

  • /search - Search Assets
    • HTTP POST {FILESPIN_TELEPORT_HOST}/api/v1/assets/search
    • Search for assets that are currently available in hot-folders and archive. For more details refer to Asset Search.
  • /conversions{?resize=300,300} - On-demand Image Transformations
    • HTTP GET {FILESPIN_TELEPORT_HOST}/api/v1/assets/{ASSET_ID}/conversions
    • To retrieve display images with on-demand transformations. Please refer to On-demand Image Transformations.
  • /data - Asset Get Data
    • HTTP GET {FILESPIN_TELEPORT_HOST}/api/v1/assets/{ASSET_ID}/data
    • Retrieve an Asset's data that includes Core metadata, Custom metadata, conversions and addon details. For more details refer to Asset Get Data.
    • API will return ARCHIVED status for archived assets
  • /upload - Asset Upload
    • HTTP POST {FILESPIN_TELEPORT_HOST}/api/v1/assets/new/content/original/upload (multipart/form-data)
    • Upload a file to Teleport's default hot-folder. For more details refer to Asset Upload.
  • /update - Asset Update Data
    • HTTP POST {FILESPIN_TELEPORT_HOST}/api/v1/assets/{ASSE``T_ID}/update
    • Save custom JSON data with an asset. For more details refer to Asset Update Data.
    • API can be used for assets that have been archived under the below conditions:-
      • internet connectivity is available for Teleport to update the Asset Metadata in the Cloud first before applying the changes to local Asset.
      • Asset has not been deleted from the Cloud.
  • /replace - Asset Replace
    • HTTP POST {FILESPIN_TELEPORT_HOST}/api/v1/assets/{ASSET_ID}/content/original/replace
    • Replace an Asset in Teleport. For more details refer to Asset Replace.
    • API can be used for assets that have been archived under the below conditions:-
      • internet connectivity is available for Teleport to replace the Asset in the Cloud first before applying the changes to local Asset.
      • Asset has not been deleted from the Cloud.
  • /conversions - Asset Get Conversion
    • HTTP GET {FILESPIN_TELEPORT_HOST}/api/v1/assets/{ASSET_ID}/conversions/{conversion_name}
    • Retrieve a specific conversion of an Asset. For more details refer to Asset Get Conversion.
  • /content/{conversion_name} - Asset Add Conversion
    • HTTP POST {FILESPIN_TELEPORT_HOST}/api/v1/assets/{ASSET_ID}/content/{conversion_name}
    • Upload and add a custom conversion file to an Asset. For more details refer to Asset Add Conversion.
    • API cannot be used for assets that have been archived.
  • /content/{conversion_name}/download - Asset Download Conversion
    • GET {FILESPIN_TELEPORT_HOST}/api/v1/assets/{ASSET_ID}/content/{conversion_name}/download
    • 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. For more details refer to Asset Download.

Pass-through API

Teleport provides a pass-through update feature where the Asset uploaded via Teleport and in ARCHIVED state can be updated in Cloud via Teleport for below API:-

  • /update AssetUpdate Data
  • /replace Asset Replace

Local Caching API

Teleport provides retrieval from Cloud and local caching feature for Assets in Teleport or the Cloud for the following API. For these API, asset is not required to exist in Teleport.

  • /api/v1/assets/{ASSET_ID}/conversions{?resize=300,300} - On-demand Image Transformations
  • /api/v1/assets/{ASSET_ID}/conversions/{conversion_name} - Asset Get Conversion
  • /api/v1/assets/{ASSET_ID}/transcodes/{TRANSCODE_KEY} - Streaming Video
  • /api/v1/files/content/{ASSET_ID}?{PARAMS} - Asset Display/Download URLs
    • URL as returned by /get_link Cloud API can be used to retrieve and cache the asset in Teleport
    • Replace the PROTOCOL, HOST and PORT part of the URL in /get_link API response with {FILESPIN_TELEPORT_HOST}
    • {PARAMS} - query parameters as returned by /get_link Cloud API

Notes

  • Default Cache Expiry is 30 minutes
  • Caching API requires a minimum of 10 GB disk space

🚧

Note that only the content is cached for above API. Asset will not be created in Teleport if does not exist in Teleport.