Agent Account Creation API

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

Last updated: Jun-26-2026

The account creation API for agents is an unauthenticated RESTful endpoint that lets an AI agent create a Cloudinary account on a user's behalf and receive its credentials in a single request.

Important

This API is currently in Early Access. Some implementation details may change before the general access release. We invite you to share any feedback via our support team.

The endpoint is built for automated onboarding: it returns the new product environment's credentials and a guidance block that walks the agent through the next steps, while a person stays in control of the account through email verification.

Unlike the Provisioning API, which manages users and product environments within an existing account, this endpoint creates a new account. It needs no authentication, since the agent has no credentials yet.

On this page:

How it works
Create an account
Credential handling for agents
Email verification
Errors

How it works

The agent sends a POST request with the user's email address and a few details about itself.
Cloudinary creates a free account with one product environment and returns the account details, the product environment's credentials, and a guidance block.
Cloudinary sends a verification email to the supplied address. This email address becomes the account's primary email address.
The recipient opens the email and sets a password.
After the recipient verifies the account email, the agent uses the returned API key and secret to call the standard Cloudinary APIs.

Create an account

You can ask an AI assistant to create the account for you. In the prompt, replace you@example.com with the email address of the user who will own the account. For example:

To call the endpoint directly, send a POST request. You don't need to authenticate.

Pass the parameters as a JSON body:

Request parameters

Parameter	Type	Required	Description
`email`	String	Yes	Email address of the user who will own the account. This becomes the account email, and Cloudinary sends the verification email to this address.
`agent_framework`	String	Yes	The framework or platform the agent runs on, for example `langchain`, `crewai`, or `autogen`. Must be 2-100 characters.
`agent_llm_model`	String	Yes	The LLM model and version the agent uses, for example `claude-opus-4-8`. Must be 2-100 characters.
`agent_goal`	String	Yes	The reason to create the account. Must be 2-300 characters.
`sdk_framework`	String	No	The SDK the agent plans to use, for example `python` or `nodejs`. When supplied, it must be 2-100 characters and is used to tailor the setup guidance returned in the response.

Response

A successful request returns the account details, the new product environment's credentials, and a guidance block that tells the agent what to do next.

Field	Type	Description
`external_id`	String	The external ID of the account.
`email`	String	The account's email address.
`plan_name`	String	The plan the account is on (`free`).
`product_environments`	Array	The product environments created with the account. Cloudinary creates one by default.
`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.
`guidance`	String	A Markdown block that guides the agent through email verification and SDK setup.

Note

In the response, each entry in product_environments is a product environment.

Important

The returned API key and secret won't work until the recipient verifies the account email.

Credential handling for agents

If the agent has filesystem access, ask it to store the API secret and full CLOUDINARY_URL in a local .env file instead of printing them in chat. The agent should also confirm that version control ignores .env.

Email verification

As with any Cloudinary account, the recipient must verify the email address before using the account. Cloudinary sends a verification email to the address in the request. The recipient clicks the button in the email and sets a password, which verifies the address and provides a password to sign in to the Console.

The agent should guide the person to complete this step. The verification email asks the recipient to set a password within 24 hours of account creation. If the email isn't verified, Cloudinary disables the account, the same as any unverified Cloudinary account.

Errors

Errors return an error object with a category and a message:

Status	Condition
400	A required parameter is missing, the email format is invalid, the email domain is a disposable-email provider, or an account already exists for the email.
403	Cloudinary's abuse controls blocked the request. The message is intentionally generic.
429	Too many account creation requests from the same IP address. Retry later.

Error

Unfortunately there's been an error sending your feedback.

Rate this page:

Documentation Index

Agent account creation API

Install Cloudinary Agent Skills