Iconik - Mixpeek

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. 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

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
)

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:

Kitsch (root collection)
├── 01 Client Essentials
│   ├── 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:

Kitsch/01 Client Essentials/08 Outros
Kitsch/02 UGC Footage/01 Talent (Before)/01 Mature
Kitsch/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”
`Kitsch/01*`	All paths under “01 Client Essentials”
`Talent`	Before and After talent folders
`Kitsch//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. Common fields (depending on your Iconik configuration):

Field	Description
`Keywords`	Tag cloud / keywords
`ClientName`	Client or brand name
`ClientCode`	Client code
`TalentName`	Talent/creator name
`SKUs`	Product SKUs
`Bundle`	Product bundle
`FolderNamePaths`	Iconik folder path metadata
`HandlerName`	Handler/producer name
`Gender`, `HairType`, `Color`	Talent attributes

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"
  }
}

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

Integrations

Documentation Index

​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

​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

File resolution

Webhooks: delete and update

How it works

Setup

Signature format

Response codes

Modification detection

Reconciliation

Provider filters

Sync modes

Troubleshooting

Related