canonical: https://jentic.com/apis/cloudinary.com/cloudinary-upload-api # Cloudinary Upload API Jentic publishes the only available OpenAPI specification for Cloudinary Upload API, keeping it validated and agent-ready. Upload, transform, and manage images, videos, and raw files through a rate-unlimited REST interface that supports both Basic Authentication and signature-based uploads. The API handles asset creation, metadata tagging, renaming, and deletion across multiple resource types including image, video, and raw file formats. Each uploaded asset is stored in Cloudinary's cloud-based media library with automatic CDN delivery. ## For AI agents Upload and manage media assets in Cloudinary, including images, videos, and raw files. Supports tagging, renaming, explicit transformations, and deletion of cloud-hosted assets. ## Scope Does not handle image analysis, facial recognition, or video transcoding pipelines - use for media upload, tagging, and basic transformations only. ## Capabilities - Upload images, videos, and raw files to a cloud-based media library with automatic CDN distribution - Apply explicit transformations and eager processing to already-uploaded assets without re-uploading - Assign, replace, and remove tags on media assets for organized retrieval and filtering - Rename assets while preserving their transformation URLs and delivery links - Delete individual assets or batch-remove media by public ID from the cloud storage - Generate derived assets such as thumbnails, format conversions, and quality optimizations on upload ## Use cases ### AI Agent Media Upload Automation AI agents upload user-generated content such as profile pictures, product photos, or document scans directly to Cloudinary through Jentic. The agent searches for the upload operation, receives the required multipart form schema, and executes the upload in a single call. Cloudinary returns a secure delivery URL with optional eager transformations applied - the agent never handles raw file bytes beyond the initial POST. Example prompt: Upload a JPEG image file to the Cloudinary cloud using the POST /{resource_type}/upload endpoint with resource_type set to 'image' and verify the returned secure_url ### Bulk Media Tagging and Organization Organize large media libraries by assigning semantic tags to assets. The tags endpoint supports add, remove, and replace operations in a single call, enabling batch categorization of hundreds of assets. Tags serve as the primary filter mechanism for retrieval, making this operation essential for any media-heavy application that needs structured asset discovery. Example prompt: Add the tags 'product-hero' and 'summer-2026' to three image assets using POST /{resource_type}/tags with the command 'add' ### On-the-fly Asset Transformation Apply post-upload transformations to existing assets without re-uploading. The explicit endpoint triggers eager transformations such as format conversion, quality adjustment, face-detection cropping, and responsive breakpoint generation. Results are cached on Cloudinary's CDN, so subsequent requests serve the pre-generated derivative instantly. Example prompt: Call POST /{resource_type}/explicit on an existing image asset to generate a 300x300 face-cropped thumbnail and a WebP format derivative ### Secure Asset Lifecycle Management Control asset availability by renaming or permanently removing files from the media library. The rename endpoint updates the public ID while maintaining existing derived versions, and the destroy endpoint permanently removes an asset and all its transformations from CDN. Both operations support invalidation flags for immediate CDN cache purge. Example prompt: Rename an image asset from 'old_product_photo' to 'product_hero_v2' using POST /{resource_type}/rename and confirm the new public_id in the response ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /{resource_type}/upload | Upload an image, video, or raw file | | POST | /{resource_type}/explicit | Apply transformations to an existing asset | | POST | /{resource_type}/rename | Rename an asset by changing its public ID | | POST | /{resource_type}/destroy | Delete an asset and its derivatives | | POST | /{resource_type}/tags | Add, remove, or replace tags on assets | | GET | /download_backup | Download a backed-up version of an asset | ## Key resources - **Upload** — Upload images, videos, and raw files with optional eager transformations and metadata - **Explicit** — Apply transformations and metadata updates to already-uploaded assets - **Tags** — Add, remove, or replace tags on media assets for organization and retrieval - **Rename** — Change the public ID of an existing asset while preserving derived transformations - **Destroy** — Permanently delete an asset and its derivatives from cloud storage - **Backup** — Download backed-up versions of assets from Cloudinary storage ## Why Jentic - **Setup:** Wiring the Cloudinary Upload API by hand means setting up basic auth with your API key and secret, computing the request signature, and resolving the per-account api.cloudinary.com/v1_1/{cloud_name} host yourself. Through Jentic you install once, import the Cloudinary Upload API from the API Directory, store the key and secret once, and your agent calls it. - **Permission scoping:** The Upload API works within one cloud fixed by the {cloud_name} host and names the asset in the request rather than pinning one id in the URL path, so scope the agent by the operations it needs, such as uploading, tagging, or renaming media. You choose that set, so a destructive operation like destroy is only in reach if you include it. - **Credential handling:** Your Cloudinary API key and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time, with the signature computed there. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'upload an image to cloud storage', and Jentic returns the matching Cloudinary upload operation with its multipart form schema so the agent constructs the request without reading the Cloudinary docs. ## Related APIs - **Imagga API** — AI-powered image recognition and tagging to auto-categorize assets uploaded via Cloudinary - **Filestack API** — File upload and transformation service with similar CDN delivery but different transformation pipeline - **Sirv API** — Image CDN and optimization service with spin and zoom features for e-commerce product imagery ## FAQ ### Why is there no official OpenAPI spec for Cloudinary Upload API? Cloudinary does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Cloudinary Upload API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Cloudinary Upload API use? The Cloudinary Upload API uses HTTP Basic Authentication where the username is your API Key and the password is your API Secret. Alternatively, uploads can use signature-based authentication where you generate a SHA-1 signature from the upload parameters and your API secret. Through Jentic, these credentials are stored encrypted in your Jentic One instance - agents receive scoped access without your API secret entering their context. ### Can I upload videos and raw files, not just images? Yes. The upload endpoint accepts a resource_type path parameter that can be 'image', 'video', or 'raw'. Each resource type supports the full lifecycle: upload, explicit transformations, tagging, renaming, and deletion. The same endpoint structure applies to all three types. ### What are the rate limits for the Cloudinary Upload API? The Cloudinary Upload API is rate-unlimited for upload operations according to the API documentation. There is no per-second or per-minute throttle on upload calls. However, your account's storage quota and bandwidth limits still apply based on your Cloudinary plan tier. ### How do I upload an image through Jentic with an AI agent? Install the Jentic SDK with pip install jentic, then search for 'upload image to cloudinary'. Jentic returns the POST /{resource_type}/upload operation schema with required parameters (file, api_key, timestamp, signature). The agent constructs the multipart request and executes it - Jentic handles credential injection so the API secret never appears in the agent's context. ### Can I apply transformations to an already-uploaded asset without re-uploading it? Yes. Use the POST /{resource_type}/explicit endpoint with the public_id of the existing asset and an eager array specifying the transformations you want (resize, crop, format change, quality adjustment). Cloudinary generates the derivatives and caches them on CDN without requiring a new upload. ### How do I organize assets with tags via the API? Use POST /{resource_type}/tags with a JSON body containing the command (add, remove, or replace), the tag value, and an array of public_ids. You can tag multiple assets in a single call. Tags serve as the primary mechanism for filtering and retrieving assets from your media library. ### Can I limit what my agent is allowed to do with the Cloudinary Upload API? Yes. Because you run your own self-hosted Jentic One instance, your rules decide which Cloudinary Upload API operations the agent may call and which stored credentials it may use. You can grant only the operations you need, such as uploading files, applying explicit transformations, or tagging and renaming assets, while withholding a destructive operation like destroy so it is never in reach. Since the API operates within the single cloud fixed by your cloud_name host and names each asset in the request, the operation set you choose is the boundary of what the agent can touch.