Administrative operations for managing Cloudinary resources including listing, updating, deleting, and organizing assets. Provides comprehensive metadata management, folder operations, and account-level settings.
List and search resources in your Cloudinary account with various filtering options.
/**
* List resources in your account
* @param options - Filtering and pagination options
* @param callback - Callback function (v1 only)
* @returns Promise with resource list
*/
function resources(
options?: ResourceListOptions,
callback?: (error: any, result: ResourceApiResponse) => void
): Promise<ResourceApiResponse>;
/**
* Get details of a specific resource
* @param public_id - Public ID of the resource
* @param options - Resource options
* @param callback - Callback function (v1 only)
* @returns Promise with resource details
*/
function resource(
public_id: string,
options?: ResourceOptions,
callback?: (error: any, result: any) => void
): Promise<any>;
interface ResourceListOptions {
/** Resource type filter */
resource_type?: 'image' | 'video' | 'raw';
/** Asset type filter */
type?: string;
/** Maximum number of results */
max_results?: number;
/** Pagination cursor */
next_cursor?: string;
/** Public ID prefix filter */
prefix?: string;
/** Include tags in response */
tags?: boolean;
/** Include context metadata */
context?: boolean;
/** Include moderation status */
moderations?: boolean;
/** Sort by field and direction */
direction?: 'asc' | 'desc';
/** Starting date filter */
start_at?: string;
[key: string]: any;
}
interface ResourceApiResponse {
/** Array of resource objects */
resources: Resource[];
/** Next pagination cursor */
next_cursor?: string;
/** Total count */
total_count?: number;
/** Time taken for request */
time?: number;
[key: string]: any;
}
interface Resource {
/** Public ID */
public_id: string;
/** File format */
format: string;
/** Asset version */
version: number;
/** Resource type */
resource_type: string;
/** Asset type */
type: string;
/** Creation date */
created_at: string;
/** File size in bytes */
bytes: number;
/** Image/video width */
width: number;
/** Image/video height */
height: number;
/** Delivery URL */
url: string;
/** Secure delivery URL */
secure_url: string;
/** Assigned tags */
tags: string[];
/** Context metadata */
context?: Record<string, string>;
/** Custom metadata */
metadata?: Record<string, string>;
[key: string]: any;
}Usage Examples:
const cloudinary = require('cloudinary');
// List all resources
const result = await cloudinary.v2.api.resources();
console.log('Total resources:', result.resources.length);
// List with filtering and pagination
const result = await cloudinary.v2.api.resources({
resource_type: 'image',
type: 'upload',
max_results: 50,
tags: true,
context: true
});
// Get specific resource details
const resource = await cloudinary.v2.api.resource('my_image', {
colors: true,
faces: true,
image_metadata: true
});
console.log('Image dimensions:', resource.width, 'x', resource.height);Filter resources by various criteria including tags, context, and moderation status.
/**
* List resources by tag
* @param tag - Tag to filter by
* @param options - Additional filtering options
* @param callback - Callback function (v1 only)
* @returns Promise with tagged resources
*/
function resources_by_tag(
tag: string,
options?: ResourceListOptions,
callback?: (error: any, result: ResourceApiResponse) => void
): Promise<ResourceApiResponse>;
/**
* List resources by context metadata
* @param key - Context key
* @param value - Context value (optional)
* @param options - Additional filtering options
* @param callback - Callback function (v1 only)
* @returns Promise with filtered resources
*/
function resources_by_context(
key: string,
value?: string,
options?: ResourceListOptions,
callback?: (error: any, result: ResourceApiResponse) => void
): Promise<ResourceApiResponse>;
/**
* List resources by moderation status
* @param kind - Moderation service
* @param status - Moderation status
* @param options - Additional filtering options
* @param callback - Callback function (v1 only)
* @returns Promise with moderated resources
*/
function resources_by_moderation(
kind: 'manual' | 'webpurify' | 'aws_rek' | 'metascan',
status: 'pending' | 'approved' | 'rejected',
options?: ResourceListOptions,
callback?: (error: any, result: ResourceApiResponse) => void
): Promise<ResourceApiResponse>;
/**
* List resources by public IDs
* @param public_ids - Array of public IDs
* @param options - Additional options
* @param callback - Callback function (v1 only)
* @returns Promise with specified resources
*/
function resources_by_ids(
public_ids: string[],
options?: ResourceOptions,
callback?: (error: any, result: ResourceApiResponse) => void
): Promise<ResourceApiResponse>;Usage Examples:
const cloudinary = require('cloudinary');
// Get resources by tag
const taggedResources = await cloudinary.v2.api.resources_by_tag('product_images', {
max_results: 100
});
// Get resources by context
const contextResources = await cloudinary.v2.api.resources_by_context('category', 'electronics');
// Get resources by moderation status
const pendingResources = await cloudinary.v2.api.resources_by_moderation('manual', 'pending');
// Get specific resources by IDs
const specificResources = await cloudinary.v2.api.resources_by_ids([
'image1', 'image2', 'image3'
]);Update, delete, and manage individual resources or groups of resources.
/**
* Update resource metadata and properties
* @param public_id - Public ID of the resource to update
* @param options - Update options
* @param callback - Callback function (v1 only)
* @returns Promise with update result
*/
function update(
public_id: string,
options?: UpdateOptions,
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Delete resources by public IDs
* @param public_ids - Array of public IDs to delete
* @param options - Deletion options
* @param callback - Callback function (v1 only)
* @returns Promise with deletion results
*/
function delete_resources(
public_ids: string[],
options?: DeleteOptions,
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Delete resources by tag
* @param tag - Tag to delete resources by
* @param options - Deletion options
* @param callback - Callback function (v1 only)
* @returns Promise with deletion results
*/
function delete_resources_by_tag(
tag: string,
options?: DeleteOptions,
callback?: (error: any, result: any) => void
): Promise<any>;
interface UpdateOptions {
/** Tags to add or replace */
tags?: string | string[];
/** Context metadata to add or replace */
context?: string | Record<string, string>;
/** Custom metadata to add or replace */
metadata?: Record<string, string>;
/** New access mode */
access_mode?: 'public' | 'authenticated';
/** Auto tagging configuration */
auto_tagging?: number;
/** Background removal setting */
background_removal?: string;
/** Moderation status override */
moderation_status?: 'pending' | 'approved' | 'rejected';
[key: string]: any;
}
interface DeleteOptions {
/** Resource type */
resource_type?: 'image' | 'video' | 'raw';
/** Asset type */
type?: string;
/** Invalidate CDN cache */
invalidate?: boolean;
[key: string]: any;
}Usage Examples:
const cloudinary = require('cloudinary');
// Update resource metadata
const updateResult = await cloudinary.v2.api.update('my_image', {
tags: ['updated', 'featured'],
context: { category: 'hero_images', priority: 'high' },
metadata: { alt_text: 'Updated hero image' }
});
// Delete specific resources
const deleteResult = await cloudinary.v2.api.delete_resources([
'old_image1', 'old_image2'
], {
invalidate: true
});
// Delete resources by tag
const tagDeleteResult = await cloudinary.v2.api.delete_resources_by_tag('temporary', {
resource_type: 'image'
});Organize resources using folder structures and manage folder operations.
/**
* List root folders
* @param options - Listing options
* @param callback - Callback function (v1 only)
* @returns Promise with folder list
*/
function root_folders(
options?: { max_results?: number; next_cursor?: string },
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* List subfolders within a folder
* @param path - Parent folder path
* @param options - Listing options
* @param callback - Callback function (v1 only)
* @returns Promise with subfolder list
*/
function sub_folders(
path: string,
options?: { max_results?: number; next_cursor?: string },
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Create a new folder
* @param path - Folder path to create
* @param options - Creation options
* @param callback - Callback function (v1 only)
* @returns Promise with creation result
*/
function create_folder(
path: string,
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Delete a folder and its contents
* @param path - Folder path to delete
* @param options - Deletion options
* @param callback - Callback function (v1 only)
* @returns Promise with deletion result
*/
function delete_folder(
path: string,
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Rename a folder
* @param from_path - Current folder path
* @param to_path - New folder path
* @param options - Rename options
* @param callback - Callback function (v1 only)
* @returns Promise with rename result
*/
function rename_folder(
from_path: string,
to_path: string,
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;Usage Examples:
const cloudinary = require('cloudinary');
// List root folders
const rootFolders = await cloudinary.v2.api.root_folders();
console.log('Root folders:', rootFolders.folders.map(f => f.name));
// List subfolders
const subFolders = await cloudinary.v2.api.sub_folders('products');
// Create folder
await cloudinary.v2.api.create_folder('products/electronics');
// Rename folder
await cloudinary.v2.api.rename_folder('old_folder', 'new_folder');
// Delete empty folder
await cloudinary.v2.api.delete_folder('temp_folder');Manage named transformations for reusable transformation configurations.
/**
* List named transformations
* @param options - Listing options
* @param callback - Callback function (v1 only)
* @returns Promise with transformation list
*/
function transformations(
options?: { max_results?: number; next_cursor?: string },
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Get details of a named transformation
* @param transformation_name - Name of the transformation
* @param options - Additional options
* @param callback - Callback function (v1 only)
* @returns Promise with transformation details
*/
function transformation(
transformation_name: string,
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Create a named transformation
* @param name - Transformation name
* @param definition - Transformation definition
* @param options - Creation options
* @param callback - Callback function (v1 only)
* @returns Promise with creation result
*/
function create_transformation(
name: string,
definition: TransformationOptions,
options?: { allowed_for_strict?: boolean },
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Update a named transformation
* @param transformation_name - Name of the transformation
* @param updates - Updated transformation definition
* @param options - Update options
* @param callback - Callback function (v1 only)
* @returns Promise with update result
*/
function update_transformation(
transformation_name: string,
updates: TransformationOptions,
options?: { allowed_for_strict?: boolean },
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Delete a named transformation
* @param transformation_name - Name of the transformation to delete
* @param options - Deletion options
* @param callback - Callback function (v1 only)
* @returns Promise with deletion result
*/
function delete_transformation(
transformation_name: string,
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;Usage Examples:
const cloudinary = require('cloudinary');
// Create named transformation
await cloudinary.v2.api.create_transformation('product_thumb', {
width: 150,
height: 150,
crop: 'fill',
gravity: 'auto',
quality: 'auto',
fetch_format: 'auto'
});
// List transformations
const transformations = await cloudinary.v2.api.transformations();
// Update transformation
await cloudinary.v2.api.update_transformation('product_thumb', {
width: 200,
height: 200,
crop: 'fill',
gravity: 'auto',
quality: 'auto'
});
// Use named transformation in URL
const url = cloudinary.url('my_image', {
transformation: 'product_thumb'
});Get account-level information and usage statistics.
/**
* Get account usage statistics
* @param options - Usage options
* @param callback - Callback function (v1 only)
* @returns Promise with usage statistics
*/
function usage(
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* Ping the API to test connectivity
* @param options - Ping options
* @param callback - Callback function (v1 only)
* @returns Promise with ping result
*/
function ping(
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;
/**
* List available resource types
* @param options - Listing options
* @param callback - Callback function (v1 only)
* @returns Promise with resource types
*/
function resource_types(
options?: Record<string, any>,
callback?: (error: any, result: any) => void
): Promise<any>;Usage Examples:
const cloudinary = require('cloudinary');
// Check account usage
const usage = await cloudinary.v2.api.usage();
console.log('Storage used:', usage.storage.used_bytes);
console.log('Bandwidth used:', usage.bandwidth.used_bytes);
// Test API connectivity
const pingResult = await cloudinary.v2.api.ping();
console.log('API Status:', pingResult.status);
// List resource types
const types = await cloudinary.v2.api.resource_types();
console.log('Available types:', types.resource_types);interface ResourceListOptions {
resource_type?: 'image' | 'video' | 'raw';
type?: string;
max_results?: number;
next_cursor?: string;
prefix?: string;
tags?: boolean;
context?: boolean;
moderations?: boolean;
direction?: 'asc' | 'desc';
start_at?: string;
[key: string]: any;
}
interface ResourceOptions {
resource_type?: 'image' | 'video' | 'raw';
type?: string;
exif?: boolean;
colors?: boolean;
faces?: boolean;
image_metadata?: boolean;
pages?: boolean;
coordinates?: boolean;
[key: string]: any;
}
interface UpdateOptions {
tags?: string | string[];
context?: string | Record<string, string>;
metadata?: Record<string, string>;
access_mode?: 'public' | 'authenticated';
auto_tagging?: number;
background_removal?: string;
moderation_status?: 'pending' | 'approved' | 'rejected';
[key: string]: any;
}
interface DeleteOptions {
resource_type?: 'image' | 'video' | 'raw';
type?: string;
invalidate?: boolean;
[key: string]: any;
}
interface Resource {
public_id: string;
format: string;
version: number;
resource_type: string;
type: string;
created_at: string;
bytes: number;
width: number;
height: number;
url: string;
secure_url: string;
tags: string[];
context?: Record<string, string>;
metadata?: Record<string, string>;
[key: string]: any;
}
interface ResourceApiResponse {
resources: Resource[];
next_cursor?: string;
total_count?: number;
time?: number;
[key: string]: any;
}