Skip to main content
Sign in

Search

Flight Control Help Center

Assets Library API Reference

  • Updated

General

You can use the Assets Library API to access and manage assets uploaded to an account's Assets Library. The assets are organized in a folder structure resembling a file system. When configuring an API file transfer from a digital asset management (DAM) provider, it's recommended that you group all files within a dedicated folder for that vendor.

Each asset in the library is assigned a unique key. This key serves as the path file that includes the file name, similar to a typical file system path.

Note: Every asset has a publicly-accessible, CDN-cached URL. This URL is designed for use in ads, and it continues to represent the asset after any modifications, such as resizing or transcoding.

API Methods

Make sure to properly authenticate when making API calls. For information on authenticating through the Clinch API, see API Authentication.

PutAsset

Path PUT https://publicapi.clinch.co/{AccountId}/Assets/Asset
Inputs

Required

  • key (string)
  • Content-Type header: Needs to be multipart/form-data with a boundary, and the name of the field is file (see here).
  • Body: The asset file within the multipart/form-data boundary including the required Content-Type header as part of the boundary.

Optional

  • failIfExists (Boolean): Prevents the API method from executing if the file already exists.
  • x-tags header (example: tag1=value1&tag2=value2...)
Outputs
  • 201 (created): This also returns a Location header containing a URL to download the asset.
  • 400 (bad request)
Notes
  • Assets, like videos and images, will undergo optimization and transcoding for better ad serving.
  • If the x-tags header is present, its tags will be added to the created asset.
  • All folders located in the path for the API call will be created if they don't already exist.
  • By default, if an asset with that key already exists, then it will be overwritten.
    • failIfExists: Returns an error in this case instead.
Example

Example request for account ID 12345, and a file named "product.jpg":

POST /12345/Assets/Asset HTTP/1.1
Content-Length: 68137
Content-Type: multipart/form-data; boundary=---------------------------974767299852498929531610575
x-tags: key=value&tag=tag1

-----------------------------974767299852498929531610575
Content-Disposition: form-data; name="file"; filename="product.jpg"
Content-Type: image/jpeg

(content of the file product.jpg)
-----------------------------974767299852498929531610575--

 

PutAssetJSON

Path PUT https://publicapi.clinch.co/{AccountId}/Assets/AssetJSON
Inputs

Required:

  • Content-Type header, set to application/json.
  • JSON body:
    • key (string; path to asset file)
    • content-type (string): The content type of the asset file. This is different from the Content-Type header, which should also be present in the request.
    • data (string): The encoded contents of the asset file.

Optional fields:

    • failIfExists (Boolean): If set to true, it will return an error if the asset file already exists. If set to false, it will overwrite the asset file. The default value is false.
    • tags (object with key/value string pairs)
    • dataEncoding: Specifies the encoding. When omitted, base64 is assumed. Currently, only base64 is supported.
Outputs
  • 201 (created): This also returns a Location header containing a URL to download the asset.
  • 400 (bad request)
Notes
  • Some assets, like videos and images, will undergo optimization and transcoding for better ad serving.
  • This API method can be used instead of PutAsset when multipart/form-data is unavailable, difficult to implement, or if the client encounters other technical limitations.
  • If the tags field is present, the tags will be added to the created asset.
  • All folders in the path will be created if they don’t exist.
  • By default, if an asset with that key already exists, then it will be overwritten.
    • failIfExists: Returns an error in this case instead.
Example

JSON body:

{
  "key": "path/to/image.jpg",
  "content-type": "image/jpeg",
  "tags": {
   "key1": "value1",
   "key2": "value2"
    ...
  },
  "failIfExists": true,
  "dataEncoding": "base64",
  "data": "/9j/4AAQSkZJRgABAQEASABIAAD/.../8wABgAQEAX/2gAIAQEAAD8A0s8g/9k="
}

 

DeleteAsset

Path DELETE https://publicapi.clinch.co/{AccountId}/Assets/Asset
Inputs Required
  • key (string; path to asset file)
  • No body needed.
Outputs
  • 204 (no content)
  • 400 (bad request)

 

PutAssetMetadata

Path PUT https://publicapi.clinch.co/{AccountId}/Assets/Asset/AssetMetadata
Inputs Required
  • key (string; path to asset file)
  • Body: 
{
 "tags":{
 "tag1":"value1",
 "tag2":"value2"
 ...
 }
}
Outputs
  • 204 (no content)
  • 400 (bad request)

 

GetAssetMetadata

Path GET https://publicapi.clinch.co/{AccountId}/Assets/Asset/AssetMetadata
Inputs Required
  • key (string; path to asset file)
  • No body
Outputs
  • 200 (OK): 
{
 "url": "https://...",
 "originalAssetUrl": "https://...",
 "posterUrl": "https://...",
 "content-type":"...",
 "tags":{
 "tag1":"value1",
 "tag2":"value2"
 ...
 }
}
  • 400 (bad request)

 

PutFolder

Path PUT https://publicapi.clinch.co/{AccountId}/Assets/Folder
Inputs Required
  • folderPath (string; path to folder)
  • No body
Outputs
  • 201 (created)
  • 400 (bad request)
Notes If the folder already exists, a 400 code will be returned with the respective error.

 

DeleteFolder

Path DELETE https://publicapi.clinch.co/{AccountId}/Assets/Folder
Inputs Required
  • folderPath (string; path to asset folder)
  • No body

Optional

  • onlyIfEmpty (Boolean)
Outputs
  • 204 (no content)
  • 400 (bad request)
Notes

By default, will also delete all the assets in the folder (including subfolders).

  • onlyIfEmpty: Deletes the folder if it’s empty (otherwise, it returns a 400 error if it isn't empty).

If a folder doesn’t exist, a 400 error will be returned.

 

GetSubFoldersList

Path GET https://publicapi.clinch.co/{AccountId}/Assets/Subfolders
Inputs Required
  • folderPath (string; path to asset folder)
  • No body
Outputs
  • 200 (OK): 
{
 "subfolders":[
  ".../.../",
  ".../.../"
 ]
}
  • 400 (bad request)
Notes

  • This endpoint returns the folders under a specific path.

  • The returned values contain the folder's path from the root folder, and end with /.

  • If folderPath isn’t provided, it will return the root-level folders.

 

GetAssetList

Path GET https://publicapi.clinch.co/{AccountId}/Assets/AssetList
Inputs Required
  • key (string; path to asset file)
  • no body

Optional

  • folderPath (string; path to asset folder)
  • topLevelOnly (Boolean)
Outputs
  • 200 (OK): 
{
 "assets":[
  {
   "key":...,
   "url":"https://...",
   "originalAssetUrl": "https://...",
   "posterUrl": "https://...",
   "lastModifiedDate": "2023-06-15T08:45:31+03:00",
   "fileSize": 1242626
  },
  ...
 ]
}
  • 400 (bad request)
Notes
  • topLevelOnly: Returns the assets in the given folder only and not in the subfolders.
  • url: The URL of the optimized asset data (e.g.: transcoded video file).
  • originalAssetUrl: The URL of the original unoptimized data (e.g.: the original untouched video file).
  • posterUrl: Should be available for videos, and not other asset types.

 

CopyAsset

Path POST https://publicapi.clinch.co/{AccountId}/Assets/CopyAsset
Inputs Required
  • Body: 
{
 "key":"...", 
 "destinationKey":"...",
 "tags":{ // optional tags for the destination
  "tag1":"value1",
  "tag2":"value2",
  ...
 }
}

Optional

  • failIfExists (Boolean): If set to true, it will return an error if the asset file already exists. If set to false, it will overwrite the asset file. The default value is false.
Outputs
  • 201 (created): This also returns a Location header containing an URL to download the asset.
  • 400 (bad request)
Notes
  • If tags are present, then those tags will be used for the new object.
  • If tags aren’t present, then the tags from the original asset will be copied.
  • This method operates like PutAsset.

 

MoveAsset

Path POST https://publicapi.clinch.co/{AccountId}/Assets/MoveAssets
Inputs Required
  • Body: 
{
 "key":"...",
 "destinationKey":"...",
 "tags":{ // optional tags for the destination
  "tag1":"value1",
  "tag2":"value2",
  ...
 }
}

Optional

  • failIfExists (Boolean): If set to true, it will return an error if the asset file already exists. If set to false, it will overwrite the asset file. The default value is false.
Outputs
  • 201 (created): This also returns a Location header containing an URL to download the asset.
  • 400 (bad request)
Notes The MoveAsset method is equal to using the CopyAsset method, and then the DeleteAsset method.

 

DeleteMultipleAssets

Path DELETE https://publicapi.clinch.co/{AccountId}/Assets/MultipleAssets
Inputs Required
  • Body:
{
 "keys":[
 "key1",
 "key2",
 ...
 ]
}
Outputs
  • 200 (OK):
{
 "deleted":[
 "key1",
 "key2",
 ...
 ],
 "errored":[
  "key3",
  "key4",
  ...
 ]
}
  • 400 (bad request)