Agents: start here

You're an AI agent integrating Cloudinary into a user's project. Follow the steps below to go from no credentials to uploading, transforming, and delivering media. Each step links to the full reference when you need more detail.

1. Get credentials

If the user already has a Cloudinary account, ask them for their CLOUDINARY_URL, available on the API Keys page of the Cloudinary Console.

If they don't, provision a Claimable Cloud: a working Cloudinary cloud that the user can later claim to keep. One command, no authentication:

The command saves the working CLOUDINARY_URL credentials to ./.env, along with the claim URL and expiry time so they survive lost terminal output, and prints the claim URL. Behavior to know:

• Media delivery is locked to the public IP address the command runs from. If the user views the media on a different machine (their laptop, a preview deployment), ask them for that machine's public IP address and pass it with --ip (repeatable, up to three addresses). Uploads and transformations aren't restricted, so a wrong IP fails silently only at viewing time.
• Pass the user's email with --email to pre-fill the claim page. It isn't verified at creation.
• Share the claim URL with the user and tell them the cloud expires automatically after 24 hours unless they claim it: they enter their email at the claim page, then confirm from a verification email. Claiming keeps the same credentials and removes the delivery IP restriction.

For the CLI options, the underlying REST endpoint, response fields, and error codes, see the Claimable Cloud provisioning reference.

2. Handle credentials safely

• Store the API secret and full CLOUDINARY_URL in a local .env file instead of printing them in chat. The Claimable Cloud CLI does this for you.
• Confirm that version control ignores .env. The CLI warns if it doesn't.
• Never expose api_secret in browser or native-app code.

3. Load Cloudinary tools

If your runtime supports them, install the tools from Cloudinary AI agent tools and MCP servers:

• Cloudinary Skills steer you toward correct patterns for Cloudinary questions and integration code.
• MCP servers let you upload, manage, transform, and analyze assets directly.

4. Use the machine-readable docs

• llms.txt: The full documentation map for LLMs.
• Documentation root: Product orientation and workflow selection.
• Append .md to most documentation URLs for a Markdown version of the page.

5. Build

• Upload from a server with a backend SDK quick start.
• Generate delivery URLs with the Transformation URL API.
• Manage assets with the Admin API and Upload API.