Iconik API Basics: Exploring Assets, Metadata, and Jobs

Written by Clarisse Eynard

Managing multimedia assets presents both media companies and content creators with significant challenges. These include the complexities of organizing content storage solutions and ensuring seamless sharing and collaboration amidst a rapidly evolving media landscape. Iconik is a comprehensive cloud based media management and collaboration tool designed to address these challenges by streamlining the organization, storage, and sharing of multimedia content.

The subsequent sections present basic Iconik concepts such as assets, metadata, and jobs, followed by an exploration of the basic Iconik API endpoints.

Understanding Key Iconik Concepts

Assets

An asset consists of one or more files and is automatically generated upon upload. It goes beyond a simple file reference, as it also encapsulates metadata, access rights, comments, and associations with other files and collections. These associations can vary, such as parent-child relationships where one asset acts as the parent to another, or collection relationships, which are automatically established for all collections an asset is added to.

Metadata

Iconik uses a proprietary metadata structure to provide enhanced user flexibility. This structure comprises three distinct levels:

1. Metadata Field: Admins define each field, specifying its type and attributes. For example, a description might be an open text field with a specific character limit.

2. Metadata Views: These views manage metadata fields as forms, allowing administrators to customize the display for different user groups. When multiple fields are present, administrators can choose to display select subsets to individual user groups.

3. Metadata Categories: These categories determine where a view can be used within Iconik. Administrators can designate specific views for searches, collections, assets, and more.

Administrators have the authority to define which metadata users can access or utilize within the system.

Job

A job handles tasks that require time or multiple steps to complete. Each job is assigned a status, such as ‘Started’, ‘Finished’, or ‘Failed’. Moreover, a job can comprise subjobs, smaller tasks with their own status and history, which are reflected in the parent job.

Below are some examples of tasks commonly managed within jobs:

1. Transcode: Converting a video, audio, or image file to create a preview
2. Transfer: Copying a file from one location to another
3. Delete: Removing an asset and its associated files

Using the API

Below is an overview of the main endpoints related to assets, metadata, and jobs, accompanied by Python example functions. Before using these functions with the REST API, users must first establish access by obtaining appropriate credentials from an admin or an admin account on the Iconik system.

All endpoints in the REST API share the same base URL to which calls (GET, POST, PATCH, PUT, DELETE) are directed, along with mandatory identification parameters specified in the header (App-ID and Auth-Token). 

The base URL is to be included in the endpoints that will be presented later.

base_url = ‘https://app.iconik.io/API‘

Below are instructions on how to recover the App-ID and the Auth-Token.

• Go to the admin panel and select Settings/Application Tokens from the side menu 

• Create a new application or use an already existing

• Create a new authentication token and copy the app id from this page

Users are required to store this data in a secure way so it can be reused at a later time.

To facilitate the calls, a class can be created to manage the API base. Below is an example in Python:

import requests # Define your Iconik credentials here ICONIK_APP_ID_KEY = ‘your_app_id’ ICONIK_AUTH_TOKEN_KEY = ‘your_auth_token’ class IconikAPIService:    base_url = ‘https://app.iconik.io/API’    app_header: dict    def __init__(self) -> None:        app_id = ICONIK_APP_ID_KEY        auth_token = ICONIK_AUTH_TOKEN_KEY        self.app_header = {            ‘App-ID’: app_id,            ‘Auth-Token’: auth_token,        }    def get(self, path: str):        return requests.get(f”{self.base_url}{path}”, headers=self.app_header)    def post(self, path: str, body: dict):        return requests.post(f”{self.base_url}{path}”, headers=self.app_header, json=body)    def patch(self, path: str, body: dict):        return requests.patch(f”{self.base_url}{path}”, headers=self.app_header, json=body)    def put(self, path: str, body: dict):        return requests.put(f”{self.base_url}{path}”, headers=self.app_header, json=body)    def delete(self, path: str):        return requests.delete(f”{self.base_url}{path}”, headers=self.app_header)

---

GET

This section describes the main endpoints used to retrieve data.

To retrieve all assets: 

/assets/v1/assets/

To retrieve a particular asset via its ID and its corresponding information: 

/assets/v1/assets/{asset_id}/

Users can also append ?include_collections=true at the end of the endpoint. While not mandatory, it facilitates retrieval of the collections in which the assets are located. Additionally, appending ?include_users=true enables users to retrieve information about the users who have interacted with the asset.

Below is an example of this using the IconikAPIService class shown above:

def get_asset(asset_id: str, with_associated_data = True):  response = IconikAPIService().get(f”/assets/v1/assets/{asset_id}/?include_collections=true”)    if response.status_code == 404:        return None    elif response.status_code != 200:        raise Exception(f”API Service Error: {response.reason}”)    return response.json()

To retrieve metadata from an asset via its ID: 

/metadata/v1/assets/{asset.id}/

To retrieve the files linked to an asset via its ID:

/files/v1/assets/{asset_id}/files

To retrieve an asset’s proxies via its ID:

/files/v1/assets/{asset_id}/proxies

Quick reminder ⇒ a proxy is a low resolution version, used for preview, it’s faster to load, less heavy but has a lower quality than the asset.

To retrieve a job:

/jobs/v1/jobs/{job_id}/

To retrieve the list of all metadata fields:

/metadata/v1/fields/

To retrieve information from a metadata field:

/metadata/v1/fields/{field_name}/

To retrieve the list of all metadata views:

/metadata/v1/fields/

Quick reminder ⇒ views are used to organize fields.

---

DELETE

This section presents the main endpoints used to delete data.

Deletes an asset using its ID:

/assets/v1/assets/{asset_id}/

Deletes a specific metadata field:

/metadata/v1/fields/{field_name}/

Deletes a job using its ID:

/jobs/v1/jobs/{job_id}/

Here is an example of a function using this endpoint:

def delete_job(job_id: str) -> bool:    response = IconikAPIService().delete(f”/jobs/v1/jobs/{job_id}/”)    if response.status_code == 404:        return False    elif response.status_code != 204:        raise Exception(f”API Service Error: {response.reason}”)    return True

---

POST

This section presents the main endpoints used to create new data.

Creates an asset:/assets/v1/assets/

Parameter: title, type, status, is_online…

Associates a new proxy with an asset:

/files/v1/assets/{asset.id}/proxies/

Associates a new file with an asset:

/files/v1/assets/{asset.id}/files/

Associates a new fileset with an asset:

/files/v1/assets/{asset.id}/file_sets/

Quick reminder ⇒ a fileset is a collection of files.

Associates a new format with an asset:

/files/v1/assets/{asset.id}/formats/

Quick reminder ⇒ a format contains references to files or filesets.

Below is a diagram illustrating a single format asset with two components (video and audio). This asset is associated with a single fileset and corresponds to a single file.

Creates a new job

/jobs/v1/jobs/

The title, status, and type of the new job must be specified at a minimum. Below is an example of a function that creates an ANALYZE job.

def create_job(self, asset_name: str):    response = self.iconik_api.post(        “/jobs/v1/jobs/”,        {            ‘title’: f”Create {asset_name} subclip”,            ‘status’: IconikJobStatus.READY,            ‘type’: IconikJobType.ANALYZE,        }    )    if response.status_code == 404:        return None    elif response.status_code != 201:        raise Exception(f”API Service Error: {response.reason}”)    return response.json()

To create a new metadata field:

/metadata/v1/fields/

---

PATCH

In this section, we will see the main endpoints to update already existing data.

Updates an asset:

/assets/v1/assets/{asset.id}

Updates a job:

/jobs/v1/jobs/{job.id}/

Updates a specific metadata field:

/metadata/v1/fields/{field_name}/

---

PUT

In this section, we will see the main endpoints to update already existing data.

Updates an asset:

/assets/v1/assets/{asset.id}

Updates a job:

/jobs/v1/jobs/{job.id}/

Updates a specific metadata field:

/metadata/v1/fields/{field_name}/

FAQ

What is the difference between put and patch?

In Iconik API, put and patch have the same behavior: they update or completely replace an existing resource.

Why is there V1 in all the endpoints?

The API is versioned and depending on the versions the parameters can be very different so we have to specify the version we want to use.

Where to find more information?

More information can be found in Iconik’s official documentation: https://app.iconik.io/docs/api.html

About TrackIt

TrackIt is an international AWS cloud consulting, systems integration, and software development firm headquartered in Marina del Rey, CA.

We have built our reputation on helping media companies architect and implement cost-effective, reliable, and scalable Media & Entertainment workflows in the cloud. These include streaming and on-demand video solutions, media asset management, and archiving, incorporating the latest AI technology to build bespoke media solutions tailored to customer requirements.

Cloud-native software development is at the foundation of what we do. We specialize in Application Modernization, Containerization, Infrastructure as Code and event-driven serverless architectures by leveraging the latest AWS services. Along with our Managed Services offerings which provide 24/7 cloud infrastructure maintenance and support, we are able to provide complete solutions for the media industry.

About Clarisse Eynard