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:



1039
1040
1041
 
# File 'lib/cloudinary/api.rb', line 1039

def self.add_metadata_field(field, options = {})
  call_metadata_api(:post, [], prepare_metadata_field_params(field), 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:



1218
1219
1220
1221
1222
 
# File 'lib/cloudinary/api.rb', line 1218

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:



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

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:



460
461
462
463
464
 
# File 'lib/cloudinary/api.rb', line 460

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:



1272
1273
1274
1275
1276
1277
1278
1279
1280
 
# File 'lib/cloudinary/api.rb', line 1272

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

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

Retrieves account configuration details.

Parameters:

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

    The optional parameters.

Returns:

Raises:

See Also:



26
27
28
29
30
31
 
# File 'lib/cloudinary/api.rb', line 26

def self.config(options={})
  uri = "config"
  params = only(options, :settings)

  call_api(:get, 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:



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

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:



857
858
859
860
861
862
863
864
 
# File 'lib/cloudinary/api.rb', line 857

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:



603
604
605
606
607
608
609
610
 
# File 'lib/cloudinary/api.rb', line 603

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:



838
839
840
841
842
 
# File 'lib/cloudinary/api.rb', line 838

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:



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

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:



367
368
369
370
371
372
 
# File 'lib/cloudinary/api.rb', line 367

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:



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

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:



421
422
423
424
425
426
427
428
429
 
# File 'lib/cloudinary/api.rb', line 421

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:



406
407
408
409
 
# File 'lib/cloudinary/api.rb', line 406

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:



732
733
734
 
# File 'lib/cloudinary/api.rb', line 732

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:



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

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:



1257
1258
1259
1260
1261
 
# File 'lib/cloudinary/api.rb', line 1257

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:



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

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:



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

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:



327
328
329
330
331
332
 
# File 'lib/cloudinary/api.rb', line 327

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:



348
349
350
351
352
353
 
# File 'lib/cloudinary/api.rb', line 348

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:



387
388
389
390
391
 
# File 'lib/cloudinary/api.rb', line 387

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:



892
893
894
 
# File 'lib/cloudinary/api.rb', line 892

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:



566
567
568
 
# File 'lib/cloudinary/api.rb', line 566

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:



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

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:



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

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:



989
990
991
992
993
994
995
996
997
998
 
# File 'lib/cloudinary/api.rb', line 989

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:



906
907
908
 
# File 'lib/cloudinary/api.rb', line 906

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:



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

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:



1203
1204
1205
 
# File 'lib/cloudinary/api.rb', line 1203

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:



873
874
875
 
# File 'lib/cloudinary/api.rb', line 873

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:



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

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

.prepare_metadata_field_params(field) ⇒ Object

Prepares optional parameters for add/update_metadata_field API calls.

Parameters:

  • options (Hash) —

    Additional options

Returns:

  • (Object) —

    Optional parameters



1065
1066
1067
1068
1069
1070
 
# File 'lib/cloudinary/api.rb', line 1065

def self.prepare_metadata_field_params(field)
  only(field,
       :type, :external_id, :label, :mandatory, :restrictions, :default_value, :default_disabled,
       :validation, :datasource, :allow_dynamic_list_values
  )
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:



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

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:



1171
1172
1173
1174
1175
1176
 
# File 'lib/cloudinary/api.rb', line 1171

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:



1187
1188
1189
1190
1191
1192
 
# File 'lib/cloudinary/api.rb', line 1187

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:



230
231
232
233
234
235
 
# File 'lib/cloudinary/api.rb', line 230

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:



249
250
251
252
 
# File 'lib/cloudinary/api.rb', line 249

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:



66
67
68
 
# File 'lib/cloudinary/api.rb', line 66

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:



82
83
84
85
86
87
88
 
# File 'lib/cloudinary/api.rb', line 82

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:



196
197
198
199
 
# File 'lib/cloudinary/api.rb', line 196

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:



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

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:



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

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:



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

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:



123
124
125
126
127
 
# File 'lib/cloudinary/api.rb', line 123

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:



103
104
105
106
107
 
# File 'lib/cloudinary/api.rb', line 103

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:



266
267
268
269
270
271
 
# File 'lib/cloudinary/api.rb', line 266

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:



1154
1155
1156
1157
1158
1159
 
# File 'lib/cloudinary/api.rb', line 1154

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:



697
698
699
700
 
# File 'lib/cloudinary/api.rb', line 697

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:



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

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:



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

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:



544
545
546
547
548
 
# File 'lib/cloudinary/api.rb', line 544

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:



527
528
529
 
# File 'lib/cloudinary/api.rb', line 527

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:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/cloudinary/api.rb', line 287

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:



1056
1057
1058
1059
1060
 
# File 'lib/cloudinary/api.rb', line 1056

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

  call_metadata_api(:put, uri, prepare_metadata_field_params(field), 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:



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

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:



1237
1238
1239
1240
1241
1242
 
# File 'lib/cloudinary/api.rb', line 1237

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:



972
973
974
 
# File 'lib/cloudinary/api.rb', line 972

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:



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

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:



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

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:



923
924
925
926
927
928
929
 
# File 'lib/cloudinary/api.rb', line 923

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:



584
585
586
587
588
589
 
# File 'lib/cloudinary/api.rb', line 584

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:



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

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:



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

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:



792
793
794
 
# File 'lib/cloudinary/api.rb', line 792

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:



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

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:



638
639
640
 
# File 'lib/cloudinary/api.rb', line 638

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:



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

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:



47
48
49
50
51
52
53
54
 
# File 'lib/cloudinary/api.rb', line 47

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:



208
209
210
211
212
213
 
# File 'lib/cloudinary/api.rb', line 208

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