Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

Image & Video APIs
Menu

Claimable Cloud API reference

Last updated: Oct-29-2026

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.

On this page:

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:

Option Description
--ip <address> Allow media delivery from a specific viewer IP address, in addition to the caller's. Repeat the option to allow up to three addresses.
--email <address> Pre-fill the claim page with the user's email address. The address isn't verified at creation.
--force Replace an existing CLOUDINARY_URL line in .env. Without this option, the command exits without provisioning if .env already contains one, so a rate-limited Claimable Cloud isn't wasted.
--no-env Print the credentials without writing to .env.
--json Output the raw API response for programmatic use.
--goal <text> What the agent is building, for example --goal "Add image optimization to a web app". Sent as agent_goal. Up to 300 characters.
--model <name> The LLM model driving the session, for example --model claude-opus-5-5. Sent as agent_llm_model, overriding any model detected from the environment.
--no-agent-metadata Don't send any agent fields. By default, the command sends the agent framework and model it detects from the environment.

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

Parameter Type Required Description
delivery_ips Array of strings No Up to three public IP addresses (IPv4 or IPv6) that media delivery from the Claimable Cloud is allowed from, in addition to the calling machine's public IP address, which is always included. Delivery is locked to these addresses until the cloud is claimed, so choose the addresses where the media will actually be viewed. Omit it when the media will be viewed on the machine that sends the request. Pass the literal string requester_ip to name the calling machine's address explicitly. Each entry must be a single IP address: CIDR ranges aren't accepted, and private, LAN, or loopback addresses are ignored.
email String No Email address of the user who will claim the cloud. Pre-fills the claim page; the user confirms or corrects it when claiming, and it isn't verified until then. If omitted, the user enters their email at the claim page.
agent_framework String No The framework or platform the agent runs on, for example claude-code, codex, or cursor. 2-100 characters.
agent_llm_model String No The LLM model and version the agent uses, for example claude-opus-5-5. 2-100 characters.
agent_goal String No What the user asked the agent to do. 2-300 characters.
sdk_framework String No The Cloudinary SDK the agent intends to use, for example nodejs. 2-100 characters.

The agent fields never cause the request to fail. If any of them isn't a string, is outside its length limits, or together they exceed 1024 characters once stored as JSON (escaping, for example of non-ASCII characters, counts toward the limit), the cloud is still created and none of them are recorded.

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.

Field Type Description
id String The unique ID of the Claimable Cloud.
email String The email address associated with the Claimable Cloud. If no email was supplied at provisioning, this is a non-routable placeholder address, replaced by the user's real address at claim.
expires_at String The time at which the Claimable Cloud expires if it isn't claimed, in ISO 8601 format.
delivery_ips Array The public IP addresses that media delivery from the Claimable Cloud is allowed from.
product_environments Array The product environments created with the Claimable Cloud. Always contains exactly one entry.
product_environments[].external_id String The external ID of the product environment.
product_environments[].cloud_name String The cloud name of the product environment.
product_environments[].api_key String The product environment's API key.
product_environments[].api_secret String The product environment's API secret. Treat this value as sensitive.
product_environments[].api_environment_variable String The CLOUDINARY_URL value to use when calling Cloudinary APIs. This value includes the API secret, so treat it as sensitive.
claim_url String The URL where the user claims the cloud. The agent shares this with the user.
guidance String A Markdown block that guides the agent through the claim step and SDK setup.

Important
The returned API key and secret work right away, but the Claimable Cloud and everything in it expire if the user doesn't claim it within the 24-hour claim window. The expires_at field gives the exact expiry time.

Delivery IP restriction

Until the cloud is claimed, media delivery is restricted to the calling machine's IP address and the 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, omit delivery_ips: the calling machine's address is always included. 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 in delivery_ips; 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:

Status Code Condition
400 delivery_ips_too_many More than three IP addresses were supplied.
400 delivery_ips_invalid delivery_ips isn't an array, or an entry isn't a valid single IP address, for example a CIDR range.
400 delivery_ips_not_public No public IP address remains once private, LAN, and loopback addresses are ignored. Pass the viewer's public IP address in delivery_ips.
403 agent_registration_disabled Claimable Cloud provisioning is currently disabled.
403 geo_location_not_permitted The request came from a location where provisioning isn't permitted.
403 None Cloudinary's abuse controls blocked the request. The message is intentionally generic.
429 ip_rate_limit_exceeded Too many provisioning requests from the same IP address. Retry later.
429 global_rate_limit_exceeded Cloudinary's overall provisioning limit was reached. Retry later.

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.

Important
We invite you to share any feedback via our support team.

Related topics

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars