> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# iconik

> Connect your iconik media library to Cloudglue

Connect your [iconik](https://www.iconik.io) media asset management account to
use your video and audio assets with Cloudglue APIs.

## Adding the iconik Data Connector

1. In iconik, create an Application Token: go to **Admin → Settings →
   Application Tokens**, enter an application name (e.g. "Cloudglue"), select
   the user the token should act as, and click **Add**. Copy both the
   **App-ID** and the **Token** — iconik shows the token only once.
2. Navigate to the [Data Connectors page](https://app.cloudglue.dev/home/data-connectors)
   in the Cloudglue app.
3. Click the iconik data connector card and enter the App-ID and Auth Token.
   Keep the default iconik URL (`https://app.iconik.io`) unless your iconik
   system is served from another domain.
4. Verify the connection by checking for the **Connected** indicator on the
   card.

<Note>
  The user the Application Token acts as determines which assets Cloudglue can
  see. The token needs read access to assets, formats, files, and proxies (e.g.
  the `can_read_assets`, `can_read_formats`, `can_read_files`, and
  `can_read_proxies` roles).
</Note>

<Info>
  **Need help setting up your data connector?** Contact our team directly for
  assistance with the setup process.
</Info>

## Using iconik with Cloudglue

To use iconik assets with Cloudglue, use the `iconik://asset/{asset_id}`
prefix in your Cloudglue API requests.

Example:

```bash theme={null}
iconik://asset/b947e9da-ec52-11ea-b571-0af7c14f78f9
```

**Example API Request to get [a multimodal description](/api-reference/endpoint/describe/post) of an asset:**

```bash theme={null}
curl --request POST \
  --url https://api.cloudglue.dev/v1/describe \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "iconik://asset/b947e9da-ec52-11ea-b571-0af7c14f78f9",
  "enable_summary": true,
  "enable_speech": true,
  "enable_visual_scene_description": true,
  "enable_scene_text": true
}'
```

<Note>
  When an asset is imported, Cloudglue downloads the asset's web proxy (a
  compact, web-ready rendition) when one is available, and falls back to the
  ORIGINAL file otherwise. Proxies are ideal for AI analysis — much smaller than
  camera originals with no meaningful quality loss for understanding tasks. The
  rendition used is recorded as `ingested_rendition` in the file's
  `source_metadata`.
</Note>

## Browsing and filtering assets

[`GET /data-connectors/{id}/files`](/api-reference/endpoint/data-connectors/list-files)
lists active video and audio assets from your iconik account, newest first.
`from`/`to` filter by asset creation date, and `title_search` runs a full-text
search on asset titles.

```bash theme={null}
curl --request GET \
  --url 'https://api.cloudglue.dev/v1/data-connectors/YOUR_CONNECTOR_ID/files?title_search=interview&from=2026-01-01' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

A result set can span multiple pages: when `has_more` is true, pass the
response's `next_page_token` back as `page_token` (with the same filter
parameters) until it returns null.

Each listed asset includes a `thumbnail_url` — the asset's keyframe as a
signed iconik URL that expires within hours. Use it to render previews while
browsing; never store it (imported files get a durable Cloudglue-hosted
thumbnail instead — see [Poster thumbnails](#poster-thumbnails)).

## Source metadata

When an iconik asset is imported, Cloudglue captures the asset's source
metadata onto the resulting file under `source_metadata`: the asset id and
title, media type, creation/modification timestamps, duration, the rendition
that was ingested (`proxy` or `original`), and a deep link back to the asset
in iconik. Signed download URLs are never stored. The `source_metadata` field
is returned on the [file object](/api-reference/endpoint/files/get-id).

### Custom metadata views (`iconik_metadata`)

Values from your iconik **metadata views** — the customer-defined custom
fields you see on an asset's "Update Metadata" panel (e.g. a screening view's
UGC Title, Description, Keywords, Categories, Ratings) — are captured under
`source_metadata.iconik_metadata`, keyed by field name. Only populated fields
are stored (iconik reports every field defined across your domain's views,
most of them empty), and values keep iconik's array wrapping — including for
single-value fields:

```json theme={null}
{
  "source_type": "iconik",
  "iconik_asset_id": "1c2090a4-…",
  "title": "5cdc99d9-….mp4",
  "iconik_metadata": {
    "uGCTitle": ["Do you have it?"],
    "keywords": ["whoops fail kicking hitting father daughter"],
    "aFVRating": ["5 Minus"],
    "emotionMultiPicklist": ["Cute", "Funny", "Happy", "Thrill"]
  }
}
```

This makes iconik custom metadata a first-class search surface:

* In [metadata collections](/api-reference/endpoint/collections/post), every
  custom field is flattened into the file's indexed search document — so a
  semantic or `doc_lexical` search over descriptions, keywords, and
  categories finds the right assets without downloading any media.
* Any search or list endpoint accepting `source_metadata` filters can target
  individual fields with `source_metadata.iconik_metadata.<FieldName>` paths
  (use `ContainsAny` for multi-value fields like keyword lists).

Field names are whatever your iconik views define — check a file's
`source_metadata` (or the
[source-metadata preview](/api-reference/endpoint/data-connectors/source-metadata))
to see the exact keys for your library.

[`GET /data-connectors/{id}/source-metadata`](/api-reference/endpoint/data-connectors/source-metadata)
previews an asset's source metadata without importing it:

```bash theme={null}
curl --request GET \
  --url 'https://api.cloudglue.dev/v1/data-connectors/YOUR_CONNECTOR_ID/source-metadata?url=iconik://asset/b947e9da-ec52-11ea-b571-0af7c14f78f9' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Poster thumbnails

iconik assets added to [metadata collections](/api-reference/endpoint/collections/post)
are indexed without downloading any media — but they still get a visual
identity: Cloudglue copies the asset's **poster keyframe** (your custom
keyframe if one is set, otherwise the largest still) into Cloudglue-hosted
storage and returns it as the file's `thumbnail_url`. This happens
automatically at import, and
[`POST /files/{file_id}/sync`](/api-reference/endpoint/files/sync-source-metadata)
backfills a thumbnail for iconik files that don't have one yet.

Fully ingested files generate thumbnails from the media itself, so the poster
copy only applies when no thumbnail exists. iconik's own keyframe URLs are
signed and short-lived, and — like download URLs — are never stored.

## UI Importing for Testing

Use the Cloudglue integration UI to quickly import iconik assets for testing
your endpoints.

To access this page, visit [our app](https://app.cloudglue.dev/home/data-connectors)
and click on **Select Videos** on the iconik connector. You can browse recent
assets, search by title, and import up to 20 assets at a time.

## Managing Access

You maintain full control over your data access. To remove the iconik Data
Connector, visit the [Data Connectors page](https://app.cloudglue.dev/home/data-connectors)
and click **Disconnect** under iconik.

Once removed:

* You cannot import new assets into Cloudglue until you reconnect.
* Any assets you previously imported will remain in Cloudglue. These can be
  viewed and deleted from [File Management](https://app.cloudglue.dev/home/files).

## Security

Cloudglue uses an iconik Application Token to securely access your assets.
This approach:

* **Maintains your control** - You own and manage the connector. Revoke the
  Application Token in iconik at any time to stop Cloudglue from accessing
  your assets.
* **Scopes access** - The token acts as the iconik user you selected, so
  Cloudglue can only see the assets that user can see.