Menu

Mattering Automations ImageKit integration

Connect ImageKit to Mattering Automations: upload from URL, media library search, file and folder management, version history with restore, bulk tagging, custom metadata fields, technical metadata reads, and cache purge as workflow steps, authenticated with one private API key.

The Mattering Automations ImageKit integration adds ImageKit's media library and Upload APIs to your automation canvas: list and search assets with the searchQuery language, read and update file details, copy, move, and rename files and folders, walk and restore file version history, add and remove tags in bulk, define custom metadata fields and write their values per file, read technical metadata like EXIF and perceptual hashes, purge the CDN cache and poll the purge to completion, read account usage and delivery analytics, and upload new files by handing ImageKit a URL it fetches server-side.

The credential is your ImageKit private API key, applied as HTTP Basic auth with the key as the username and an empty password, the same on the management host (api.imagekit.io) and the upload host (upload.imagekit.io). The key lives in the ImageKit dashboard under Developer options, then API keys. The public key on the same screen authenticates nothing server-side, and this integration rejects a stored public key with a plain error rather than letting every node fail with a 401. Setup takes a few minutes, and this guide walks each step and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried. Of the 32 nodes, 11 read and 21 act, and five carry a destructive flag: ImageKit: Delete File, ImageKit: Delete Files (Bulk), ImageKit: Delete File Version, ImageKit: Delete Folder, and ImageKit: Delete Custom Metadata Field. ImageKit deletes are permanent, with no trash and no restore endpoint, delete folder removes everything inside without refusing a non-empty folder, and deleting a custom metadata field permanently retires its name. Some surfaces are deliberately absent: the beta V2 upload endpoint is a client-side JWT flow so V1 carries uploads here, saved-extension configuration and the beta account origin and URL-endpoint management APIs are infrastructure admin, and ImageKit's API has no webhook management endpoints (webhook targets are configured in the ImageKit dashboard), so there are no webhook nodes to build.

Before you start

  • An ImageKit account. ImageKit's pricing page lists a free plan that includes the media library and API access, so the integration can be set up and exercised without a paid subscription.
  • Access to the account's private API key: in the ImageKit dashboard under Developer options, then API keys. If you are on a team account, you need enough dashboard access to view the developer keys.
  • A Mattering workspace with access to the Automations app.
  • Optional: your URL endpoint (it looks like ik.imagekit.io/your_id) if you want it saved on the credential for reference when building delivery URLs. No node requires it: the nodes that take delivery URLs get them from ImageKit: List Files output.

Get your ImageKit private API key

ImageKit authenticates server-side API requests with HTTP Basic auth: the private API key is the username and the password is empty. One key covers everything this integration does, on both the management and upload hosts. The dashboard shows two keys side by side, and only one of them works here: the private key, which starts with private_. The public key (public_) exists for client-side upload signature flows and cannot authenticate API calls.

Sign in to the ImageKit dashboard at imagekit.io.
Open Developer options in the dashboard navigation, then API keys.
Copy the Private key value. It starts with private_.
Do not copy the public key. It starts with public_ and authenticates nothing server-side. This integration checks the prefix and rejects a stored public key with an error telling you to use the private key, so if you see that error, this step is the fix.
The private key grants full API access to the account's media library, including permanent deletes. Treat it like a password: store it only in the Mattering credential, and if it leaks, regenerate it in the ImageKit dashboard and update the credential.

Connect ImageKit to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose ImageKit from the list.
Click Create new credential, paste the private key into Private API Key, and save. The URL Endpoint field is optional and for reference only.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering lists one file from your media library, a read that succeeds even on an empty library, so a pass proves the key is valid and a 401 means the key is wrong, revoked, or the public one.
Click Connect. All 32 ImageKit nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: an ImageKit section should list the query and action nodes. Drop ImageKit: List Files onto the canvas and run a test step. It is the integration's health check and its backbone at once: a valid key returns an array of assets (possibly empty on a fresh account), and the fileId, filePath, folderPath, and url values in its output are what every other ImageKit node asks for. Its type parameter switches what it lists: files, file versions, folders, or all, and the folder mode is what fills the folder pickers on the copy, move, and upload nodes.

If the library has at least one file, run ImageKit: Get File Details with a fileId from the list to see a full asset record, and ImageKit: Get Account Usage with a short date range to confirm the account-level reads. Everything in this verify path is read-only: it cannot reach the five destructive nodes or change a single asset, so it is safe to re-run whenever you rotate the key.

Node reference

32 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 11

ImageKit: Get Account Usage

imagekit_get_usage

Read aggregate account usage between two dates: bandwidth bytes, media library storage bytes, video processing units, extension units, and original cache storage. The range covers startDate up to but NOT including endDate, must stay under 90 days, and returns one total per metric for the whole range (no per-day breakdown). Responses are cached by ImageKit for several hours.

ImageKit: Get Bulk Job Status

imagekit_get_bulk_job_status

Check an asynchronous folder job (copy, move, or rename): Pending or Completed, plus the purgeRequestId when a rename requested a cache purge.

ImageKit: Get File Details

imagekit_get_file

Fetch the current version of one file in full: URL, thumbnail, dimensions, tags, AI tags, custom metadata, version info, and publication state.

ImageKit: Get File Metadata

imagekit_get_file_metadata

Read the technical metadata of an uploaded file: dimensions, format, density, transparency, perceptual hash (pHash), and full EXIF blocks for images; codec and duration details for video.

ImageKit: Get File Version Details

imagekit_get_file_version

Fetch the details of one specific version of a file, including its own URL with the version query string.

ImageKit: Get Metadata from URL

imagekit_get_metadata_from_url

Read the same technical metadata (EXIF, pHash, dimensions) for any delivery URL served through the account, including transformed URLs.

ImageKit: Get Purge Status

imagekit_get_purge_status

Check a cache purge request: Pending or Completed.

ImageKit: Get Usage Analytics

imagekit_get_usage_analytics

Read delivery analytics between two dates (both inclusive, span under 90 days; a beta API): request and bandwidth totals, status code and error breakdowns, top 404 assets, cache hit/miss counts, and per-country and per-format splits. All figures are totals for the whole range; there is no per-day series. Check generatedAt for data freshness.

ImageKit: List Custom Metadata Fields

imagekit_list_custom_metadata_fields

List the account's custom metadata field definitions (name, label, and value schema). The id from here feeds the update and delete field nodes; the names key the customMetadata values on upload and update file.

ImageKit: List File Versions

imagekit_list_file_versions

List every version of a file, newest first, with each version's versionInfo.id (the versionId the per-version nodes take), URL, size, and timestamps.

ImageKit: List Files

imagekit_list_files

List and search the media library: files, file versions, or folders, with sorting, folder scoping, and ImageKit's searchQuery language for advanced filters. Returns a bare array of asset objects; the fileId, filePath, folderPath, and url values here feed every other ImageKit node. Also the credential health check to run first in any ImageKit automation.

Action nodes 21

ImageKit: Add Tags (Bulk)

imagekit_add_tags_bulk

Add one or more tags to up to 50 files in one call. Existing tags are kept. Reversible with ImageKit: Remove Tags (Bulk).

ImageKit: Copy File

imagekit_copy_file

Copy a file into another folder, optionally with all its versions. If a file of the same name exists at the destination, the copy is appended to that file's version history. Reversible by deleting the copy.

ImageKit: Copy Folder

imagekit_copy_folder

Copy a folder with all its nested folders and files into another folder. Runs as an asynchronous bulk job: the returned jobId feeds ImageKit: Get Bulk Job Status. Reversible by deleting the copy.

ImageKit: Create Custom Metadata Field

imagekit_create_custom_metadata_field

Define a new custom metadata field (Text, Textarea, Number, Date, Boolean, SingleSelect, or MultiSelect) that assets can then carry values for. Deleting a field later permanently retires its name, so choose names carefully.

ImageKit: Create Folder

imagekit_create_folder

Create a new folder under a parent path, creating missing intermediate folders automatically. Reversible with ImageKit: Delete Folder while the folder is empty.

ImageKit: Delete Custom Metadata Field

imagekit_delete_custom_metadata_field

DESTRUCTIVE: delete a custom metadata field definition. The field's API name is permanently retired: no new field can ever be created with the same name. Fields referenced by a path policy cannot be deleted.

ImageKit: Delete File

imagekit_delete_file

DESTRUCTIVE: permanently delete one file and ALL its versions. There is no trash or restore. Cached copies on the CDN are not removed; purge them with ImageKit: Purge Cache if needed.

ImageKit: Delete File Version

imagekit_delete_file_version

DESTRUCTIVE: permanently delete one NON-CURRENT version of a file (the API refuses to delete the current version). There is no restore for a deleted version.

ImageKit: Delete Files (Bulk)

imagekit_delete_files_bulk

DESTRUCTIVE: permanently delete up to 100 files and all their versions in one call. There is no trash or restore. A 207 response reports per-file failures alongside the successes.

ImageKit: Delete Folder

imagekit_delete_folder

DESTRUCTIVE: permanently delete a folder AND EVERYTHING inside it: all nested files, their versions, and all subfolders. Unlike some providers, ImageKit does NOT refuse non-empty folders, and there is no restore.

ImageKit: Move File

imagekit_move_file

Move a file and all its versions into another folder. If a file of the same name exists at the destination, the moved file is appended to its version history. Reversible by moving back.

ImageKit: Move Folder

imagekit_move_folder

Move a folder with all its nested folders, files, and versions into another folder. Runs as an asynchronous bulk job: the returned jobId feeds ImageKit: Get Bulk Job Status. Reversible by moving back.

ImageKit: Purge Cache

imagekit_purge_cache

Purge the CDN and internal cache for one delivery URL (asynchronous; the cache re-fills on the next request). Returns a requestId for ImageKit: Get Purge Status. Purge requests count against the account's monthly purge quota.

ImageKit: Remove AI Tags (Bulk)

imagekit_remove_ai_tags_bulk

Remove machine-generated AI tags from up to 50 files in one call. AI tags come from the auto-tagging extensions; removed ones can be regenerated by re-running the extension on the file.

ImageKit: Remove Tags (Bulk)

imagekit_remove_tags_bulk

Remove one or more tags from up to 50 files in one call. Reversible with ImageKit: Add Tags (Bulk).

ImageKit: Rename File

imagekit_rename_file

Rename a file (all versions). Old URLs stop working, though CDN-cached copies persist unless purgeCache is set. Reversible by renaming back. A 409 means a file with the new name already exists there.

ImageKit: Rename Folder

imagekit_rename_folder

Rename a folder; every nested asset keeps its content but gets an updated path, so old URLs stop working. Runs as an asynchronous bulk job (202): the returned jobId feeds ImageKit: Get Bulk Job Status. Reversible by renaming back.

ImageKit: Restore File Version

imagekit_restore_file_version

Restore an older version of a file as the current version. Reversible by restoring the previous current version again from the version list.

ImageKit: Update Custom Metadata Field

imagekit_update_custom_metadata_field

Update a custom metadata field's label or schema rules. The field's type and API name cannot change (type keys sent inside schema are ignored). At least one of label or schema must be provided.

ImageKit: Update File Details

imagekit_update_file

Edit the current version of one file: replace its tag list, remove AI tags, set custom coordinates, set custom metadata values, or update the description. Only fields you fill are sent. Extensions and publication state are reachable via extra_body (extensions, publish).

ImageKit: Upload File from URL

imagekit_upload_from_url

Upload a file by giving ImageKit a publicly reachable HTTP or HTTPS URL to fetch server-side (the Upload API's file parameter accepts a URL natively; ImageKit must receive response headers within 8 seconds). Returns the stored file's fileId, path, and delivery URL. Reversible with ImageKit: Delete File.

Using the integration

On the automation canvas

ImageKit nodes chain with every other node: a webhook can carry an image URL into ImageKit: Upload File from URL and write the returned delivery URL into a Mattering database, a scheduled sweep can run ImageKit: List Files with a searchQuery filter and open a task for what it finds, and ImageKit: Get Usage Analytics can feed a report that lands next to the rest of the work. The lister's outputs are the connective tissue: run it first and pipe fileId, filePath, folderPath, and url downstream.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. An agent can search the library with ImageKit: List Files, tag batches with ImageKit: Add Tags (Bulk), file assets with ImageKit: Move File, and set structured values with ImageKit: Update File Details. The read and tag surface is safe to hand an agent outright; keep the five destructive nodes behind conditions or approval steps. ImageKit also publishes its own official MCP server, in public preview (beta) per its docs; this integration is the fit when ImageKit is one step in a workflow that spans other tools.

Pickers versus the searchQuery language

Most identifier fields in this integration are dropdown pickers filled from live account data: fileId fields list your files by name, versionId fields list a file's versions, folder paths list your folders, delivery URL fields list asset URLs, and custom metadata field ids list your field definitions. The one deliberate exception is search. The searchQuery parameter on ImageKit: List Files is a Lucene-like query language with typed comparisons, so it is a field you write, not a list you pick from: a query like createdAt > "7d" AND size > "2mb" filters the library in one call. It composes with the type filter, folder scoping, and sorting on the same node.

Folder operations run as asynchronous jobs

ImageKit: Copy Folder, ImageKit: Move Folder, and ImageKit: Rename Folder act on whole trees, so ImageKit runs them as background jobs: the node returns a jobId immediately, and ImageKit: Get Bulk Job Status reports Pending until the job is Completed. Poll before running steps that depend on the new paths. A folder rename changes the path of every nested asset, so old URLs stop working; when the rename requested a cache purge, the job status also carries the purgeRequestId to poll with ImageKit: Get Purge Status. ImageKit: Create Folder and single-file copy and move are synchronous and need no polling.

Versions, renames, and the cache

Every file keeps its version history: ImageKit: List File Versions shows it newest first, ImageKit: Restore File Version makes an older version current, and ImageKit: Delete File Version prunes non-current versions, with the API refusing to touch the current one. The CDN is the second half of every one of these stories: cached copies keep serving after a rename, restore, or delete, so ImageKit: Purge Cache on the affected delivery URL, then ImageKit: Get Purge Status to Completed, is the honest closing pair. Purges are one URL per call and count against the account's monthly purge quota, so purge exactly what changed; ImageKit: Rename File can request its own purge at rename time.

The five destructive nodes, gated

ImageKit: Delete Folder is the heaviest: it permanently removes the folder and everything inside, all nested files, their versions, and all subfolders, and ImageKit does not refuse a non-empty folder, so list the folder's contents first if there is any doubt. ImageKit: Delete File and ImageKit: Delete Files (Bulk) (up to 100 files per call) remove all versions with no restore. ImageKit: Delete Custom Metadata Field permanently retires the field's name for the whole account. ImageKit: Delete File Version is the smallest but still final for that version. The pattern for all five is the same: read or list the target first, and put the delete behind a condition, an approval task, or a manual run rather than a bare trigger.

Troubleshooting

The credential is rejected with an error about the public key
That error is the integration working as designed: the stored key starts with public_, and ImageKit's public key cannot authenticate server-side API calls (it exists for client-side upload signature flows). It is the value the dashboard surfaces most prominently, which is exactly why the integration checks the prefix and fails fast with a pointed message instead of letting every node return a confusing 401. Open the ImageKit dashboard under Developer options, then API keys, copy the private key (it starts with private_), and update the credential.
Test Connection fails with a 401
The test lists one file from the media library, which succeeds for any valid private key even on an empty account, so a 401 is about the key itself. ImageKit's own error message for a bad key says the request does not contain a private API key. Check for whitespace picked up in the copy, confirm the key was not regenerated in the dashboard since it was saved (regenerating invalidates the old value), and confirm you copied the private key rather than the public one, though a public key is normally caught earlier with its own specific error.
Upload File from URL fails even though the URL opens in a browser
ImageKit fetches the URL server-side, which changes the rules: the URL must be publicly reachable without cookies or login, and ImageKit must receive response headers within 8 seconds. URLs behind authentication, localhost or private-network addresses, and slow origins all fail the fetch even when a logged-in browser shows the file fine. Pre-signed URLs from storage providers work while they are valid. If the source is genuinely private, download it in an earlier step with its own credentials and host it somewhere reachable, or use a pre-signed URL generated for the transfer.
A folder copy, move, or rename returned success but nothing has changed
Those three nodes are asynchronous: success means ImageKit accepted the job, not that it finished. The response carries a jobId; run ImageKit: Get Bulk Job Status with it and treat the operation as done only when the status is Completed. Large folder trees take time, so put the status check in a loop or a delayed step rather than immediately reading the new paths. Single-file copy, move, and rename are synchronous and never need this.
Delete Folder removed files you did not expect
ImageKit: Delete Folder permanently deletes the folder and everything inside it, including all nested files, their versions, and all subfolders, and ImageKit does not refuse a non-empty folder the way some providers do. There is no trash and no restore endpoint, so recovery means re-uploading from wherever the originals live. Prevention is the only real fix: run ImageKit: List Files scoped to the folder path first so the workflow (or the approving human) sees exactly what is inside, and keep this node behind an approval step rather than a bare trigger.
Creating a custom metadata field fails because the name already exists, but no field with that name is visible
Deleting a custom metadata field permanently retires its name: no new field can ever be created with the same name on the account, and a previously deleted field with that name still claims it. Run ImageKit: List Custom Metadata Fields with includeDeleted set to true to see retired names. The fix is a new name (the user-facing label can stay the same, since labels are editable and separate from the API name). Related edge: a field referenced by a path policy cannot be deleted, and the field's type and API name can never be changed after creation, only its label and schema rules.
An old URL still serves a file after a rename, restore, or delete
That is the CDN doing its job: renames and deletes change the media library immediately, but cached copies at the edge keep serving until they expire or are purged. Run ImageKit: Purge Cache with the affected delivery URL, then poll ImageKit: Get Purge Status until Completed. Purges are one URL per call and count against the account's monthly purge quota, so purge the specific URLs that changed rather than sweeping. For renames, ImageKit: Rename File accepts a purgeCache option that requests the purge in the same call and returns a purgeRequestId to poll.
Nodes return 429 during a heavy run, or usage numbers look stale
Two separate behaviors. ImageKit rate-limits per endpoint, with limits that vary by endpoint and account, and reports the state on X-RateLimit-Limit, X-RateLimit-Reset (milliseconds to wait before retrying), and X-RateLimit-Interval response headers; on a 429, wait out the reset and prefer the bulk nodes (tags take up to 50 files per call, bulk delete up to 100) over per-file loops. Separately, ImageKit: Get Account Usage requires a range under 90 days with an exclusive end date, and ImageKit caches its response for several hours, so very recent activity lags; ImageKit: Get Usage Analytics (a beta API, inclusive dates) carries a generatedAt timestamp that states its own freshness.

ImageKit is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products