Assets API

The Assets API allows you to add Assets to the system such as images, PDF files, and HTML5 creative Assets (ZIP files).

This page covers the common endpoints and methods associated with the Assets API.

Authentication

Use the following header parameters for all requests:

Headers
Authentication string required	Authentication bearer token See Authentication Guide
X-IAA-OW-ID integer required	Organization Workspace ID Header

Assets Details

Get a List of All Assets

GET

Get a list of all Assets in the system. Includes both regular Assets and HTML5 creative assets.

An Asset id can be used to Get Asset Details or to perform various actions in Assets Management endpoints.

Response Properties

id integer	Asset ID
storagePath string	File path of Asset
cdnUrl string	URL of Asset
created integer	Unix epoch timestamp of Asset creation, in milliseconds
modifiedDate string	Date Asset modified
isDisposable boolean	Indicates whether Asset is temporary and can be purged
isZipFile boolean	Indicates whether the Asset is a ZIP file
isHtml5Creative boolean	Indicates whether the Asset is an HTML5 creative
assetDimensions object	Dimensions of the creative (HTML5 Assets only). Contains width and height
iframeHtml string	Ready-to-use iframe HTML code (HTML5 Assets only)

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "storagePath": "assets/201427/tfteBYO_1704204958735.jpg",
      "cdnUrl": "https://d3jme5si7t6llb.cloudfront.net/assets/201427/tfteBYO_1704204958735.jpg",
      "created": 1704204961147,
      "modifiedDate": "2024-01-02T14:16:08.726+0000",
      "isDisposable": false,
      "isZipFile": false,
      "isHtml5Creative": false,
      "assetDimensions": null,
      "iframeHtml": null
    },
    {
      "id": 2,
      "storagePath": "assets/201427/randomPath/index.html",
      "cdnUrl": "https://d3jme5si7t6llb.cloudfront.net/assets/201427/randomPath/index.html",
      "created": 1704204971010,
      "modifiedDate": "2024-01-02T14:16:11.375+0000",
      "isDisposable": true,
      "isZipFile": true,
      "isHtml5Creative": true,
      "assetDimensions": {
        "width": 300,
        "height": 250
      },
      "iframeHtml": "<iframe src=\"https://d3jme5si7t6llb.cloudfront.net/assets/201427/randomPath/index.html\" width=\"300\" height=\"250\" frameborder=\"0\" scrolling=\"no\" marginheight=\"0\" marginwidth=\"0\"></iframe>"
    },
    {
      "id": 3,
      "storagePath": "assets/201427/2mBGamD_1704205759807.jpg",
      "cdnUrl": "https://d3jme5si7t6llb.cloudfront.net/assets/201427/2mBGamD_1704205759807.jpg",
      "created": 1704205761106,
      "modifiedDate": "2024-01-02T08:59:21.508+0000",
      "isDisposable": false,
      "isZipFile": false,
      "isHtml5Creative": false,
      "assetDimensions": null,
      "iframeHtml": null
    }
  ]
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface AssetDimensions {
  width: number;
  height: number;
}

interface AssetDetail {
  id: number;
  storagePath: string;
  cdnUrl: string;
  created: number;
  modifiedDate: string;
  isDisposable: boolean;
  isZipFile: boolean;
  isHtml5Creative: boolean;
  assetDimensions: AssetDimensions | null;
  iframeHtml: string | null;
}

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: AssetDetail[];
      }
    }
  }
}

function getAllAssets(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/asset/list',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Asset Details

GET

Get properties of a single Asset by ID. For HTML5 creative assets, the response includes additional fields for dimensions and iframe HTML code.

Path Parameters
assetId integer	Asset ID

Response Properties

id integer	Asset ID
storagePath string	File path of Asset
cdnUrl string	URL of Asset
created integer	Unix epoch timestamp of Asset creation, in milliseconds
modifiedDate string	Date Asset modified
isDisposable boolean	Indicates whether Asset is temporary and can be purged
isZipFile boolean	Indicates whether the Asset is a ZIP file
isHtml5Creative boolean	Indicates whether the Asset is an HTML5 creative
assetDimensions object	Dimensions of the creative (HTML5 Assets only). Contains width and height
iframeHtml string	Ready-to-use iframe HTML code (HTML5 Assets only)

JSON

Select exampleRegular AssetHTML5 Creative Asset

Response 200

{
  "success": true,
  "data": {
    "id": 1,
    "storagePath": "assets/201427/tfteBYO_1704204958735.jpg",
    "cdnUrl": "https://cdn.example.com/assets/201427/tfteBYO_1704204958735.jpg",
    "created": 1704204961147,
    "modifiedDate": "2024-01-18T06:03:23.823+0000",
    "isDisposable": true,
    "isZipFile": false,
    "isHtml5Creative": false,
    "assetDimensions": null,
    "iframeHtml": null
  }
}

Response 200

{
  "success": true,
  "data": {
    "id": 2,
    "storagePath": "assets/201427/randomPath/index.html",
    "cdnUrl": "https://cdn.example.com/assets/201427/randomPath/index.html",
    "created": 1704204971010,
    "modifiedDate": "2024-01-18T06:03:23.823+0000",
    "isDisposable": false,
    "isZipFile": true,
    "isHtml5Creative": true,
    "assetDimensions": {
      "width": 300,
      "height": 250
    },
    "iframeHtml": "<iframe src=\"https://cdn.example.com/assets/201427/randomPath/index.html\" width=\"300\" height=\"250\" frameborder=\"0\" scrolling=\"no\" marginheight=\"0\" marginwidth=\"0\"></iframe>"
  }
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "No Asset found with the Asset ID provided. Please provide a valid ID."
    }
  ]
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface AssetDimensions {
  width: number;
  height: number;
}

interface AssetDetail {
  id: number;
  storagePath: string;
  cdnUrl: string;
  created: number;
  modifiedDate: string;
  isDisposable: boolean;
  isZipFile: boolean;
  isHtml5Creative: boolean;
  assetDimensions: AssetDimensions | null;
  iframeHtml: string | null;
}

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: AssetDetail;
      }
    }
  }
}

function getAssetDetails(assetId: number): Promise<Responses> {
  const options = {
    method: 'GET',
    url: `https://api.iqm.com/api/v3/asset/${assetId}`,
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Assets Management

Add Multiple Assets

POST

Add multiple Assets to the system. Request accepts an array of multipart file objects and their corresponding metadata. Supports both regular Assets (images, PDFs) and HTML5 creative Assets (ZIP files).

Parameters
filesMetadata form data required	Object array in JSON string
filesMetadata object properties attachedFileName string Name of asset originalFileName string Name of uploaded multipart file disposable boolean Indicates whether Asset is temporary and can be purged, default: false zipFile boolean Set to true when uploading a ZIP file for HTML5 creatives, default: false html5Creative boolean Set to true when uploading an HTML5 creative asset, default: false
files multipart/form-data required	Array of Asset files to upload

Response Properties

assetID integer	Unique identifier of the uploaded asset
assetCDNURL string	CDN URL of the uploaded asset
dimensions object	Dimensions of the creative (HTML5 Assets only). Contains width and height
iframeHtml string	Ready-to-use iframe HTML code (HTML5 Assets only)

JSON

Select exampleRegular AssetHTML5 Creative Asset

Formdata Sample

------WebKitFormBoundaryAofpaWXja6BTaYQ9
Content-Disposition: form-data; name="files"; filename="example.jpg"
Content-Type: image/jpeg

------WebKitFormBoundaryAofpaWXja6BTaYQ9
Content-Disposition: form-data; name="filesMetadata"

[{"attachedFileName":"example.jpg","originalFileName":"example.jpg","disposable":false}]
------WebKitFormBoundaryAofpaWXja6BTaYQ9--

Response 200

{
  "success": true,
  "data": {
    "example.jpg": {
      "assetID": 697,
      "assetCDNURL": "https://d3jme5si7t6llb.cloudfront.net/assets/201427/IHp2jMI_1704987233847.jpg"
    }
  }
}

Formdata Sample

------WebKitFormBoundaryAofpaWXja6BTaYQ9
Content-Disposition: form-data; name="files"; filename="300x250_creative.zip"
Content-Type: application/zip

------WebKitFormBoundaryAofpaWXja6BTaYQ9
Content-Disposition: form-data; name="filesMetadata"

[{"attachedFileName":"300x250_creative.zip","originalFileName":"300x250.zip","disposable":false,"zipFile":true,"html5Creative":true}]
------WebKitFormBoundaryAofpaWXja6BTaYQ9--

Response 200

{
  "success": true,
  "data": {
    "300x250_creative.zip": {
      "assetID": 19234,
      "assetCDNURL": "https://d3jme5si7t6llb.cloudfront.net/assets/204876/OQ6NQ8B_1772197041498/index.html?cb=1",
      "dimensions": {
        "width": 300,
        "height": 250
      },
      "iframeHtml": "<iframe src=\"https://d3jme5si7t6llb.cloudfront.net/assets/204876/OQ6NQ8B_1772197041498/index.html?cb=1\" width=\"300\" height=\"250\" frameborder=\"0\" scrolling=\"no\" marginheight=\"0\" marginwidth=\"0\"></iframe>"
    }
  }
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Please pass File(s) metaData"
    }
  ]
}

TypeScript

import axios from "axios";
import * as fs from "fs";
import * as path from "path";
import FormData from "form-data";

interface FileMetadata {
  attachedFileName: string;
  originalFileName: string;
  disposable?: boolean;
  zipFile?: boolean;
  html5Creative?: boolean;
}

interface AssetResponse {
  assetID: number;
  assetCDNURL: string;
  dimensions?: {
    width: number;
    height: number;
  };
  iframeHtml?: string;
}

async function addAssets(filesMetadata: FileMetadata[], filePaths: string[]): Promise<any> {
  const form = new FormData();
  form.append("filesMetadata", JSON.stringify(filesMetadata));

  for (const filePath of filePaths) {
    const stream = fs.createReadStream(filePath);
    form.append("files", stream, path.basename(filePath));
  }

  const headers = {
    ...form.getHeaders(),
    Authorization: `Bearer [TOKEN]`, // replace with actual bearer token
    "x-iaa-ow-id": '[OWID]', // replace with your actual ow id
  };

  const response = await axios.post(
    "https://api.iqm.com/api/v3/asset",
    form,
    {
      headers,
      timeout: 10000,
      timeoutErrorMessage: 'Request timed out after 10 seconds'
    }
  );
  console.log(JSON.stringify(response.data));
  return response.data;
}

// Example: Upload a regular image asset
(async () => {
  const metadata: FileMetadata[] = [
    {
      attachedFileName: "example.png",
      originalFileName: "example.png",
      disposable: false
    }
  ];

  try {
    const result = await addAssets(metadata, ["example.png"]);
    console.log("Upload successful:", result);
  } catch (error) {
    console.error("Upload failed:", error);
  }
})();

// Example: Upload an HTML5 creative asset
(async () => {
  const metadata: FileMetadata[] = [
    {
      attachedFileName: "300x250_creative.zip",
      originalFileName: "300x250.zip",
      disposable: false,
      zipFile: true,
      html5Creative: true
    }
  ];

  try {
    const result = await addAssets(metadata, ["300x250_creative.zip"]);
    console.log("HTML5 Creative upload successful:", result);
  } catch (error) {
    console.error("Upload failed:", error);
  }
})();

---

Update Asset Details

PATCH

Update the details of an existing Asset by ID.

Path Parameters
assetId integer	Asset ID

Request Schema
storagePath string	File path of Asset
cdnUrl string	Asset CDN URL
disposable boolean	Indicates whether Asset is temporary and can be purged (true), default: true

JSON

Request Sample

{
  "storagePath": "string",
  "cdnUrl": "string",
  "disposable": true
}

Response 200

{
  "success": true,
  "data": {
    "statusCode": 200,
    "responseObject": {
      "message": "Asset updated successfully"
    }
  }
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          statusCode: number;
          responseObject: {
            message: string
          }
        }
      }
    }
  };
  401: {
    content: {
      "application/json": {
        success?: boolean;
        errorObjects?: {
          error?: string;
          reason?: string;
          field?: string;
        }[];
        data?: Record<string, never>;
      }
    }
  }
}

function updateAssetDetails(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://api.iqm.com/api/v3/asset/{assetId}',
    params: {
      path: {
        assetId: `number`,
      }
    },
    requestBody: {
      content: {
        "application/json": {
          storagePath?: `string`,
          cdnUrl?: `string`,
          disposable?: `boolean`,
        }
      }
    },
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Delete Asset

DELETE

Delete single Asset by ID.

Path Parameters
assetId integer	Asset ID

JSON

Response 200

{
  "success": true,
  "data": "Asset deleted successfully."
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: string
      }
    }
  };
  401: {
    content: {
      Authorization?: string;
      "X-IAA-OW-ID"?: string;
    };
    path: {
      assetId: number;
    }
  }
}

function deleteAsset(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://api.iqm.com/api/v3/asset/{assetId}',
    params: {
      path: {
        assetId: `number`
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}