Iconik

Overview

Iconik is a cloud-native media asset management platform. By connecting Iconik to Mixpeek, you can automatically sync your media library — enabling search, classification, and analysis across video, image, and audio assets. Iconik uses the same connection sync pattern as all other Mixpeek storage integrations. Mixpeek polls Iconik for assets, downloads proxy files, and creates bucket objects with full metadata. It can also parse editorial project files into footage ↔ ad relationships (see Project-file linkage). Optionally, you can configure webhooks for real-time delete and update events.

Prerequisites

An Iconik account with assets
An Iconik App ID and Auth Token with read access to assets, proxies, and files
A Mixpeek account with an active namespace

Configuration

Connection-level fields

Field	Required	Description
`auth_token`	Yes	Iconik authentication token (JWT or API token)
`app_id`	Yes	Iconik application ID (UUID format)
`webhook_secret`	No	Shared signing secret for inbound Iconik webhooks. Required only if you want Mixpeek to cascade-delete objects when assets are deleted in Iconik (see Webhooks: delete and update).

Sync-level fields

Field	Required	Default	Description
`source_path`	No	`iconik://`	Sync all assets, or filter by collection
`sync_mode`	No	`continuous`	`initial_only` or `continuous`
`polling_interval_seconds`	No	300	How often to check for new/modified assets (continuous mode)
`skip_duplicates`	No	`true`	Skip assets already synced with the same modification time
`reconcile_on_sync`	No	`false`	Remove objects whose source assets no longer exist in Iconik
`provider_filters`	No	—	Filter by collection IDs, asset status, or media type

Setup

Create Iconik API credentials

In the Iconik admin panel, go to Admin > Integrations > Applications
Click Create Application
Copy the App ID and Auth Token — you’ll need both for the Mixpeek connection

Use a dedicated application for the Mixpeek integration rather than a personal token. Application tokens don’t expire when a user leaves the organization.

Create the connection in Mixpeek

In the Mixpeek Studio, go to Settings > Storage Connections > Add Connection and select Iconik.Or via the API:

from mixpeek import Mixpeek

client = Mixpeek(api_key="YOUR_API_KEY")

connection = client.organizations.connections.create(
    name="Iconik Production",
    provider_type="iconik",
    provider_config={
        "credentials": {
            "auth_token": "YOUR_ICONIK_AUTH_TOKEN",
            "app_id": "YOUR_ICONIK_APP_ID"
        }
    },
    test_before_save=True
)

print(connection.connection_id)  # e.g. conn_3010b0af974c8d83

import Mixpeek from "mixpeek";

const client = new Mixpeek({ apiKey: "YOUR_API_KEY" });

const connection = await client.organizations.connections.create({
  name: "Iconik Production",
  provider_type: "iconik",
  provider_config: {
    credentials: {
      auth_token: "YOUR_ICONIK_AUTH_TOKEN",
      app_id: "YOUR_ICONIK_APP_ID",
    },
  },
  test_before_save: true,
});

curl -X POST https://api.mixpeek.com/v1/organizations/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Iconik Production",
    "provider_type": "iconik",
    "provider_config": {
      "credentials": {
        "auth_token": "YOUR_ICONIK_AUTH_TOKEN",
        "app_id": "YOUR_ICONIK_APP_ID"
      }
    },
    "test_before_save": true
  }'

Save the returned connection_id.

Create a bucket with Iconik sync

Create a bucket and configure it to sync from your Iconik connection:

bucket = client.buckets.create(
    namespace_id="your-namespace-id",
    name="iconik-assets",
    description="Media assets from Iconik",
    blob_type="video"
)

sync = client.buckets.syncs.create(
    namespace_id="your-namespace-id",
    bucket_id=bucket.bucket_id,
    connection_id=connection.connection_id,
    source_path="iconik://",
    sync_mode="continuous",
    polling_interval_seconds=300,
    skip_duplicates=True
)

# Create bucket
curl -X POST https://api.mixpeek.com/v1/buckets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: YOUR_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket_name": "iconik-assets",
    "description": "Media assets from Iconik"
  }'

# Create sync config
curl -X POST "https://api.mixpeek.com/v1/buckets/$BUCKET_ID/syncs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: YOUR_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_YOUR_CONNECTION_ID",
    "source_path": "iconik://",
    "sync_mode": "continuous",
    "polling_interval_seconds": 300,
    "skip_duplicates": true
  }'

Verify ingestion

Monitor the sync status in Studio or via the API. Assets will be automatically downloaded (proxy files) and processed through your collection’s feature extractors.

curl "https://api.mixpeek.com/v1/buckets/$BUCKET_ID/syncs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: YOUR_NAMESPACE"

Collection traversal and directory mapping

When you specify collection_ids in provider_filters, the connector recursively traverses the Iconik collection hierarchy (up to 10 levels deep) and maps the collection tree to a directory_path on each synced object. For example, an Iconik collection structure like:

Brand Campaign (root collection)
├── 01 Product Shots
│   ├── 01 Ingredients
│   └── 08 Outros
├── 02 UGC Footage
│   ├── 01 Talent (Before)
│   │   ├── 00 Young
│   │   └── 01 Mature
│   └── 02 Talent (After)
└── 03 High-End Footage

produces objects with directory_path values like:

Brand Campaign/01 Product Shots/08 Outros
Brand Campaign/02 UGC Footage/01 Talent (Before)/01 Mature
Brand Campaign/03 High-End Footage

This path is available in source_metadata.directory_path and can be used for filtering in retrievers.

Glob filtering with `path_patterns`

Use path_patterns in provider_filters to include only assets whose directory_path matches one or more glob patterns. Patterns use standard fnmatch syntax and are case-insensitive.

{
  "provider_filters": {
    "collection_ids": ["15202dd4-9b00-11ef-8481-fedcde789d87"],
    "media_type": "video",
    "path_patterns": ["*UGC*", "*High-End*"]
  }
}

Pattern	Matches
`UGC`	Any path containing “UGC”
`Brand Campaign/01*`	All paths under “01 Product Shots”
`Talent`	Before and After talent folders
`Brand Campaign//01`	First subfolder in each top-level category
`Outros`	Only the Outros folder

Iconik metadata on objects and retriever results

When the connector syncs an Iconik asset into a bucket, it captures metadata from two sources and exposes them as source_metadata on the resulting bucket object.

Asset-level fields

These come from the Iconik asset record directly:

Field	Description
`iconik_asset_id`	Iconik asset UUID
`title`	Asset title
`status`	Asset status (e.g., `ACTIVE`)
`media_type`	Media type (`video`, `image`, `audio`)
`date_created`	Asset creation timestamp
`date_modified`	Last modification timestamp
`date_imported`	When the asset was imported into Iconik
`is_online`	Whether the asset is currently online
`archive_status`	Archive state of the asset
`analyze_status`	Iconik analysis status
`category`	Asset category
`type`	Iconik object type (e.g., `ASSET`)
`external_id`	External reference ID
`created_by_user`	Iconik user ID who created the asset
`updated_by_user`	Iconik user ID who last modified the asset
`directory_path`	Collection hierarchy path (see above)
`thumbnail_url`	Keyframe/thumbnail URL (if available)
`proxy_url`	Pre-signed proxy download URL

Custom metadata from views

The connector automatically discovers all metadata views configured in your Iconik workspace and fetches custom metadata for each asset across all views. Fields are flattened from Iconik’s nested field_values format into simple key-value pairs. Example fields (depending on your Iconik configuration):

Field	Description
`Keywords`	Tag cloud / keywords
`ProjectName`	Project or campaign name
`Category`	Asset category
`Description`	Asset description
`FolderNamePaths`	Iconik folder path metadata
`CreatorName`	Creator / uploader name

All populated custom metadata fields are included automatically — no configuration needed. If you want to limit metadata to a specific view, set metadata_view_id in the connection’s provider_config:

{
  "provider_config": {
    "credentials": { "auth_token": "...", "app_id": "..." },
    "metadata_view_id": "97324f86-55ba-11ef-877b-c2a940a89d9c"
  }
}

Project-file linkage

Beyond per-asset metadata, the Iconik connector captures the relationships between assets that come from editorial (NLE) projects. For Iconik NLE_PROJECT assets (e.g. an Adobe Premiere project — one per produced ad), the connector reads Iconik’s relations — the media assets the project uses, already parsed by Iconik — and attaches typed, directed edges to the object — Mixpeek’s first-class model for customer-owned relationships between objects. When the project file itself is downloadable (native .prproj, .fcpxml, or an xmeml .xml export), the connector additionally parses it to enrich each edge with clip order and timeline ticks — matched to the relations by footage file name. This is how an assembled ad is linked to every piece of footage it uses, with its position in the cut — captured as a saved value on the object at ingestion, not recomputed at query time.

What gets captured

For an NLE project asset, the connector emits one edge per related media asset, stored at the root of the object under edges:

Edge field	Description
`type`	`uses_footage` for related video assets; `uses_media` for audio/image/other (with `attributes.media_type`)
`target_object_id`	The footage object this relation references, resolved from the source asset id. Until that footage object exists in Mixpeek, the edge preserves the source asset reference and is flagged `attributes.target_unresolved` so a later reconcile can rewrite it.
`direction`	`out` (ad → footage)
`attributes.iconik_asset_id`	The related Iconik asset’s id (the durable foreign key)
`attributes.clip_order`	The clip’s order within the ad sequence (1-based; from the project-file parse)
`attributes.start_ticks_in` / `start_ticks_out`	Clip position in Adobe ticks (`254,016,000,000` per second). `attributes.tick_semantics` says what they measure: `"timeline"` (position in the ad — native `.prproj`) or `"source"` (in/out within the source footage — `xmeml` exports)

The connector also sets two root-level signals on the ad object:

Field	Description
`is_final_ad`	`true` when the asset is an assembled/produced ad (a project file with clips) — distinguishing it from raw pre-production footage
`ad_clip_count`	Number of footage clips composited into the ad

Plain media assets (raw footage) get no edges and pay no extra API calls — linkage capture is gated to NLE project assets. Everything is fully fail-open: a relations error or a missing/malformed project file never blocks asset ingestion (edges without a parseable project file simply carry no tick attributes).

Edges and these signals are customer-owned data and live at the object root, never under _internal. They flow automatically from the object through your collections into the document’s search payload, so they are available to retrievers.

Traversing the relationships

Once footage↔ad edges are on your documents, the traverse_edge retriever stage follows them at query time — e.g. starting from an ad, fetch every piece of footage it uses, carrying the clip order and start-ticks of each:

{
  "stage_id": "traverse_edge",
  "parameters": { "edge_type": "uses_footage", "direction": "out" }
}

This linkage is a generalizable capability of Mixpeek’s source-adapter framework — any connector whose source carries a companion/sidecar file (an NLE project, an XMP sidecar, a per-object .json) can populate edges the same way. The Adobe Premiere xmeml parser is the Iconik-specific piece.

File resolution

The Iconik connector resolves downloadable files in priority order:

Proxy URL — pre-signed download URL from GET /files/v1/assets/{id}/proxies/
Original file URL — download URL from GET /files/v1/assets/{id}/formats/

Per asset, the connector makes: one asset metadata call, one proxy URL resolution call, and one metadata view call per discovered view (views are cached after the first asset).

Webhooks: delete and update

Mixpeek handles Iconik webhook events to keep your index in sync in real time, without waiting for the next poll cycle.

How it works

Iconik POSTs events to a Mixpeek endpoint that includes your connection_id.
Mixpeek verifies the X-Iconik-Signature header against the webhook_secret stored on that connection.
assets.asset_deleted — Mixpeek finds every object synced from that Iconik asset and deletes them, cascading through OBJECT_DELETED to remove derived documents from your collections.
assets.asset_updated — Mixpeek re-evaluates the asset against each sync config’s metadata_filters. If the asset no longer matches and reconcile_on_sync is enabled, the corresponding objects are unindexed.
assets.asset_created — Acknowledged; the asset will be picked up on the next sync poll.

Setup

Add a webhook secret to the connection

Pick any high-entropy string (32+ chars) and store it as webhook_secret in the Iconik connection’s credentials. You can set it at create time or patch an existing connection.

cURL

curl -X PATCH https://api.mixpeek.com/v1/organizations/connections/{connection_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config": {
      "credentials": {
        "auth_token": "...",
        "app_id": "...",
        "webhook_secret": "your-32-char-random-string"
      }
    }
  }'

In the Iconik admin panel:

Go to Admin > Integrations > Webhooks
Click Create Webhook
Set the URL to https://api.mixpeek.com/v1/webhooks/iconik/{connection_id} — replace {connection_id} with the Mixpeek connection ID
Subscribe to events: Asset Created, Asset Updated, Asset Deleted
Save the webhook

Verify with a test delete

Delete a synced asset in Iconik and confirm the corresponding object disappears from your bucket. The webhook returns a JSON body documenting what it did:

{
  "received": true,
  "event_type": "assets.asset_deleted",
  "handled": true,
  "asset_id": "e0f0ec84-4d63-11f1-99fa-b221c0ff30c8",
  "deleted_objects": 1
}

Signature format

Mixpeek verifies inbound Iconik webhooks using HMAC-SHA256:

Header: X-Iconik-Signature: <hex_hmac_sha256>
HMAC computed as HMAC_SHA256(webhook_secret, raw_body) over the exact raw bytes of the request body.
Signatures are compared with hmac.compare_digest to avoid timing attacks.

Response codes

Status	Meaning
`200`	Event received. `handled` is `true` for delete/update/create, `false` for unrecognized event types.
`400`	Connection has no `webhook_secret` configured, or payload is not valid JSON.
`401`	`X-Iconik-Signature` is missing, malformed, or the HMAC doesn’t match.
`404`	`connection_id` in the URL is not an Iconik connection.

Modification detection

When skip_duplicates is true (default), re-syncing the same Iconik account skips assets whose date_modified hasn’t changed since the last sync. This makes continuous syncing efficient — only new or modified assets are re-processed. When skip_duplicates is false, every asset is re-downloaded and re-processed on each sync cycle, replacing existing objects with fresh ones.

Reconciliation

When reconcile_on_sync is enabled, each sync cycle checks whether previously synced assets still exist in Iconik. Assets that have been deleted from Iconik are automatically removed from your bucket.

curl -X POST "https://api.mixpeek.com/v1/buckets/$BUCKET_ID/syncs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: YOUR_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_YOUR_CONNECTION_ID",
    "source_path": "iconik://",
    "reconcile_on_sync": true
  }'

Reconciliation checks each indexed object against the Iconik API on every sync cycle. For large libraries (10k+ assets), this adds API calls proportional to the number of indexed objects. Use it when stale objects are unacceptable.

Provider filters

Filter which Iconik assets get synced using provider_filters:

{
  "provider_filters": {
    "collection_ids": ["col_abc", "col_def"],
    "status": "ACTIVE",
    "media_type": "video"
  }
}

Filter	Description
`collection_ids`	Only sync assets from specific Iconik collections
`status`	Filter by asset status (e.g., `ACTIVE`)
`media_type`	Filter by media type (`video`, `image`, `audio`)

Sync modes

Mode	Description
`initial_only`	Sync all current assets once
`continuous`	Poll for new/modified assets at the configured interval

Troubleshooting

401 Unauthorized on connection test

Verify your App ID and Auth Token are correct. The App ID is a UUID (e.g., e0f0ec84-4d63-...). Tokens can be regenerated in the Iconik admin panel under Admin > Integrations > Applications.

Assets not appearing in sync

Only assets with proxy files or original files available are synced. Check that your Iconik credentials have read access to the files API (GET /files/v1/assets/{id}/proxies/).

Duplicate objects appearing

Ensure skip_duplicates is set to true on your sync config. This deduplicates assets by their Iconik asset ID and modification timestamp.

Deleted assets still in bucket

Enable reconcile_on_sync on your sync config, or configure webhooks to handle assets.asset_deleted events for real-time cleanup.

Webhook 401 errors

The X-Iconik-Signature header doesn’t match. Verify the webhook_secret on your Mixpeek connection matches what Iconik is using to sign payloads.

Buckets — How bucket sync works
Webhooks — How outbound Mixpeek webhooks work
Storage Connections API — Full API reference

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

Overview

Prerequisites

Configuration

Connection-level fields

Sync-level fields

Setup

Collection traversal and directory mapping

Glob filtering with `path_patterns`

Iconik metadata on objects and retriever results

Asset-level fields

Custom metadata from views

Project-file linkage

What gets captured

Traversing the relationships

File resolution

Webhooks: delete and update

How it works

Setup

Signature format

Response codes

Modification detection

Reconciliation

Provider filters

Sync modes

Troubleshooting

​Overview

​Prerequisites

​Configuration

​Connection-level fields

​Sync-level fields

​Setup

​Collection traversal and directory mapping

​Glob filtering with path_patterns

​Iconik metadata on objects and retriever results

​Asset-level fields

​Custom metadata from views

​Project-file linkage

​What gets captured

​Traversing the relationships

​File resolution

​Webhooks: delete and update

​How it works

​Setup

​Signature format

​Response codes

​Modification detection

​Reconciliation

​Provider filters

​Sync modes

​Troubleshooting

​Related

Overview

Prerequisites

Configuration

Connection-level fields

Sync-level fields

Setup

Collection traversal and directory mapping

Glob filtering with `path_patterns`

Iconik metadata on objects and retriever results

Asset-level fields

Custom metadata from views

Project-file linkage

What gets captured

Traversing the relationships

File resolution

Webhooks: delete and update

How it works

Setup

Signature format

Response codes

Modification detection

Reconciliation

Provider filters

Sync modes

Troubleshooting

Related