Cloudinary

Retrieves comprehensive usage metrics and account statistics A report on the status of product environment usage, including storage, credits, bandwidth, requests, number of resources, and add-on usage. No date parameter needed to get current usage statistics.

Add related assets by asset ID Relates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other.

Delete asset relations by asset ID Unrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.

Renames or moves an entire folder (along with all assets it contains) to a new location Renames or moves an entire folder (along with all assets it contains) to a new location within your Cloudinary media library.

Creates a new empty folder in your Cloudinary media library Creates a new folder at the specified path

Deletes an existing folder from your media library Deletes a folder and all assets within it.

Searches for folders whose attributes match a given expression Lists the folders that match the specified search expression. Limited to 2000 results. If no parameters are passed, returns the 50 most recently created folders in descending order of creation time.

Provides a powerful query interface to filter and retrieve assets and their details Returns a list of resources matching the specified search criteria. Uses a Lucene-like query language to filter assets by descriptive attributes (`public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder`, `tags`, `context.<key>`), file details (`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`), lifecycle dates (`uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`), moderation and lifecycle state (`status`, `moderation_status`, `moderation_kind`), embedded data (`image_metadata.*`), structured metadata (`metadata.<external_id>`), and analysis fields (`face_count`, `colors`, `quality_score`, `illustration_score`, `accessibility_analysis.*`). Supports sorting, aggregate counts, and complex boolean expressions. See the `expression` parameter for the full field reference. ## Expression syntax - **Match**: `field:value` (token match) or `field=value` (exact match). Examples: `tags:shirt`, `tags=cotton`. - **Comparisons**: `>`, `<`, `>=`, `<=` for numbers and dates. Example: `bytes>10000000`. - **Ranges**: `field:[from TO to]` inclusive, `field:{from TO to}` exclusive. Example: `width:{200 TO 1028}`. - **Booleans**: `AND`, `OR`, `NOT` (uppercase), or `+` (must), `-` (must not). `NOT` must appear between clauses — a bare leading `NOT` is a parse error; use `-field:value` to negate the first clause. Group with parentheses: `(shirt OR pants) AND clothes`. - **Wildcards**: trailing `*` only, for prefix match (`public_id:shoes_*`, `format:jp*`, `tags:shirt*`). Not supported on `folder`, `asset_folder`, `resource_type`, or `type`. Leading `*`, middle `*`, `?`, and bare `*` (`folder:*`, `context.alt:*`) are all parse errors — wildcards cannot be used as a "field is present" probe. - **Tokenized vs exact fields**: `tags`, `filename`, `display_name`, `context.<key>`, and `metadata.<id>` match on tokens split by whitespace and punctuation — `tags:analysis` matches the tag `full-analysis`. `public_id`, `folder`, `asset_folder`, and `format` match the whole value — `public_id:dog` will not match `dog_pldcwy`; use `public_id="dog_pldcwy"` (exact) or `public_id:dog*` (prefix). These exact-match fields still accept a trailing `*` for prefix match (except `folder` / `asset_folder`, where wildcards are ignored). - **Dates**: ISO-8601 in quotes (`uploaded_at>"2024-01-15"`) or relative shorthand `Nh`, `Nd`, `Nw`, `Nm`, `Ny` (`uploaded_at>1d`, `created_at:[4w TO 1w]`). Send raw `<`/`>`, never HTML-escaped. - **Quoting**: wrap any value containing a space, colon, or other reserved character (`! ( ) { } [ ] ^ ~ ? \ = & < > |`) in double quotes, or escape each character with `\`. Examples: `tags:"service:mantels"`, `aspect_ratio:"16:9"`, `folder:"My Folder"`. ## Common mistakes - Use `folder:` or `asset_folder:` (singular); `folders:`, `asset_folder_id:`, and other invented variants are not valid fields. Pass the exact folder name — wildcards do not apply here. - There is no "has any value" / presence probe. `folder:*`, `metadata.alt:*`, `context.key:*`, `tags:*`, and `-tags:*` are all parse errors. See *"Which assets have any value for `metadata.<id>`?"* under **Common tasks** for workarounds. - `NOT foo AND bar` is a parse error. Write it as `bar AND NOT foo` or `-foo AND bar`, and keep every `NOT` between two clauses (`a AND NOT b AND NOT c` is fine; `NOT b AND NOT c …` is not). - `public_id:dog` will not match `dog_pldcwy`. Use `public_id="dog_pldcwy"` (exact) or `public_id:dog*` (prefix). - `tags=service:mantels` fails because the unquoted colon is parsed as a field separator. Use `tags="service:mantels"` or `tags=service\:mantels`. - Do not HTML-escape operators. Send `uploaded_at<1h`, not `uploaded_at&lt;1h`. - Do not leave an operand empty (e.g. `tags: AND -tags:foo`). Omit the empty clause entirely. ## Tips - Set `max_results: 0` to return only `total_count` and `aggregations` without any resource payload — useful for counts and aggregation-only queries. - `total_count` is always present in the response; prefer it over running an aggregation just to get a count. - `aggregate` (both simple and range variants) and the `metadata`, `image_metadata`, `image_analysis` values of `with_field` require a Tier 2 search plan. - Range aggregations require each range to include a `key` label (1–20 chars, `[a-zA-Z0-9_-]+`) and at least one of `from` / `to`. ## Common tasks - **Count matching assets** — put the filter in `expression` with `max_results: 0` and read `total_count` from the response. Works on every tier; no `aggregate` needed. - **Preview one matching asset** — set `max_results: 1`; add `with_field: ["tags", "context"]` (or `metadata`, Tier 2) to inspect values. Prefer this over fetching and scanning a full page. - **Distribution of values for a field** — Tier 2: `aggregate: [format|resource_type|type]` for enum counts, or range aggregations on `bytes`, `image_pixels`, `video_pixels`, or `duration`. Tier 1 fallback: run N small queries with `max_results: 0`, one per candidate value, and read `total_count` from each. - **"Which assets have any value for `metadata.<id>`?"** — not expressible directly (`metadata.X:*` is a parse error; there is no presence probe). Workarounds: (a) if the field has a known value set, enumerate — `metadata.region:(apac OR emea OR amer)`; (b) query broadly with `with_field: ["metadata"]` (Tier 2) and filter client-side for entries where the field is set; (c) at ingest time, attach a sentinel tag whenever the field is set, then search by that tag. - **Newest / largest N** — keep the filter in `expression` and sort explicitly: `sort_by: [{uploaded_at: "desc"}]` with `max_results: 10`. - **Filter by folder** — both `asset_folder:"parent/child"` and `folder:"parent/child"` match an exact folder path; there is no wildcard or "contains". To query across multiple folders, enumerate: `asset_folder:("campaigns/2024" OR "campaigns/2025")`. - **Filter by metadata when you only know the label** — first call `list-metadata-fields` to resolve the label to an `external_id`, then query `metadata.<external_id>:value`. - **Multiple independent filters in one turn** — prefer one `expression` with `OR` / parentheses over firing many parallel calls: `metadata.region:apac OR metadata.region:emea` in a single request is faster and more reliable than two parallel requests. ## Examples - `tags:shirt AND uploaded_at>1d` - `resource_type:image AND bytes>1000000 AND (format:png OR format:jpg)` - `folder:products AND context.category:electronics` - `tags:"service:mantels" AND -tags:discontinued`

Finds images in your asset library based on visual similarity or content Returns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways: - Provide a URL of an image - Specify the asset ID of an existing image - Provide a textual description

Get Cloudinary transformation rules documentation from official docs 🚨 WHEN TO USE: - MANDATORY before creating, modifying, or discussing Cloudinary transformations - REQUIRED when user asks for image/video effects, resizing, cropping, filters, etc. - NOT needed for simple asset management (upload, list, delete, etc.) - ⚠️ CALL ONLY ONCE per session - documentation doesn't change, reuse the knowledge 🚨 STRICT REQUIREMENTS (when transformations are involved): - MUST call this tool BEFORE any transformation-related task (but only once) - MUST read and understand the returned documentation - DO NOT attempt transformations without consulting this reference - DO NOT make up transformation parameters - DO NOT guess syntax - only use documented parameters - DO NOT call this tool multiple times - the docs are static, remember them This tool returns the complete, authoritative Cloudinary transformation reference that contains all valid parameters, syntax rules, and best practices.

Generate derived transformations for existing assets using Cloudinary's explicit API with eager transformations ⚠️ CRITICAL PREREQUISITES: 1. MUST call get-tx-reference tool first 2. MUST validate transformation syntax against official docs 3. MUST use only documented parameters from the reference 4. MUST follow proper URL component structure (slashes between components, commas within) 📋 VALIDATION CHECKLIST: - ✅ Called get-tx-reference tool - ✅ Verified all parameters exist in official docs - ✅ Used correct syntax (e.g., f_auto/q_auto not f_auto,q_auto) - ✅ Applied proper component chaining rules - ✅ Included crop mode when using width/height This tool creates actual derived assets on Cloudinary using the explicit API.

Use this tool when the user wants to upload a file to Cloudinary directly from their own machine or environment. It signs Upload API parameters so the caller can POST files straight to the Cloudinary Upload API — no API secret required on the client side. NOT suitable for large files (>100 MB) or bulk uploads — direct the user to the Cloudinary CLI (`cld uploader upload`) or an SDK instead, which handle chunking, retries, and progress reporting. Returns one credential object per input entry: upload_params — serialized params to echo verbatim as form fields (includes timestamp) api_key — Cloudinary API key signature — HMAC signature over upload_params; invalidated if any field is changed host — Upload API hostname (may differ from api.cloudinary.com for regional/enterprise accounts) cloud_name — Cloudinary cloud name Send only signable params in the input (public_id, folder, tags, context, metadata, eager, transformation, …). Do not include file, resource_type, api_key, or signature — these are not part of the signed parameter set and will be ignored if passed. To upload after signing, POST multipart/form-data to: https://<host>/v1_1/<cloud_name>/<resource_type>/upload Include your file plus api_key, signature, and EVERY key from upload_params as its own form field. Any added, dropped, renamed, or re-serialized field invalidates the signature. resource_type (image/video/raw/auto) is part of the URL, not upload_params. Example (all upload_params keys must appear — shown here with public_id and timestamp only for brevity; include every key your upload_params actually contains): curl https://<host>/v1_1/<cloud_name>/image/upload \ -F 'file=@"/path/to/photo.jpg"' \ -F 'api_key=<api_key>' -F 'signature=<signature>' \ -F 'timestamp=<upload_params.timestamp>' \ -F 'public_id=<upload_params.public_id>' # one -F per upload_params key IMPORTANT — the file= argument MUST use two quoting layers: single-quotes around the entire -F value (shell), double-quotes around the path (curl): -F 'file=@"<path>"'. Paths with spaces or special characters are common and will be word-split by the shell if unquoted, silently truncating the filename at the first space.