Asset API

The Asset API streamlines the management and storage of assets in the system, such as images, PDF files, and HTML5 creative assets (ZIP files). This service plays a critical role in handling media uploads, temporary storage, and coordination with other services (such as the Creative API) for final storage and metadata management.

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

More resources

• Creative ad specs and requirements Help Center article

Authentication

Use the following header parameters for all requests:

Headers
Authentication string required	Authentication bearer token. See Sign up and authenticate.
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 a 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);
}