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.
Connect ImageKit to Mattering
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
Test Connection fails with a 401
Upload File from URL fails even though the URL opens in a browser
A folder copy, move, or rename returned success but nothing has changed
Delete Folder removed files you did not expect
Creating a custom metadata field fails because the name already exists, but no field with that name is visible
An old URL still serves a file after a rename, restore, or delete
Nodes return 429 during a heavy run, or usage numbers look stale
Related
The ImageKit MCP
What connecting ImageKit unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.