Cloudinary API

Authentication

Product-environment credentials: cloud name, API key and API secret are shown under Console → Settings → API Keys; the SDKs also accept a single CLOUDINARY_URL=cloudinary://{api_key}:{api_secret}@{cloud_name} S6 S23. Keys can be created, renamed, disabled and deleted per product environment through the Console or the Provisioning API (access_keys); since 2026-08 a key can be created and given roles in one step S17 S36.

OIDC discovery is public at https://oauth.cloudinary.com/.well-known/openid-configuration. It advertises grant types authorization_code, implicit, client_credentials and refresh_token, PKCE methods plain and S256, a revocation endpoint (/oauth2/revoke), userinfo, and RS256 ID tokens S12. Unverified The developer docs only document the authorization-code flow; whether client credentials can be used against Cloudinary APIs is Unknown.

An unauthenticated Admin API call returns 401 with WWW-Authenticate: Basic realm="Cloudinary" and {"error":{"message":"Invalid credentials"}} S13. Error codes: 400, 401, 403, 404, 409, 420 (rate limited), JSON body {"error":{"message":…}} S6.

Core resources

Paths are relative to https://api.cloudinary.com (or api-eu / api-ap). {rt} = resource_type (image | video | raw), {type} = delivery type (upload, private, authenticated, fetch…). Derived from the official OpenAPI schema cloudinary_openapi_api.yml S21 and the Admin/Upload API references S5 S7.

Data model

• Account → product environments (each identified by a cloud name, formerly "sub-accounts") → assets. Users and groups belong to the account; API keys belong to a product environment S17 S53.
• Asset identifiers: asset_id (immutable, unique); public_id (unique among assets of the same resource type, up to 255 chars, part of the delivery URL, editable); display_name (not unique, dynamic folders only); asset_folder (location; separate from the public ID in dynamic mode); resource_type (image / video / raw); delivery type; version (numeric, appears in URLs) S29 S44 S14. Legacy API calls address an asset by the resource_type / type / public_id triplet; newer endpoints also accept asset_id S7 S5.
• Resource payload (search/get): format, bytes, width, height, aspect_ratio, pixels, created_at, uploaded_at, url, secure_url, status (active / not_found if deleted but backed up), access_mode, access_control, etag, created_by / uploaded_by (user or access key). Optional fields via with_field / fields: tags, context, metadata, and (Tier 2) image_metadata, image_analysis S14 S21.
• Metadata: tags (array), context (key/value map), metadata (structured fields by external ID; list values by datasource external ID) S21 S46.
• Renditions: derived assets are created by transformation URLs or eager at upload; listed on the parent asset, deletable or invalidatable via derived_resources S21 S31.
• Versions: backed-up originals are listed with versions=true, downloaded via download_backup, and restored via resources/restore S6 S21.

Search & querying

• POST/v1_1/{cloud}/resources/search with a JSON body: expression, sort_by (array of {field: asc|desc}, default created_at desc), max_results (default 50, max 500), next_cursor, aggregate, with_field, fields S21 S14.
• Expression syntax: Lucene-like; field:value (tokenised) vs field=value (exact), trailing * prefix, ranges [a TO b] / {a TO b}, comparisons > < >= <=, relative dates (uploaded_at>1d), AND / OR / NOT / - S21 S52. Fields cover technical properties, tags, context, structured metadata, folder, moderation, access mode and (Tier 2) image analysis such as colours, faces, quality and embedded metadata S14.
• Tiers: Tier 1 is enabled automatically for product environments with up to 10 million assets. Tier 2 (image-analysis fields, embedded-metadata search, aggregate facet counts) is on request for Advanced plans and above (extra cost) and Enterprise (included up to 10M assets) S14.
• Visual search (Enterprise only): POST…/resources/visual_search with exactly one of image_url, image_asset_id or text S5 S21.
• Deep pagination: cursor-based with no documented hard cap S14. Index freshness / eventual-consistency delay: Not public.
• Folder search: …/folders/search with an expression on folder properties S14 S21.

Uploads & binaries

• Single request: multipart POST…/{rt}/upload with file as binary, Base64 data URI, remote HTTP(S)/FTP URL (fetched server-side), or allowlisted private S3/GCS bucket URL S9.
• Chunked: required above 100 MB. SDK upload_large uses 20 MB chunks by default (minimum 5 MB); async=true for files above 20 GB. REST: each chunk is POSTed with the same X-Unique-Upload-Id header and a Content-Range: bytes start-end/total header (-1 total if unknown); intermediate responses return done: false S9. Unverified The docs say chunks go to the normal upload endpoint, while the OpenAPI schema also exposes a separate …/{rt}/upload_chunked operation S21.
• Asynchronous processing: eager transformations (optionally asynchronous) with notification_url callbacks; upload responses return asset_id, public_id, version, secure_url and metadata S9 S15.
• Upload widget (https://upload-widget.cloudinary.com/latest/global/all.js): drop-in client UI with third-party sources and signed or unsigned presets S28.
• Download / delivery: originals and renditions through https://res.cloudinary.com/{cloud}/{asset_type}/{delivery_type}/{transformations}/{version}/{public_id}.{ext}; root-path shortcuts for images S31. Responses come from a CDN (Cloudflare headers observed on the shared domain, Cache-Control: max-age=2592000) S13. Private/authenticated assets need signed URLs or token/cookie auth S30. Admin downloads: …/download, …/asset/download, generate_archive (ZIP) S7.
• File size limits by plan: see Overview → Pricing S67.

Events & webhooks

• Configuration: in the Console (Settings → Webhook Notifications, each URL linked to chosen notification types) or through the Admin API triggers (one event_type + one uri each; event_type: all allowed; event type cannot be changed after creation) S15 S16. Unverified The same page says both "up to 10" and "up to 30" notification URLs per product environment; the trigger section uses 30 S15.
• Per-request notification_url on Upload API calls and upload presets. By default (additive: false) global triggers do not fire when a per-call URL is set; with additive: true both receive the notification S15.
• Event types (notification_type): upload, delete, delete_by_token, rename, move, create_folder, delete_folder, move_or_rename_asset_folder, resource_tags_changed, resource_context_changed, resource_metadata_changed, resource_display_name_changed, access_control_changed, moderation, moderation_summary, eager, explode, multi, generate_archive, info (add-on results), error, invalidate_custom_cdn, bulk_refresh_auto_fetch, publish (public link), proof_status_changed, related_assets, report, restore_asset_version S16. Many fire for both API and Console UI actions (for example a Media Library move sends move) S15.
• Payload: HTTP POST containing the same information as the synchronous API response. Can be reshaped per trigger with a Mustache payload_template and narrowed with JSONLogic filter expressions S15.
• Signature: headers X-Cld-Timestamp + X-Cld-Signature (legacy HMAC-SHA1 keyed with the API secret) and/or X-Cld-Signature_v2 (Ed25519 / EdDSA v2, Cloudinary-managed key). Chosen per trigger with auth_scheme = default (both), legacy_hmac or eddsa_v2. A dedicated API key can be set for verification S15.
• Retries: on a non-200 response, 3 more attempts after 3, 6 and 9 minutes; delivery timeout 20 s S15.

Limits & quirks

• Admin vs Upload API split: Admin is rate-limited per hour and Upload is not. Cloudinary itself suggests Upload API methods (explicit, tags, context, metadata) for bulk updates to stay under Admin limits S6 S21.
• HTTP 420 (not 429) signals Admin rate limiting S6. Newer generation APIs use 429 S21.
• Folder mode matters: fixed-folder environments embed the folder in public_id; moving or renaming changes URLs and fires rename instead of move. Folder mode is set at creation and migration to dynamic is one-way (via support) S29 S15.
• Overwrite semantics: unless "Keep existing metadata when uploading newer versions" is enabled, API overwrites delete tags, context and structured metadata S45.
• Search tiers: aggregations and image-analysis fields are silently omitted on Tier 1 (the request is accepted) S21.
• OAuth is beta; the PHP SDK does not support oauth_token for Upload calls S11.
• Media Library widget needs a logged-in Cloudinary user (seat) and, for Enterprise, an Assets plan; optional SAML SSO login S27.
• Free-plan limits apply to API size and resolution (e.g. 10 MB image, 25 MP) S67.
• Validate user input before passing it into public_id, tags, context and similar parameters (vendor guidance) S4.

SDKs, tools & code samples

The GitHub org cloudinary has about 140 public repositories (active; cloudinary_npm pushed 2026-09-24) S95.

Changelog of the API