The SDK can be installed with either npm, pnpm, bun or yarn package managers.
npm add @cloudinary/config
pnpm add @cloudinary/config
bun add @cloudinary/config
yarn add @cloudinary/config zod
# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.
This SDK is also an installable MCP server where the various SDK methods are exposed as tools that can be invoked by AI applications.
Node.js v20 or greater is required to run the MCP server from npm.
Claude installation steps
Add the following server definition to your claude_desktop_config.json
file:
{
"mcpServers": {
"CloudinaryConfig": {
"command": "npx",
"args": [
"-y", "--package", "@cloudinary/config",
"--",
"mcp", "start",
"--api-key", "...",
"--api-secret", "...",
"--cloud-name", "..."
]
}
}
}
Cursor installation steps
Create a .cursor/mcp.json
file in your project root with the following content:
{
"mcpServers": {
"CloudinaryConfig": {
"command": "npx",
"args": [
"-y", "--package", "@cloudinary/config",
"--",
"mcp", "start",
"--api-key", "...",
"--api-secret", "...",
"--cloud-name", "..."
]
}
}
}
You can also run MCP servers as a standalone binary with no additional dependencies. You must pull these binaries from available Github releases:
curl -L -o mcp-server \
https://github.com/cloudinary/config-js/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server
For a full list of server arguments, run:
npx -y --package @cloudinary/config -- mcp start --help
For supported JavaScript runtimes, please consult RUNTIMES.md.
import { CloudinaryConfig } from "@cloudinary/config";
const cloudinaryConfig = new CloudinaryConfig({
cloudName: "<value>",
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
});
async function run() {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
);
console.log(result);
}
run();
A parameter is configured globally. This parameter may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, This global value will be used as the default on the operations that use it. When such operations are called, there is a place in each to override the global value, if needed.
For example, you can set cloud_name
to "<value>"
at SDK initialization and then you do not have to pass the same value on calls to operations like listTransformations
. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.
The following global parameter is available. Global parameters can also be set via environment variable.
Name | Type | Description | Environment |
---|---|---|---|
cloudName | string | The cloud name of your product environment. | CLOUDINARY_CLOUD_NAME |
import { CloudinaryConfig } from "@cloudinary/config";
const cloudinaryConfig = new CloudinaryConfig({
cloudName: "<value>",
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
});
async function run() {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
);
console.log(result);
}
run();
This SDK supports the following security scheme globally:
Name | Type | Scheme | Environment Variable |
---|---|---|---|
apiKey apiSecret |
http | Custom HTTP | CLOUDINARY_API_KEY CLOUDINARY_API_SECRET |
You can set the security parameters through the security
optional parameter when initializing the SDK client instance. For example:
import { CloudinaryConfig } from "@cloudinary/config";
const cloudinaryConfig = new CloudinaryConfig({
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
cloudName: "<value>",
});
async function run() {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
);
console.log(result);
}
run();
Available methods
- createMetadataField - Creates a new structured metadata field in your account
- listMetadataFields - Lists all structured metadata fields defined in your Cloudinary product environment
- getMetadataField - Retrieves the definition of a specific structured metadata field by its identifier (external_id)
- updateMetadataField - Updates the configuration of an existing metadata field
- deleteMetadataField - Deletes a structured metadata field definition from your account
- searchMetadataFieldDatasource - Search across all metadata field datasources
- reorderMetadataFields - Reorder all metadata fields
- reorderMetadataField - Change position of metadata field
- updateMetadataFieldDatasource - Updates the allowed values (the datasource) for a specified metadata field
- deleteMetadataFieldDatasource - Removes one or more allowed values from a metadata field's datasource
- searchDatasourceInMDField - Search datasource values in a metadata field
- restoreMetadataFieldDatasource - Restore datasource values
- createMetadataRule - Creates a new conditional metadata rule
- listMetadataRules - Retrieves a list of all conditional metadata rules defined in your accountcloudinary
- updateMetadataRule - Updates an existing conditional metadata rule's definition
- deleteMetadataRule - Deletes a conditional metadata rule by its ID
- createStreamingProfile - Creates a new adaptive streaming profile in your Cloudinary account
- getStreamingProfiles - Lists all adaptive streaming profiles (both built-in and custom) defined in your Cloudinary account
- getStreamingProfile - Retrieves the details of a single adaptive streaming profile by its name
- updateStreamingProfile - Modifies an existing adaptive streaming profile's configuration
- deleteStreamingProfile - Delete custom streaming profile or revert built-in profile to the original settings
- listTransformations - Lists all transformation definitions in your account (including named transformations
- getTransformation - Retrieves details of a specific transformation
- createTransformation - Creates a new named transformation (assigning a custom name to a set of transformation
- updateTransformation - Updates the definition of an existing named transformation
- deleteTransformation - Deletes a named transformation from your account
- listTrigger - Lists all webhook notification triggers configured for your product environmentcloudinary
- createTrigger - Creates a new notification trigger (webhook) by specifying an event type and a destination
- updateTrigger - Updates the callback URL of an existing webhook trigger in your Cloudinary account
- deleteTrigger - Deletes a notification trigger
- listUploadMappings - Retrieves a list of all upload mapping rules configured in your Cloudinary product environment
- createUploadMapping - Creates a new upload mapping
- updateUploadMapping - Updates an existing upload mapping by changing its remote URL template for a given
- deleteUploadMapping - Deletes a folder upload mapping
- replaceUploadMappings - Replaces all upload mappings
- createUploadPreset - Creates a new upload preset with specified configuration settings
- listUploadPresets - Lists all upload presets configured in the account
- getUploadPreset - Retrieves details of a single upload preset
- updateUploadPreset - Updates an existing upload preset's configuration settings
- deleteUploadPreset - Deletes an upload preset from the account
All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.
To read more about standalone functions, check FUNCTIONS.md.
Available standalone functions
metadataFieldsCreateMetadataField
- Creates a new structured metadata field in your accountmetadataFieldsDeleteMetadataField
- Deletes a structured metadata field definition from your accountmetadataFieldsDeleteMetadataFieldDatasource
- Removes one or more allowed values from a metadata field's datasourcemetadataFieldsGetMetadataField
- Retrieves the definition of a specific structured metadata field by its identifier (external_id)metadataFieldsListMetadataFields
- Lists all structured metadata fields defined in your Cloudinary product environmentmetadataFieldsReorderMetadataField
- Change position of metadata fieldmetadataFieldsReorderMetadataFields
- Reorder all metadata fieldsmetadataFieldsRestoreMetadataFieldDatasource
- Restore datasource valuesmetadataFieldsSearchDatasourceInMDField
- Search datasource values in a metadata fieldmetadataFieldsSearchMetadataFieldDatasource
- Search across all metadata field datasourcesmetadataFieldsUpdateMetadataField
- Updates the configuration of an existing metadata fieldmetadataFieldsUpdateMetadataFieldDatasource
- Updates the allowed values (the datasource) for a specified metadata fieldmetadataRulesCreateMetadataRule
- Creates a new conditional metadata rulemetadataRulesDeleteMetadataRule
- Deletes a conditional metadata rule by its IDmetadataRulesListMetadataRules
- Retrieves a list of all conditional metadata rules defined in your accountcloudinarymetadataRulesUpdateMetadataRule
- Updates an existing conditional metadata rule's definitionstreamingProfilesCreateStreamingProfile
- Creates a new adaptive streaming profile in your Cloudinary accountstreamingProfilesDeleteStreamingProfile
- Delete custom streaming profile or revert built-in profile to the original settingsstreamingProfilesGetStreamingProfile
- Retrieves the details of a single adaptive streaming profile by its namestreamingProfilesGetStreamingProfiles
- Lists all adaptive streaming profiles (both built-in and custom) defined in your Cloudinary accountstreamingProfilesUpdateStreamingProfile
- Modifies an existing adaptive streaming profile's configurationtransformationsCreateTransformation
- Creates a new named transformation (assigning a custom name to a set of transformationtransformationsDeleteTransformation
- Deletes a named transformation from your accounttransformationsGetTransformation
- Retrieves details of a specific transformationtransformationsListTransformations
- Lists all transformation definitions in your account (including named transformationstransformationsUpdateTransformation
- Updates the definition of an existing named transformationtriggersCreateTrigger
- Creates a new notification trigger (webhook) by specifying an event type and a destinationtriggersDeleteTrigger
- Deletes a notification triggertriggersListTrigger
- Lists all webhook notification triggers configured for your product environmentcloudinarytriggersUpdateTrigger
- Updates the callback URL of an existing webhook trigger in your Cloudinary accountuploadMappingsCreateUploadMapping
- Creates a new upload mappinguploadMappingsDeleteUploadMapping
- Deletes a folder upload mappinguploadMappingsListUploadMappings
- Retrieves a list of all upload mapping rules configured in your Cloudinary product environmentuploadMappingsReplaceUploadMappings
- Replaces all upload mappingsuploadMappingsUpdateUploadMapping
- Updates an existing upload mapping by changing its remote URL template for a givenuploadPresetsCreateUploadPreset
- Creates a new upload preset with specified configuration settingsuploadPresetsDeleteUploadPreset
- Deletes an upload preset from the accountuploadPresetsGetUploadPreset
- Retrieves details of a single upload presetuploadPresetsListUploadPresets
- Lists all upload presets configured in the accountuploadPresetsUpdateUploadPreset
- Updates an existing upload preset's configuration settings
Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.
To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:
import { CloudinaryConfig } from "@cloudinary/config";
const cloudinaryConfig = new CloudinaryConfig({
cloudName: "<value>",
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
});
async function run() {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
{
retries: {
strategy: "backoff",
backoff: {
initialInterval: 1,
maxInterval: 50,
exponent: 1.1,
maxElapsedTime: 100,
},
retryConnectionErrors: false,
},
},
);
console.log(result);
}
run();
If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:
import { CloudinaryConfig } from "@cloudinary/config";
const cloudinaryConfig = new CloudinaryConfig({
retryConfig: {
strategy: "backoff",
backoff: {
initialInterval: 1,
maxInterval: 50,
exponent: 1.1,
maxElapsedTime: 100,
},
retryConnectionErrors: false,
},
cloudName: "<value>",
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
});
async function run() {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
);
console.log(result);
}
run();
CloudinaryConfigError
is the base class for all HTTP error responses. It has the following properties:
Property | Type | Description |
---|---|---|
error.message |
string |
Error message |
error.statusCode |
number |
HTTP response status code eg 404 |
error.headers |
Headers |
HTTP response headers |
error.body |
string |
HTTP body. Can be empty string if no body is returned. |
error.rawResponse |
Response |
Raw HTTP response |
error.data$ |
Optional. Some errors may contain structured data. See Error Classes. |
import { CloudinaryConfig } from "@cloudinary/config";
import * as errors from "@cloudinary/config/models/errors";
const cloudinaryConfig = new CloudinaryConfig({
cloudName: "<value>",
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
});
async function run() {
try {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
);
console.log(result);
} catch (error) {
// The base class for HTTP error responses
if (error instanceof errors.CloudinaryConfigError) {
console.log(error.message);
console.log(error.statusCode);
console.log(error.body);
console.log(error.headers);
// Depending on the method different errors may be thrown
if (error instanceof errors.ApiError) {
console.log(error.data$.error); // components.ErrorT
}
}
}
}
run();
Primary errors:
CloudinaryConfigError
: The base class for HTTP error responses.ApiError
: Generic error.
Less common errors (6)
Network errors:
ConnectionError
: HTTP client was unable to make a request to a server.RequestTimeoutError
: HTTP request timed out due to an AbortSignal signal.RequestAbortedError
: HTTP request was aborted by the client.InvalidRequestError
: Any input used to create a request is invalid.UnexpectedClientError
: Unrecognised or unexpected error.
Inherit from CloudinaryConfigError
:
ResponseValidationError
: Type mismatch between the data returned from the server and the structure expected by the SDK. Seeerror.rawValue
for the raw value anderror.pretty()
for a nicely formatted multi-line string.
You can override the default server globally by passing a server index to the serverIdx: number
optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:
# | Server | Variables | Description |
---|---|---|---|
0 | https://{region}.cloudinary.com |
region |
Regional API endpoints for optimal performance. |
1 | https://{host} |
host |
Custom domains for enterprise deployments. |
If the selected server has variables, you may override its default values through the additional parameters made available in the SDK constructor:
Variable | Parameter | Supported Values | Default | Description |
---|---|---|---|---|
region |
region: models.ServerRegion |
- "api" - "api-eu" - "api-ap" |
"api" |
Regional endpoint selection |
host |
host: string |
string | "api.cloudinary.com" |
API host domain. |
import { CloudinaryConfig } from "@cloudinary/config";
const cloudinaryConfig = new CloudinaryConfig({
serverIdx: 1,
host: "unlined-aircraft.info",
cloudName: "<value>",
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
});
async function run() {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
);
console.log(result);
}
run();
The default server can also be overridden globally by passing a URL to the serverURL: string
optional parameter when initializing the SDK client instance. For example:
import { CloudinaryConfig } from "@cloudinary/config";
const cloudinaryConfig = new CloudinaryConfig({
serverURL: "https://api.cloudinary.com",
cloudName: "<value>",
security: {
apiKey: "CLOUDINARY_API_KEY",
apiSecret: "CLOUDINARY_API_SECRET",
},
});
async function run() {
const result = await cloudinaryConfig.transformations.listTransformations(
20,
"8edbc61040178db60b0973ca9494bf3a",
);
console.log(result);
}
run();
The TypeScript SDK makes API calls using an HTTPClient
that wraps the native
Fetch API. This
client is a thin wrapper around fetch
and provides the ability to attach hooks
around the request lifecycle that can be used to modify the request or handle
errors and response.
The HTTPClient
constructor takes an optional fetcher
argument that can be
used to integrate a third-party HTTP client or when writing tests to mock out
the HTTP client and feed in fixtures.
The following example shows how to use the "beforeRequest"
hook to to add a
custom header and a timeout to requests and how to use the "requestError"
hook
to log errors:
import { CloudinaryConfig } from "@cloudinary/config";
import { HTTPClient } from "@cloudinary/config/lib/http";
const httpClient = new HTTPClient({
// fetcher takes a function that has the same signature as native `fetch`.
fetcher: (request) => {
return fetch(request);
}
});
httpClient.addHook("beforeRequest", (request) => {
const nextRequest = new Request(request, {
signal: request.signal || AbortSignal.timeout(5000)
});
nextRequest.headers.set("x-custom-header", "custom value");
return nextRequest;
});
httpClient.addHook("requestError", (error, request) => {
console.group("Request Error");
console.log("Reason:", `${error}`);
console.log("Endpoint:", `${request.method} ${request.url}`);
console.groupEnd();
});
const sdk = new CloudinaryConfig({ httpClient });
You can setup your SDK to emit debug logs for SDK requests and responses.
You can pass a logger that matches console
's interface as an SDK option.
Warning
Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.
import { CloudinaryConfig } from "@cloudinary/config";
const sdk = new CloudinaryConfig({ debugLogger: console });
You can also enable a default debug logger by setting an environment variable CLOUDINARY_DEBUG
to true.