Class: Cloudinary::Api

Inherits:
Object show all
Extended by:
BaseApi
Defined in:
lib/cloudinary/api.rb

Class Method Summary collapse

Methods included from BaseApi

call_json_api, extended

Class Method Details

.add_metadata_field(field, options = {}) ⇒ Cloudinary::Api::Response

Creates a new metadata field definition.

Parameters:

  • field (Hash) —

    The field to add.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1023
1024
1025
1026
1027
 
# File 'lib/cloudinary/api.rb', line 1023

def self.add_metadata_field(field, options = {})
  params = only(field, :type, :external_id, :label, :mandatory, :default_value, :validation, :datasource)

  call_metadata_api(:post, [], params, options)
end

.add_metadata_rule(rule, options = {}) ⇒ Cloudinary::Api::Response

Creates a new metadata rule definition.

Parameters:

  • rule (Hash) —

    The rule to add.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1195
1196
1197
1198
1199
 
# File 'lib/cloudinary/api.rb', line 1195

def self.add_metadata_rule(rule, options = {})
  params = only(rule, :metadata_field_id, :condition, :result, :name)

  call_metadata_rules_api(:post, [], params, options)
end

.add_related_assets(public_id, assets_to_relate, options = {}) ⇒ Cloudinary::Api::Response

Relates an asset to other assets by public IDs.

Parameters:

  • public_id (String) —

    The public ID of the asset.

  • assets_to_relate (String|Array) —

    The array of up to 10 fully_qualified_public_ids given as resource_type/type/public_id.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:



426
427
428
429
430
431
432
 
# File 'lib/cloudinary/api.rb', line 426

def self.add_related_assets(public_id, assets_to_relate, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/related_assets/#{resource_type}/#{type}/#{public_id}"
  params = {:assets_to_relate => Cloudinary::Utils.build_array(assets_to_relate)}
  call_api(:post, uri, params, options)
end

.add_related_assets_by_asset_ids(asset_id, assets_to_relate, options = {}) ⇒ Cloudinary::Api::Response

Relates an asset to other assets by asset IDs.

Parameters:

  • asset_id (String) —

    The asset ID of the asset to update.

  • assets_to_relate (String|Array) —

    The array of up to 10 asset IDs.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:



444
445
446
447
448
 
# File 'lib/cloudinary/api.rb', line 444

def self.add_related_assets_by_asset_ids(asset_id, assets_to_relate, options={})
  uri           = "resources/related_assets/#{asset_id}"
  params = {:assets_to_relate => Cloudinary::Utils.build_array(assets_to_relate)}
  call_api(:post, uri, params, options)
end

.analyze(input_type, analysis_type, options = {}) ⇒ Cloudinary::Api::Response

Analyzes an asset with the requested analysis type.

Parameters:

  • input_type (Object) —

    The type of input for the asset to analyze (‘uri’).

  • analysis_type (Object) —

    The type of analysis to run (‘google_tagging’, ‘captioning’, ‘fashion’).

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:



1249
1250
1251
1252
1253
1254
1255
1256
1257
 
# File 'lib/cloudinary/api.rb', line 1249

def self.analyze(input_type, analysis_type, options = {})
  api_uri = ["analysis", "analyze", input_type]
  params = only(options, :uri, :parameters)
  params["analysis_type"] = analysis_type

  options[:api_version] = 'v2'

  call_api(:post, api_uri, params, options)
end

.create_folder(folder_name, options = {}) ⇒ Cloudinary::Api::Response

Creates a new empty folder.

Parameters:

  • folder_name (String) —

    The full path of the new folder to create.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



730
731
732
 
# File 'lib/cloudinary/api.rb', line 730

def self.create_folder(folder_name, options={})
  call_api(:post, "folders/#{folder_name}", {}, options)
end

.create_streaming_profile(name, options = {}) ⇒ Cloudinary::Api::Response

Creates a new, custom streaming profile.

Parameters:

  • name (String) —

    The name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-). If the name is of a predefined profile, the profile will be modified.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



841
842
843
844
845
846
847
848
 
# File 'lib/cloudinary/api.rb', line 841

def self.create_streaming_profile(name, options={})
  params = only(options, :display_name, :representations)
  params[:representations] = params[:representations].map do |r|
    {:transformation => Cloudinary::Utils.generate_transformation_string(r[:transformation])}
  end.to_json
  params[:name] = name
  call_api(:post, 'streaming_profiles', params, options)
end

.create_transformation(name, definition, options = {}) ⇒ Cloudinary::Api::Response

Creates a named transformation.

Parameters:

  • name (String) —

    The name of the transformation.

  • definition (String|Hash) —

    The transformation. Can be a string or a hash. For example: “w_150,h_100,c_fill” or {“width” => 150, “height” => 100, “crop” => “fill”}.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



587
588
589
590
591
592
593
594
 
# File 'lib/cloudinary/api.rb', line 587

def self.create_transformation(name, definition, options={})
  params = {
    :name => name,
    :transformation => Cloudinary::Utils.build_eager(definition)
  }

  call_api(:post, "transformations", params, options)
end

.create_upload_mapping(name, options = {}) ⇒ Cloudinary::Api::Response

Creates a new upload mapping.

Parameters:

  • name (String) —

    The name of the folder to map.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



822
823
824
825
826
 
# File 'lib/cloudinary/api.rb', line 822

def self.create_upload_mapping(name, options={})
  params          = only(options, :template)
  params[:folder] = name
  call_api(:post, 'upload_mappings', params, options)
end

.create_upload_preset(options = {}) ⇒ Cloudinary::Api::Response

Creates a new upload preset.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



666
667
668
669
 
# File 'lib/cloudinary/api.rb', line 666

def self.create_upload_preset(options={})
  params = Cloudinary::Uploader.build_upload_params(options, true)
  call_api(:post, "upload_presets", params.merge(only(options, :name, :unsigned, :disallow_public_id, :live)), options)
end

.delete_all_resources(options = {}) ⇒ Cloudinary::Api::Response

Deletes all assets of the specified asset and delivery type, including their derived assets.

Supports deleting up to a maximum of 1000 original assets in a single call.

cloudinary.com/documentation/admin_api#delete_resources

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:



351
352
353
354
355
356
 
# File 'lib/cloudinary/api.rb', line 351

def self.delete_all_resources(options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/#{resource_type}/#{type}"
  call_api(:delete, uri, delete_resource_params(options, :all => true ), options)
end

.delete_datasource_entries(field_external_id, entries_external_id, options = {}) ⇒ Cloudinary::Api::Response

Deletes entries in a metadata single or multi-select field’s datasource.

Deletes (blocks) the datasource (list) entries from the specified metadata field definition. Sets the state of the entries to inactive. This is a soft delete. The entries still exist in the database and can be reactivated using the restoreDatasourceEntries method.

Parameters:

  • field_external_id (String) —

    The ID of the field to update.

  • entries_external_id (Array) —

    The IDs of the entries to delete from the data source.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1083
1084
1085
1086
1087
1088
 
# File 'lib/cloudinary/api.rb', line 1083

def self.delete_datasource_entries(field_external_id, entries_external_id, options = {})
  uri = [field_external_id, "datasource"]
  params = {:external_ids => entries_external_id }

  call_metadata_api(:delete, uri, params, options)
end

.delete_derived_by_transformation(public_ids, transformations, options = {}) ⇒ Cloudinary::Api::Response

Deletes derived assets identified by transformation and public_ids.

Parameters:

  • public_ids (String|Array) —

    The public IDs for which you want to delete derived assets.

  • transformations (String|Array|Hash) —

    The transformation(s) associated with the derived assets to delete.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:



405
406
407
408
409
410
411
412
413
 
# File 'lib/cloudinary/api.rb', line 405

def self.delete_derived_by_transformation(public_ids, transformations, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/#{resource_type}/#{type}"
  params = {:public_ids => public_ids}.merge(only(options, :invalidate))
  params[:keep_original] = true
  params[:transformations] = Cloudinary::Utils.build_eager(transformations)
  call_api(:delete, uri, params, options)
end

.delete_derived_resources(derived_resource_ids, options = {}) ⇒ Cloudinary::Api::Response

Deletes the specified derived assets by derived asset ID.

The derived asset IDs for a particular original asset are returned when calling the resource method to return the details of a single asset.

Parameters:

  • derived_resource_ids (String|Array) —

    The derived asset IDs (up to 100 ids).

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



390
391
392
393
 
# File 'lib/cloudinary/api.rb', line 390

def self.delete_derived_resources(derived_resource_ids, options={})
  uri = "derived_resources"
  call_api(:delete, uri, { :derived_resource_ids => derived_resource_ids }, options)
end

.delete_folder(path, options = {}) ⇒ Cloudinary::Api::Response

Deletes an empty folder.

The specified folder cannot contain any assets, but can have empty descendant sub-folders.

Parameters:

  • path (String) —

    The full path of the empty folder to delete.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



716
717
718
 
# File 'lib/cloudinary/api.rb', line 716

def self.delete_folder(path, options={})
  call_api(:delete, "folders/#{path}", {}, options)
end

.delete_metadata_field(field_external_id, options = {}) ⇒ Cloudinary::Api::Response

Deletes a metadata field definition by external ID.

The external ID is immutable. Therefore, once deleted, the field’s external ID can no longer be used for future purposes.

Parameters:

  • field_external_id (String) —

    The ID of the field to delete.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1062
1063
1064
1065
1066
 
# File 'lib/cloudinary/api.rb', line 1062

def self.delete_metadata_field(field_external_id, options = {})
  uri = [field_external_id]

  call_metadata_api(:delete, uri, {}, options)
end

.delete_metadata_rule(external_id, options = {}) ⇒ Cloudinary::Api::Response

Deletes a metadata rule definition by external ID.

The rule should no longer be considered a valid candidate for all other endpoints (it will not show up in the list of rules, etc).

Parameters:

  • external_id (String) —

    The ID of the rule to delete.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1234
1235
1236
1237
1238
 
# File 'lib/cloudinary/api.rb', line 1234

def self.delete_metadata_rule(external_id, options = {})
  uri = [external_id]

  call_metadata_rules_api(:delete, uri, {}, options)
end

.delete_related_assets(public_id, assets_to_unrelate, options = {}) ⇒ Cloudinary::Api::Response

Unrelates an asset from other assets by public IDs.

Parameters:

  • public_id (String) —

    The public ID of the asset.

  • assets_to_unrelate (String|Array) —

    The array of up to 10 fully_qualified_public_ids given as resource_type/type/public_id.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:



461
462
463
464
465
466
467
 
# File 'lib/cloudinary/api.rb', line 461

def self.delete_related_assets(public_id, assets_to_unrelate, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/related_assets/#{resource_type}/#{type}/#{public_id}"
  params = {:assets_to_unrelate => Cloudinary::Utils.build_array(assets_to_unrelate)}
  call_api(:delete, uri, params, options)
end

.delete_related_assets_by_asset_ids(asset_id, assets_to_unrelate, options = {}) ⇒ Cloudinary::Api::Response

Unrelates an asset from other assets by asset IDs.

Parameters:

  • asset_id (String) —

    The asset ID of the asset to update.

  • assets_to_unrelate (String|Array) —

    The array of up to 10 asset IDs.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:



479
480
481
482
483
 
# File 'lib/cloudinary/api.rb', line 479

def self.delete_related_assets_by_asset_ids(asset_id, assets_to_unrelate, options={})
  uri           = "resources/related_assets/#{asset_id}"
  params = {:assets_to_unrelate => Cloudinary::Utils.build_array(assets_to_unrelate)}
  call_api(:delete, uri, params, options)
end

.delete_resources(public_ids, options = {}) ⇒ Cloudinary::Api::Response

Deletes the specified assets.

Parameters:

  • public_ids (String|Array) —

    The public IDs of the assets to delete (up to 100).

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



311
312
313
314
315
316
 
# File 'lib/cloudinary/api.rb', line 311

def self.delete_resources(public_ids, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/#{resource_type}/#{type}"
  call_api(:delete, uri, delete_resource_params(options, :public_ids => public_ids ), options)
end

.delete_resources_by_prefix(prefix, options = {}) ⇒ Cloudinary::Api::Response

Deletes assets by prefix.

Delete up to 1000 original assets, along with their derived assets, where the public ID starts with the specified prefix.

Parameters:

  • prefix (String) —

    The Public ID prefix.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



332
333
334
335
336
337
 
# File 'lib/cloudinary/api.rb', line 332

def self.delete_resources_by_prefix(prefix, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/#{resource_type}/#{type}"
  call_api(:delete, uri, delete_resource_params(options, :prefix => prefix), options)
end

.delete_resources_by_tag(tag, options = {}) ⇒ Cloudinary::Api::Response

Deletes assets with the specified tag, including their derived assets.

Supports deleting up to a maximum of 1000 original assets in a single call.

Admin API documentation.

Parameters:

  • tag (String) —

    The tag value of the assets to delete.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the

Returns:

Raises:

See Also:



371
372
373
374
375
 
# File 'lib/cloudinary/api.rb', line 371

def self.delete_resources_by_tag(tag, options={})
  resource_type = options[:resource_type] || "image"
  uri           = "resources/#{resource_type}/tags/#{tag}"
  call_api(:delete, uri, delete_resource_params(options), options)
end

.delete_streaming_profile(name, options = {}) ⇒ Cloudinary::Api::Response

Deletes or reverts the specified streaming profile.

For custom streaming profiles, deletes the specified profile. For built-in streaming profiles, if the built-in profile was modified, reverts the profile to the original settings. For built-in streaming profiles that have not been modified, the Delete method returns an error.

Parameters:

  • name (String) —

    The name of the streaming profile to delete or revert.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



876
877
878
 
# File 'lib/cloudinary/api.rb', line 876

def self.delete_streaming_profile(name, options={})
  call_api(:delete, "streaming_profiles/#{name}", {}, options)
end

.delete_transformation(transformation, options = {}) ⇒ Cloudinary::Api::Response

Deletes the specified stored transformation.

Deleting a transformation also deletes all the stored derived assets based on this transformation (up to 1000). The method returns an error if there are more than 1000 derived assets based on this transformation.

Parameters:

  • transformation (String|Hash) —

    The transformation to delete. Can be either a string or an array of parameters. For example: “w_150,h_100,c_fill” or {“width” => 150, “height” => 100,“crop” => “fill”}.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



550
551
552
 
# File 'lib/cloudinary/api.rb', line 550

def self.delete_transformation(transformation, options={})
  call_api(:delete, "transformations", {:transformation => Cloudinary::Utils.build_eager(transformation)}, options)
end

.delete_upload_mapping(name, options = {}) ⇒ Cloudinary::Api::Response

Deletes an upload mapping.

Parameters:

  • name (String) —

    The name of the upload mapping folder to delete.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



790
791
792
 
# File 'lib/cloudinary/api.rb', line 790

def self.delete_upload_mapping(name, options={})
  call_api(:delete, 'upload_mappings', { :folder => name }, options)
end

.delete_upload_preset(name, options = {}) ⇒ Cloudinary::Api::Response

Deletes the specified upload preset.

Parameters:

  • The (String) —

    name of the upload preset to delete.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



636
637
638
 
# File 'lib/cloudinary/api.rb', line 636

def self.delete_upload_preset(name, options={})
  call_api(:delete, "upload_presets/#{name}", {}, options)
end

.get_breakpoints(public_id, options) ⇒ Cloudinary::Api::Response

Gets the breakpoints.

Returns breakpoints if defined, otherwise checks the cache(if configured), otherwise fall backs to static calculation.

Parameters:

  • public_id (String) —

    Resource source.

  • options (Hash) —

    The optional parameters.

Returns:

Raises:



973
974
975
976
977
978
979
980
981
982
 
# File 'lib/cloudinary/api.rb', line 973

def self.get_breakpoints(public_id, options)
  local_options = options.clone
  base_transformation = Cloudinary::Utils.generate_transformation_string(local_options)
  srcset = local_options[:srcset]
  breakpoints = [:min_width, :max_width, :bytes_step, :max_images].map {|k| srcset[k]}.join('_')

  local_options[:transformation] = [base_transformation, width: "auto:breakpoints_#{breakpoints}:json"]
  json_url = Cloudinary::Utils.cloudinary_url public_id, local_options
  call_json_api('GET', json_url, {}, 60, {})
end

.get_streaming_profile(name, options = {}) ⇒ Cloudinary::Api::Response

Gets details of a single streaming profile by name.

Parameters:

  • name (String) —

    The identification name of the streaming profile.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



890
891
892
 
# File 'lib/cloudinary/api.rb', line 890

def self.get_streaming_profile(name, options={})
  call_api(:get, "streaming_profiles/#{name}", {}, options)
end

.list_metadata_fields(options = {}) ⇒ Cloudinary::Api::Response

Lists all metadata field definitions.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



993
994
995
 
# File 'lib/cloudinary/api.rb', line 993

def self.list_metadata_fields(options = {})
  call_metadata_api(:get, [], {}, options)
end

.list_metadata_rules(options = {}) ⇒ Cloudinary::Api::Response

Lists all metadata rules definitions.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1180
1181
1182
 
# File 'lib/cloudinary/api.rb', line 1180

def self.list_metadata_rules(options = {})
  call_metadata_rules_api(:get, [], {}, options)
end

.list_streaming_profiles ⇒ Cloudinary::Api::Response

Lists streaming profiles including built-in and custom profiles.

Returns:

Raises:

See Also:



857
858
859
 
# File 'lib/cloudinary/api.rb', line 857

def self.list_streaming_profiles
  call_api(:get, 'streaming_profiles', {}, {})
end

.metadata_field_by_field_id(field_external_id, options = {}) ⇒ Cloudinary::Api::Response

Gets a single metadata field definition by external ID.

Parameters:

  • field_external_id (String) —

    The external ID of the field to retrieve.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1007
1008
1009
1010
1011
 
# File 'lib/cloudinary/api.rb', line 1007

def self.metadata_field_by_field_id(field_external_id, options = {})
  uri = [field_external_id]

  call_metadata_api(:get, uri, {}, options)
end

.ping(options = {}) ⇒ Cloudinary::Api::Response

Tests the reachability of the Cloudinary API.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



13
14
15
 
# File 'lib/cloudinary/api.rb', line 13

def self.ping(options={})
  call_api(:get, "ping", {}, options)
end

.rename_folder(from_path, to_path, options = {}) ⇒ Cloudinary::Api::Response

Renames existing asset folder.

Parameters:

  • from_path (String) —

    The full path of an existing asset folder.

  • to_path (String) —

    The full path of the new asset folder.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



745
746
747
 
# File 'lib/cloudinary/api.rb', line 745

def self.rename_folder(from_path, to_path, options={})
  call_api(:put, "folders/#{from_path}", {:to_folder => to_path}, options)
end

.reorder_metadata_field_datasource(field_external_id, order_by, direction = nil, options = {}) ⇒ Cloudinary::Api::Response

Reorders metadata field datasource. Currently supports only value.

Parameters:

  • field_external_id (String) —

    The ID of the metadata field

  • order_by (String) —

    Criteria for the order. Currently supports only value

  • direction (String) (defaults to: nil) —

    Optional (gets either asc or desc)

  • options (Hash) (defaults to: {}) —

    Configuration options

Returns:

Raises:



1148
1149
1150
1151
1152
1153
 
# File 'lib/cloudinary/api.rb', line 1148

def self.reorder_metadata_field_datasource(field_external_id, order_by, direction = nil, options = {})
  uri    = [field_external_id, "datasource", "order"]
  params = { :order_by => order_by, :direction => direction }

  call_metadata_api(:post, uri, params, options)
end

.reorder_metadata_fields(order_by, direction = nil, options = {}) ⇒ Cloudinary::Api::Response

Reorders metadata fields.

Parameters:

  • order_by (String) —

    Criteria for the order (one of the fields ‘label’, ‘external_id’, ‘created_at’).

  • direction (String) (defaults to: nil) —

    Optional (gets either asc or desc).

  • options (Hash) (defaults to: {}) —

    Configuration options.

Returns:

Raises:



1164
1165
1166
1167
1168
1169
 
# File 'lib/cloudinary/api.rb', line 1164

def self.reorder_metadata_fields(order_by, direction = nil, options = {})
  uri    = ["order"]
  params = { :order_by => order_by, :direction => direction }

  call_metadata_api(:put, uri, params, options)
end

.resource(public_id, options = {}) ⇒ Cloudinary::Api::Response

Returns the details of the specified asset and all its derived assets.

Note that if you only need details about the original asset, you can also use the Uploader::upload or Uploader::explicit methods, which return the same information and are not rate limited.

Parameters:

  • public_id (String) —

    The public ID of the asset.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



214
215
216
217
218
219
 
# File 'lib/cloudinary/api.rb', line 214

def self.resource(public_id, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/#{resource_type}/#{type}/#{public_id}"
  call_api(:get, uri, prepare_resource_details_params(options), options)
end

.resource_by_asset_id(asset_id, options = {}) ⇒ Cloudinary::Api::Response

Returns the details of the specified asset and all its derived assets by asset id.

Note that if you only need details about the original asset, you can also use the Uploader::upload or Uploader::explicit methods, which return the same information and are not rate limited.

Parameters:

Returns:

See Also:



233
234
235
236
 
# File 'lib/cloudinary/api.rb', line 233

def self.resource_by_asset_id(asset_id, options={})
  uri    = "resources/#{asset_id}"
  call_api(:get, uri, prepare_resource_details_params(options), options)
end

.resource_types(options = {}) ⇒ Cloudinary::Api::Response

Lists all uploaded assets filtered by any specified options.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



50
51
52
 
# File 'lib/cloudinary/api.rb', line 50

def self.resource_types(options={})
  call_api(:get, "resources", {}, options)
end

.resources(options = {}) ⇒ Cloudinary::Api::Response

Lists all uploaded assets filtered by any specified options.

see cloudinary.com/documentation/admin_api#get_resources Get all images

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



66
67
68
69
70
71
72
 
# File 'lib/cloudinary/api.rb', line 66

def self.resources(options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type]
  uri           = "resources/#{resource_type}"
  uri           += "/#{type}" unless type.blank?
  call_api(:get, uri, list_resources_params(options).merge(only(options, :prefix, :start_at)), options)
end

.resources_by_asset_folder(asset_folder, options = {}) ⇒ Cloudinary::Api::Response

Returns all assets stored directly in a specified asset folder, regardless of the public ID paths of those assets.

<a href=cloudinary.com/documentation/dynamic_folders#new_admin_api_endpoints target=“_blank”> Admin API</a> documentation.

Parameters:

  • asset_folder (String) —

    The requested asset folder.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the

Returns:

Raises:

See Also:



180
181
182
183
 
# File 'lib/cloudinary/api.rb', line 180

def self.resources_by_asset_folder(asset_folder, options={})
  uri = "resources/by_asset_folder"
  call_api(:get, uri, list_resources_params(options, :asset_folder => asset_folder), options)
end

.resources_by_asset_ids(asset_ids, options = {}) ⇒ Cloudinary::Api::Response

Lists assets with the specified asset IDs.

<a href=cloudinary.com/documentation/admin_api#get_resources target=“_blank”> Admin API</a> documentation.

Parameters:

  • asset_ids (Object) —

    The requested asset IDs.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the

Returns:

Raises:

See Also:



164
165
166
167
 
# File 'lib/cloudinary/api.rb', line 164

def self.resources_by_asset_ids(asset_ids, options={})
  uri = "resources/by_asset_ids"
  call_api(:get, uri, resources_params(options, :asset_ids => asset_ids), options)
end

.resources_by_context(key, value = nil, options = {}) ⇒ Cloudinary::Api::Response

Lists assets with the specified contextual metadata.

This method does not return matching deleted assets, even if they have been backed up.

Parameters:

  • key (String) —

    Only assets with this context key are returned.

  • value (String) (defaults to: nil) —

    Only assets with this context value for the specified context key are returned. If this parameter is not provided, all assets with the specified context key are returned, regardless of the key value.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



129
130
131
132
133
 
# File 'lib/cloudinary/api.rb', line 129

def self.resources_by_context(key, value=nil, options={})
  resource_type = options[:resource_type] || "image"
  uri           = "resources/#{resource_type}/context"
  call_api(:get, uri, list_resources_params(options, :key => key, :value => value), options)
end

.resources_by_ids(public_ids, options = {}) ⇒ Cloudinary::Api::Response

Lists assets with the specified public IDs.

Parameters:

  • public_ids (String|Array) —

    The requested public_ids (up to 100).

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



146
147
148
149
150
151
 
# File 'lib/cloudinary/api.rb', line 146

def self.resources_by_ids(public_ids, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/#{resource_type}/#{type}"
  call_api(:get, uri, resources_params(options, :public_ids => public_ids), options)
end

.resources_by_moderation(kind, status, options = {}) ⇒ Cloudinary::Api::Response

Lists assets currently in the specified moderation queue and status.

Parameters:

  • kind (String) —

    Type of image moderation queue to list. Valid values: “manual”, “webpurify”, “aws_rek”, or “metascan”.

  • status (String) —

    Only assets with this moderation status will be returned. Valid values: “pending”, “approved”, “rejected”.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



107
108
109
110
111
 
# File 'lib/cloudinary/api.rb', line 107

def self.resources_by_moderation(kind, status, options={})
  resource_type = options[:resource_type] || "image"
  uri           = "resources/#{resource_type}/moderations/#{kind}/#{status}"
  call_api(:get, uri, list_resources_params(options), options)
end

.resources_by_tag(tag, options = {}) ⇒ Cloudinary::Api::Response

Lists assets with the specified tag.

This method does not return matching deleted assets, even if they have been backed up.

Parameters:

  • tag (String) —

    The tag value.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



87
88
89
90
91
 
# File 'lib/cloudinary/api.rb', line 87

def self.resources_by_tag(tag, options={})
  resource_type = options[:resource_type] || "image"
  uri           = "resources/#{resource_type}/tags/#{tag}"
  call_api(:get, uri, list_resources_params(options), options)
end

.restore(public_ids, options = {}) ⇒ Cloudinary::Api::Response

Reverts to the latest backed up version of the specified deleted assets.

Parameters:

  • public_ids (String|Array) —

    The public IDs of the backed up assets to restore. They can be existing or deleted assets.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



250
251
252
253
254
255
 
# File 'lib/cloudinary/api.rb', line 250

def self.restore(public_ids, options={})
  resource_type = options[:resource_type] || "image"
  type          = options[:type] || "upload"
  uri           = "resources/#{resource_type}/#{type}/restore"
  call_api(:post, uri, { :public_ids => public_ids, :versions => options[:versions] }, options)
end

.restore_metadata_field_datasource(field_external_id, entries_external_ids, options = {}) ⇒ Cloudinary::Api::Response

Restore entries in a metadata field datasource.

Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition. Sets the state of the entries to active.

Parameters:

  • field_external_id (String) —

    The ID of the metadata field.

  • entries_external_ids (Array) —

    An array of IDs of datasource entries to restore (unblock).

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1131
1132
1133
1134
1135
1136
 
# File 'lib/cloudinary/api.rb', line 1131

def self.restore_metadata_field_datasource(field_external_id, entries_external_ids, options = {})
  uri = [field_external_id, "datasource_restore"]
  params = {:external_ids => entries_external_ids }

  call_metadata_api(:post, uri, params, options)
end

.root_folders(options = {}) ⇒ Cloudinary::Api::Response

Lists all root folders.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



681
682
683
684
 
# File 'lib/cloudinary/api.rb', line 681

def self.root_folders(options={})
  params = only(options, :max_results, :next_cursor)
  call_api(:get, "folders", params, options)
end

.subfolders(of_folder_path, options = {}) ⇒ Cloudinary::Api::Response

Lists sub-folders.

Returns the name and path of all the sub-folders of a specified parent folder. Limited to 2000 results.

Parameters:

  • of_folder_path (String) —

    The parent folder.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



699
700
701
702
 
# File 'lib/cloudinary/api.rb', line 699

def self.subfolders(of_folder_path, options={})
  params = only(options, :max_results, :next_cursor)
  call_api(:get, "folders/#{of_folder_path}", params, options)
end

.tags(options = {}) ⇒ Cloudinary::Api::Response

Lists all the tags currently used for a specified asset type.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



495
496
497
498
499
 
# File 'lib/cloudinary/api.rb', line 495

def self.tags(options={})
  resource_type = options[:resource_type] || "image"
  uri           = "tags/#{resource_type}"
  call_api(:get, uri, only(options, :next_cursor, :max_results, :prefix), options)
end

.transformation(transformation, options = {}) ⇒ Cloudinary::Api::Response

Returns the details of a single transformation.

Parameters:

  • transformation (String|Array) —

    The transformation. Can be either a string or an array of parameters. For example: “w_150,h_100,c_fill” or array(“width” => 150, “height” => 100,“crop” => “fill”).

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



528
529
530
531
532
 
# File 'lib/cloudinary/api.rb', line 528

def self.transformation(transformation, options={})
  params                  = only(options, :next_cursor, :max_results)
  params[:transformation] = Cloudinary::Utils.build_eager(transformation)
  call_api(:get, "transformations", params, options)
end

.transformations(options = {}) ⇒ Cloudinary::Api::Response

Lists stored transformations.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



511
512
513
 
# File 'lib/cloudinary/api.rb', line 511

def self.transformations(options={})
  call_api(:get, "transformations", only(options, :named, :next_cursor, :max_results), options)
end

.update(public_id, options = {}) ⇒ Cloudinary::Api::Response

Updates details of an existing asset.

Update one or more of the attributes associated with a specified asset. Note that you can also update most attributes of an existing asset using the Uploader::explicit method, which is not rate limited.

Parameters:

  • public_id (String|Array) —

    The public ID of the asset to update.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/cloudinary/api.rb', line 271

def self.update(public_id, options={})
  resource_type  = options[:resource_type] || "image"
  type           = options[:type] || "upload"
  uri            = "resources/#{resource_type}/#{type}/#{public_id}"
  update_options = {
    :access_control     => Cloudinary::Utils.json_array_param(options[:access_control]),
    :asset_folder       => options[:asset_folder],
    :auto_tagging       => options[:auto_tagging] && options[:auto_tagging].to_f,
    :background_removal => options[:background_removal],
    :categorization     => options[:categorization],
    :context            => Cloudinary::Utils.encode_context(options[:context]),
    :custom_coordinates => Cloudinary::Utils.encode_double_array(options[:custom_coordinates]),
    :detection          => options[:detection],
    :display_name       => options[:display_name],
    :face_coordinates   => Cloudinary::Utils.encode_double_array(options[:face_coordinates]),
    :metadata           => Cloudinary::Utils.encode_context(options[:metadata]),
    :moderation_status  => options[:moderation_status],
    :notification_url   => options[:notification_url],
    :quality_override   => options[:quality_override],
    :ocr                => options[:ocr],
    :raw_convert        => options[:raw_convert],
    :similarity_search  => options[:similarity_search],
    :tags               => options[:tags] && Cloudinary::Utils.build_array(options[:tags]).join(","),
    :clear_invalid      => Cloudinary::Utils.as_safe_bool(options[:clear_invalid]),
    :unique_display_name=> options[:unique_display_name]
  }
  call_api(:post, uri, update_options, options)
end

.update_metadata_field(field_external_id, field, options = {}) ⇒ Cloudinary::Api::Response

Updates a metadata field by external ID.

Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data.

Parameters:

  • field_external_id (String) —

    The ID of the field to update.

  • field (Hash) —

    The field definition.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1042
1043
1044
1045
1046
1047
 
# File 'lib/cloudinary/api.rb', line 1042

def self.update_metadata_field(field_external_id, field, options = {})
  uri = [field_external_id]
  params = only(field, :label, :mandatory, :default_value, :validation)

  call_metadata_api(:put, uri, params, options)
end

.update_metadata_field_datasource(field_external_id, entries_external_id, options = {}) ⇒ Cloudinary::Api::Response

Updates a metadata field datasource.

Updates the datasource of a supported field type (currently enum or set), passed as JSON data. The update is partial: datasource entries with an existing external_id will be updated and entries with new external_id’s (or without external_id’s) will be appended.

Parameters:

  • field_external_id (String) —

    The ID of the field to update.

  • entries_external_id (Array) —

    A list of datasource entries. Existing entries (according to entry id) will be updated. New entries will be added.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
 
# File 'lib/cloudinary/api.rb', line 1106

def self.update_metadata_field_datasource(field_external_id, entries_external_id, options = {})
  uri = [field_external_id, "datasource"]

  params = entries_external_id.each_with_object({:values => [] }) do |item, hash|
    item = only(item, :external_id, :value)
    hash[:values ] << item if item.present?
  end

  call_metadata_api(:put, uri, params, options)
end

.update_metadata_rule(external_id, rule, options = {}) ⇒ Cloudinary::Api::Response

Updates a metadata rule by external ID.

Updates an existing metadata rule definition. Expects a JSON object which defines the updated rule.

Parameters:

  • external_id (String) —

    The ID of the rule to update.

  • rule (Hash) —

    The rule definition.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



1214
1215
1216
1217
1218
1219
 
# File 'lib/cloudinary/api.rb', line 1214

def self.update_metadata_rule(external_id, rule, options = {})
  uri = [external_id]
  params = only(rule, :metadata_field_id, :condition, :result, :name, :state)

  call_metadata_rules_api(:put, uri, params, options)
end

.update_resources_access_mode_by_ids(access_mode, public_ids, options = {}) ⇒ Cloudinary::Api::Response

Update resources access mode. Resources are selected by the provided public_ids.

Parameters:

  • access_mode (String) —

    The access mode to set the resources to.

  • public_ids (Array) —

    The ids by which to filter applicable resources

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



956
957
958
 
# File 'lib/cloudinary/api.rb', line 956

def self.update_resources_access_mode_by_ids(access_mode, public_ids, options = {})
  update_resources_access_mode(access_mode, :public_ids, public_ids, options)
end

.update_resources_access_mode_by_prefix(access_mode, prefix, options = {}) ⇒ Cloudinary::Api::Response

Update resources access mode. Resources are selected by the prefix.

Parameters:

  • access_mode (String) —

    The access mode to set the resources to.

  • prefix (String) —

    The prefix by which to filter applicable resources

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



926
927
928
 
# File 'lib/cloudinary/api.rb', line 926

def self.update_resources_access_mode_by_prefix(access_mode, prefix, options = {})
  update_resources_access_mode(access_mode, :prefix, prefix, options)
end

.update_resources_access_mode_by_tag(access_mode, tag, options = {}) ⇒ Cloudinary::Api::Response

Update resources access mode. Resources are selected by the tag.

Parameters:

  • access_mode (String) —

    The access mode to set the resources to.

  • tag (String) —

    The tag by which to filter applicable resources.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



941
942
943
 
# File 'lib/cloudinary/api.rb', line 941

def self.update_resources_access_mode_by_tag(access_mode, tag, options = {})
  update_resources_access_mode(access_mode, :tag, tag, options)
end

.update_streaming_profile(name, options = {}) ⇒ Cloudinary::Api::Response

Updates an existing streaming profile.

You can update both custom and built-in profiles. The specified list of representations replaces the previous list.

Admin API documentation.

Parameters:

  • name (String) —

    The name of the streaming profile to update.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the

Returns:

Raises:

See Also:



907
908
909
910
911
912
913
 
# File 'lib/cloudinary/api.rb', line 907

def self.update_streaming_profile(name, options={})
  params = only(options, :display_name, :representations)
  params[:representations] = params[:representations].map do |r|
    {:transformation => Cloudinary::Utils.generate_transformation_string(r[:transformation])}
  end.to_json
  call_api(:put, "streaming_profiles/#{name}", params, options)
end

.update_transformation(transformation, updates, options = {}) ⇒ Cloudinary::Api::Response

Updates the specified transformation.

Parameters:

  • transformation (String|Hash) —

    The transformation. Can be either a string or an array of parameters. For example: “w_150,h_100,c_fill” or {“width” => 150, “height” => 100,“crop” => “fill”}.

  • updates (Hash) —

    The update parameters. See the Admin API documentation.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



568
569
570
571
572
573
 
# File 'lib/cloudinary/api.rb', line 568

def self.update_transformation(transformation, updates, options={})
  params                  = only(updates, :allowed_for_strict)
  params[:unsafe_update]  = Cloudinary::Utils.build_eager(updates[:unsafe_update]) if updates[:unsafe_update]
  params[:transformation] = Cloudinary::Utils.build_eager(transformation)
  call_api(:put, "transformations", params, options)
end

.update_upload_mapping(name, options = {}) ⇒ Cloudinary::Api::Response

Updates an existing upload mapping with a new template (URL).

Parameters:

  • name (String) —

    The name of the upload mapping folder to remap.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



805
806
807
808
809
 
# File 'lib/cloudinary/api.rb', line 805

def self.update_upload_mapping(name, options={})
  params          = only(options, :template)
  params[:folder] = name
  call_api(:put, 'upload_mappings', params, options)
end

.update_upload_preset(name, options = {}) ⇒ Cloudinary::Api::Response

Updates the specified upload preset.

Admin API documentation.

Parameters:

  • name (String) —

    The name of the upload preset.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the

Returns:

Raises:

See Also:



651
652
653
654
 
# File 'lib/cloudinary/api.rb', line 651

def self.update_upload_preset(name, options={})
  params = Cloudinary::Uploader.build_upload_params(options, true)
  call_api(:put, "upload_presets/#{name}", params.merge(only(options, :unsigned, :disallow_public_id, :live)), options)
end

.upload_mapping(name = nil, options = {}) ⇒ Cloudinary::Api::Response

Returns the details of the specified upload mapping.

Retrieve the mapped template (URL) of a specified upload mapping folder.

Parameters:

  • name (String) (defaults to: nil) —

    The name of the upload mapping folder.

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:

See Also:



776
777
778
 
# File 'lib/cloudinary/api.rb', line 776

def self.upload_mapping(name=nil, options={})
  call_api(:get, 'upload_mappings', { :folder => name }, options)
end

.upload_mappings(options = {}) ⇒ Cloudinary::Api::Response

Lists upload mappings by folder and its mapped template (URL).

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



759
760
761
762
 
# File 'lib/cloudinary/api.rb', line 759

def self.upload_mappings(options={})
  params = only(options, :next_cursor, :max_results)
  call_api(:get, :upload_mappings, params, options)
end

.upload_preset(name, options = {}) ⇒ Cloudinary::Api::Response

Retrieves the details of the specified upload preset.

Parameters:

  • name (String) —

    The name of the upload preset.

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



622
623
624
 
# File 'lib/cloudinary/api.rb', line 622

def self.upload_preset(name, options={})
  call_api(:get, "upload_presets/#{name}", only(options, :max_results), options)
end

.upload_presets(options = {}) ⇒ Cloudinary::Api::Response

Lists existing upload presets.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

See Also:



606
607
608
 
# File 'lib/cloudinary/api.rb', line 606

def self.upload_presets(options={})
  call_api(:get, "upload_presets", only(options, :next_cursor, :max_results), options)
end

.usage(options = {}) ⇒ Cloudinary::Api::Response

Gets cloud usage details.

Returns a report detailing your current Cloudinary cloud usage details, including storage, bandwidth, requests, number of assets, and add-on usage. Note that numbers are updated periodically.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters. See the Admin API documentation.

Returns:

Raises:

  • (Cloudinary::Api:Error)

See Also:



31
32
33
34
35
36
37
38
 
# File 'lib/cloudinary/api.rb', line 31

def self.usage(options={})
  uri = 'usage'
  date = options[:date]

  uri += "/#{Cloudinary::Utils.to_usage_api_date_format(date)}" unless date.nil?

  call_api(:get, uri, {}, options)
end

.visual_search(options = {}) ⇒ Cloudinary::Api::Response

Find images based on their visual content.

Parameters:

  • options (Hash) (defaults to: {}) —

    The optional parameters.

Returns:

Raises:



192
193
194
195
196
197
 
# File 'lib/cloudinary/api.rb', line 192

def self.visual_search(options = {})
  uri    = "resources/visual_search"
  params = only(options, :image_url, :image_asset_id, :text, :image_file)
  params[:image_file] = Cloudinary::Utils.handle_file_param(params[:image_file]) if params.has_key?(:image_file)
  call_api(:post, uri, params, options)
end