Claimable Cloud API reference

A Claimable Cloud is a working Cloudinary environment that an AI agent can provision on a user's behalf, with no signup and no existing credentials. The returned credentials work immediately, media delivery is restricted to the IP addresses supplied at provisioning, and the cloud expires at the end of the 24-hour claim window unless the user claims it.

For the full agent onboarding flow, see Agents: start here.

Provision a Claimable Cloud

The fastest way to provision a Claimable Cloud is the CLI that wraps the REST API. A single command, with no arguments and no authentication, provisions the cloud, saves the credentials as CLOUDINARY_URL in the project's .env file (creating the file if needed), and prints the claim URL and next steps. The claim URL and expiry time are saved to .env as well, so they survive lost terminal output:

By default, media delivery is locked to the public IP address the command runs from. Use the options to change that and more:

The command never opens a browser, and it warns if .env isn't ignored by version control.

Call the API directly

To provision a Claimable Cloud without the CLI, send a POST request to the provisioning endpoint. You don't need to authenticate.

Pass the parameters as a JSON body:

Request parameters

Response

A successful request returns the Claimable Cloud's details, the new product environment's credentials, the expiry time, the claim URL, and a guidance block that tells the agent what to do next.

Delivery IP restriction

Until the cloud is claimed, media delivery is restricted to the IP addresses in delivery_ips: requests from any other address are blocked at the CDN edge. Uploads, transformations, and API calls aren't restricted; only delivery of the resulting media is.

Because of this, the delivery_ips values should be the public IP addresses of the machines where the media will actually be viewed, which aren't always where the agent runs. If the agent runs on the user's machine, requester_ip is the right choice. If the agent runs elsewhere, for example in a CI job or a cloud runtime, and the user views the media from their laptop or a preview deployment, the agent should pass the viewer's public IP address instead; otherwise the media won't load for the user, even though uploads and transformations succeed.

Claiming the cloud removes the restriction, and media delivery works globally from then on.

Claimable Cloud limits

The Claimable Cloud is limited by time and quota: it expires if it isn't claimed within 24 hours of provisioning (the exact time is returned as expires_at and saved to .env by the CLI), and its usage caps are lower than those of a regular free account. Claiming converts it to a free Cloudinary account with the free plan's regular limits.

Claim the cloud

The user claims the cloud at the returned claim_url: they enter their email address (pre-filled if the agent supplied one at provisioning), review the privacy policy and terms of service, optionally set a password for signing in to the Console, and confirm from the verification email. Submitting the claim form extends the claim window, so a claim in progress doesn't expire. If the address already belongs to another Cloudinary account, the claim page shows an error and the user can enter a different address.

Claiming turns the Claimable Cloud into a free Cloudinary account with the verified email as its primary address:

• The cloud name, API key, and API secret stay the same, so anything the agent built against the Claimable Cloud keeps working, and all uploaded assets are retained.
• The delivery IP restriction is removed, so media delivery works globally.

Until the claim completes, no terms are accepted and no payment method is attached. An unclaimed cloud expires at the end of the 24-hour claim window, and Cloudinary deletes it and everything in it. An expired claim URL can't be recovered: the agent provisions a new cloud instead.

Errors

Errors return an error object with a category and a message. Some errors also include a machine-readable code:

API stability

Some details of this API may change over time. It's designed as a one-off call that an agent makes to provision a Claimable Cloud, not an API to integrate against in code, so in practice any changes shouldn't affect you. Once claimed, a Claimable Cloud behaves the same as any other Cloudinary account and won't change.