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

## 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'
```

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