0
# Admin API
1

2
Complete resource management including asset discovery, metadata operations, transformation management, and account administration.
3

4
## Capabilities
5

6
### Resource Discovery
7

8
List and search for uploaded resources with comprehensive filtering options.
9

10
```python { .api }
11
def resources(**options):
12
    """List uploaded resources with filtering options.
13
    
14
    Args:
15
        resource_type (str, optional): Filter by resource type ('image', 'video', 'raw')
16
        type (str, optional): Filter by delivery type ('upload', 'private', 'authenticated', 'fetch', 'multi', 'text', 'asset')
17
        prefix (str, optional): Filter by public_id prefix
18
        public_ids (list, optional): Specific public IDs to retrieve
19
        tags (bool, optional): Include tags in response
20
        context (bool, optional): Include context in response  
21
        metadata (bool, optional): Include metadata in response
22
        moderations (bool, optional): Include moderation status
23
        direction (str, optional): Sort direction ('asc', 'desc', default: 'desc')
24
        max_results (int, optional): Maximum results to return (default: 10, max: 500)
25
        next_cursor (str, optional): Cursor for pagination
26
        start_at (str, optional): Start listing from this public_id
27
        **kwargs: Additional filtering options
28
    
29
    Returns:
30
        dict: Response containing:
31
            - resources (list): List of resource objects with details
32
            - next_cursor (str): Cursor for next page (if more results exist)
33
            - rate_limit_allowed (int): Rate limit quota
34
            - rate_limit_reset_at (str): Rate limit reset time
35
            - rate_limit_remaining (int): Remaining rate limit quota
36
    """
37

38
def resources_by_tag(tag, **options):
39
    """List resources filtered by a specific tag.
40
    
41
    Args:
42
        tag (str): Tag to filter by
43
        **options: Same options as resources()
44
    
45
    Returns:
46
        dict: Response containing resources with the specified tag
47
    """
48

49
def resources_by_context(key, value=None, **options):
50
    """List resources filtered by context key-value pairs.
51
    
52
    Args:
53
        key (str): Context key to filter by
54
        value (str, optional): Context value to filter by (if not provided, matches any value for the key)
55
        **options: Same options as resources()
56
    
57
    Returns:
58
        dict: Response containing resources matching the context criteria
59
    """
60

61
def resources_by_moderation(kind, status, **options):
62
    """List resources filtered by moderation status.
63
    
64
    Args:
65
        kind (str): Moderation kind ('manual', 'webpurify', 'aws_rek', 'metascan')
66
        status (str): Moderation status ('pending', 'approved', 'rejected')
67
        **options: Same options as resources()
68
    
69
    Returns:
70
        dict: Response containing resources with specified moderation status
71
    """
72

73
def resources_by_ids(public_ids, **options):
74
    """Get resources by their public IDs.
75
    
76
    Args:
77
        public_ids (list): List of public IDs to retrieve
78
        **options: Additional options
79
    
80
    Returns:
81
        dict: Response containing the specified resources
82
    """
83
```
84

85
### Individual Resource Management
86

87
Get details and update properties of specific resources.
88

89
```python { .api }
90
def resource(public_id, **options):
91
    """Get details of a specific resource.
92
    
93
    Args:
94
        public_id (str): Public ID of the resource
95
        resource_type (str, optional): Type of resource ('image', 'video', 'raw')
96
        type (str, optional): Delivery type ('upload', 'private', 'authenticated')
97
        exif (bool, optional): Include EXIF data
98
        colors (bool, optional): Include color information
99
        faces (bool, optional): Include face detection data
100
        quality_analysis (bool, optional): Include quality analysis
101
        accessibility_analysis (bool, optional): Include accessibility analysis
102
        cinemagraph_analysis (bool, optional): Include cinemagraph analysis
103
        coordinates (bool, optional): Include custom coordinates
104
        max_results (int, optional): Maximum derived resources to return
105
        derived_next_cursor (str, optional): Cursor for derived resources pagination
106
        **kwargs: Additional options
107
    
108
    Returns:
109
        dict: Detailed resource information including:
110
            - public_id (str): Public identifier
111
            - format (str): File format
112
            - version (int): Version number
113
            - resource_type (str): Type of resource
114
            - type (str): Delivery type
115
            - created_at (str): Creation timestamp
116
            - bytes (int): File size
117
            - width (int): Width in pixels
118
            - height (int): Height in pixels
119
            - url (str): Public URL
120
            - secure_url (str): HTTPS URL
121
            - tags (list): Applied tags
122
            - context (dict): Context metadata
123
            - metadata (dict): Structured metadata
124
            - derived (list): Derived versions/transformations
125
            - And additional analysis data based on options
126
    """
127

128
def update(public_id, **options):
129
    """Update properties of an existing resource.
130
    
131
    Args:
132
        public_id (str): Public ID of the resource to update
133
        resource_type (str, optional): Type of resource
134
        type (str, optional): Delivery type
135
        tags (list, optional): Tags to replace existing tags
136
        context (dict, optional): Context to replace existing context
137
        metadata (dict, optional): Metadata to replace existing metadata
138
        face_coordinates (str, optional): Face coordinates to set
139
        custom_coordinates (str, optional): Custom coordinates to set
140
        auto_tagging (float, optional): Apply auto-tagging with confidence threshold
141
        categorization (str, optional): Apply categorization
142
        detection (str, optional): Apply object detection
143
        background_removal (str, optional): Apply background removal
144
        moderation_status (str, optional): Set moderation status
145
        raw_convert (str, optional): Convert raw file format
146
        quality_override (str, optional): Override quality analysis
147
        **kwargs: Additional update options
148
    
149
    Returns:
150
        dict: Updated resource information
151
    """
152
```
153

154
### Resource Deletion
155

156
Delete resources individually or in bulk with various filtering criteria.
157

158
```python { .api }
159
def delete_resources(public_ids, **options):
160
    """Delete multiple resources by public IDs.
161
    
162
    Args:
163
        public_ids (list): List of public IDs to delete
164
        resource_type (str, optional): Type of resources to delete
165
        type (str, optional): Delivery type of resources
166
        keep_original (bool, optional): Keep original files, delete only derivatives
167
        invalidate (bool, optional): Invalidate CDN cache
168
        next_cursor (str, optional): Cursor for batch processing
169
    
170
    Returns:
171
        dict: Deletion results with details of deleted and failed resources
172
    """
173

174
def delete_resources_by_prefix(prefix, **options):
175
    """Delete resources by public_id prefix.
176
    
177
    Args:
178
        prefix (str): Public ID prefix to match
179
        **options: Same options as delete_resources()
180
    
181
    Returns:
182
        dict: Deletion results
183
    """
184

185
def delete_resources_by_tag(tag, **options):
186
    """Delete resources by tag.
187
    
188
    Args:
189
        tag (str): Tag to match for deletion
190
        **options: Same options as delete_resources()
191
    
192
    Returns:
193
        dict: Deletion results
194
    """
195

196
def delete_all_resources(**options):
197
    """Delete all resources in the account.
198
    
199
    Args:
200
        **options: Same options as delete_resources()
201
    
202
    Returns:
203
        dict: Deletion results
204
    """
205

206
def delete_derived_resources(derived_resource_ids, **options):
207
    """Delete specific derived resources.
208
    
209
    Args:
210
        derived_resource_ids (list): List of derived resource IDs to delete
211
        **options: Additional deletion options
212
    
213
    Returns:
214
        dict: Deletion results
215
    """
216
```
217

218
### Tag Management
219

220
Manage tags across your resources.
221

222
```python { .api }
223
def tags(**options):
224
    """List all tags in your account.
225
    
226
    Args:
227
        max_results (int, optional): Maximum results to return
228
        next_cursor (str, optional): Cursor for pagination
229
        prefix (str, optional): Filter tags by prefix
230
    
231
    Returns:
232
        dict: Response containing:
233
            - tags (list): List of tag names
234
            - next_cursor (str): Cursor for next page
235
    """
236
```
237

238
### Transformation Management
239

240
Manage named transformations and eager transformations.
241

242
```python { .api }
243
def transformations(**options):
244
    """List all named transformations.
245
    
246
    Args:
247
        max_results (int, optional): Maximum results to return
248
        next_cursor (str, optional): Cursor for pagination
249
    
250
    Returns:
251
        dict: Response containing:
252
            - transformations (list): List of transformation objects
253
            - next_cursor (str): Cursor for next page
254
    """
255

256
def transformation(transformation, **options):
257
    """Get details of a specific transformation.
258
    
259
    Args:
260
        transformation (str|dict): Transformation name or definition
261
        **options: Additional options
262
    
263
    Returns:
264
        dict: Transformation details including usage statistics
265
    """
266

267
def create_transformation(name, definition, **options):
268
    """Create a named transformation.
269
    
270
    Args:
271
        name (str): Name for the transformation
272
        definition (dict): Transformation parameters
273
        **options: Additional options
274
    
275
    Returns:
276
        dict: Created transformation details
277
    """
278

279
def update_transformation(transformation, **options):
280
    """Update an existing transformation.
281
    
282
    Args:
283
        transformation (str|dict): Transformation to update
284
        allowed_for_strict (bool, optional): Allow in strict mode
285
        **options: Update options
286
    
287
    Returns:
288
        dict: Updated transformation details
289
    """
290

291
def delete_transformation(transformation, **options):
292
    """Delete a named transformation.
293
    
294
    Args:
295
        transformation (str|dict): Transformation to delete
296
        **options: Additional options
297
    
298
    Returns:
299
        dict: Deletion result
300
    """
301
```
302

303
### Account Information
304

305
Get account usage and configuration information.
306

307
```python { .api }
308
def ping(**options):
309
    """Test API connectivity and authentication.
310
    
311
    Args:
312
        **options: Additional options
313
    
314
    Returns:
315
        dict: Response indicating API status
316
    """
317

318
def usage(**options):
319
    """Get account usage statistics.
320
    
321
    Args:
322
        date (str, optional): Specific date for usage (YYYY-MM-DD format)
323
        **options: Additional options
324
    
325
    Returns:
326
        dict: Usage statistics including:
327
            - plan (str): Account plan type
328
            - last_updated (str): Last update timestamp
329
            - objects (dict): Object counts by type
330
            - bandwidth (dict): Bandwidth usage
331
            - storage (dict): Storage usage
332
            - requests (dict): API request counts
333
            - resources (dict): Resource counts
334
            - derived_resources (dict): Derived resource counts
335
    """
336
```
337

338
### Visual Search
339

340
Find resources based on visual similarity using images or text descriptions.
341

342
```python { .api }
343
def visual_search(image_url=None, image_asset_id=None, text=None, image_file=None, **options):
344
    """Find images based on their visual content.
345
    
346
    Args:
347
        image_url (str, optional): URL of an image to use as search query
348
        image_asset_id (str, optional): Asset ID of an image in your account to use as search query
349
        text (str, optional): Textual description to search for (e.g., "cat", "red car")
350
        image_file (str|bytes|Path|callable, optional): Local image file to use as search query
351
        **options: Additional search options
352
    
353
    Returns:
354
        dict: Response containing:
355
            - resources (list): List of visually similar resources
356
            - next_cursor (str): Cursor for pagination (if more results exist)
357
    """
358
```
359

360
### Extended Resource Management
361

362
Advanced resource retrieval methods including asset ID and folder-based access.
363

364
```python { .api }
365
def resource_by_asset_id(asset_id, **options):
366
    """Get details of a specific resource by asset ID.
367
    
368
    Args:
369
        asset_id (str): Asset ID of the resource
370
        exif (bool, optional): Include EXIF data
371
        faces (bool, optional): Include face detection data
372
        colors (bool, optional): Include color information
373
        image_metadata (bool, optional): Include image metadata
374
        media_metadata (bool, optional): Include extended media metadata
375
        cinemagraph_analysis (bool, optional): Include cinemagraph analysis
376
        pages (bool, optional): Include page count for multi-page files
377
        phash (bool, optional): Include perceptual hash data
378
        coordinates (bool, optional): Include custom and face coordinates
379
        max_results (int, optional): Maximum derived resources to return
380
        quality_analysis (bool, optional): Include quality analysis
381
        derived_next_cursor (str, optional): Cursor for derived resources pagination
382
        accessibility_analysis (bool, optional): Include accessibility analysis
383
        versions (bool, optional): Include version information
384
        related (bool, optional): Include related assets
385
        related_next_cursor (str, optional): Cursor for related assets pagination
386
        **kwargs: Additional options
387
    
388
    Returns:
389
        dict: Detailed resource information
390
    """
391

392
def resources_by_asset_folder(asset_folder, **options):
393
    """List resources in a specific asset folder.
394
    
395
    Args:
396
        asset_folder (str): The asset folder path
397
        direction (str, optional): Sort direction ('asc', 'desc')
398
        max_results (int, optional): Maximum results to return
399
        next_cursor (str, optional): Cursor for pagination
400
        **options: Additional filtering options
401
    
402
    Returns:
403
        dict: Response containing resources in the specified folder
404
    """
405

406
def resources_by_asset_ids(asset_ids, **options):
407
    """Get resources by their asset IDs.
408
    
409
    Args:
410
        asset_ids (list): List of asset IDs to retrieve
411
        direction (str, optional): Sort direction ('asc', 'desc')
412
        max_results (int, optional): Maximum results to return
413
        next_cursor (str, optional): Cursor for pagination
414
        **options: Additional options
415
    
416
    Returns:
417
        dict: Response containing the specified resources
418
    """
419
```
420

421
### Asset Relationship Management
422

423
Manage relationships between assets for content organization and discovery.
424

425
```python { .api }
426
def add_related_assets(public_id, assets_to_relate, resource_type="image", type="upload", **options):
427
    """Add related assets to a resource by public IDs.
428
    
429
    Args:
430
        public_id (str): Public ID of the main asset
431
        assets_to_relate (list): List of up to 10 fully qualified public IDs (resource_type/type/public_id)
432
        resource_type (str, optional): Resource type (default: "image")
433
        type (str, optional): Upload type (default: "upload")
434
        **options: Additional options
435
    
436
    Returns:
437
        dict: Result of the relationship addition
438
    """
439

440
def add_related_assets_by_asset_ids(asset_id, assets_to_relate, **options):
441
    """Add related assets to a resource by asset IDs.
442
    
443
    Args:
444
        asset_id (str): Asset ID of the main asset
445
        assets_to_relate (list): List of up to 10 asset IDs to relate
446
        **options: Additional options
447
    
448
    Returns:
449
        dict: Result of the relationship addition
450
    """
451

452
def delete_related_assets(public_id, assets_to_unrelate, resource_type="image", type="upload", **options):
453
    """Remove related assets from a resource by public IDs.
454
    
455
    Args:
456
        public_id (str): Public ID of the main asset
457
        assets_to_unrelate (list): List of up to 10 fully qualified public IDs to unrelate
458
        resource_type (str, optional): Resource type (default: "image")
459
        type (str, optional): Upload type (default: "upload")
460
        **options: Additional options
461
    
462
    Returns:
463
        dict: Result of the relationship removal
464
    """
465

466
def delete_related_assets_by_asset_ids(asset_id, assets_to_unrelate, **options):
467
    """Remove related assets from a resource by asset IDs.
468
    
469
    Args:
470
        asset_id (str): Asset ID of the main asset
471
        assets_to_unrelate (list): List of up to 10 asset IDs to unrelate
472
        **options: Additional options
473
    
474
    Returns:
475
        dict: Result of the relationship removal
476
    """
477
```
478

479
### Advanced Deletion Operations
480

481
Specialized deletion methods for different use cases and asset types.
482

483
```python { .api }
484
def delete_resources_by_asset_ids(asset_ids, **options):
485
    """Delete resources by their asset IDs.
486
    
487
    Args:
488
        asset_ids (list): List of asset IDs to delete
489
        transformations (list, optional): Specific transformations to delete
490
        keep_original (bool, optional): Keep original files, delete only derivatives
491
        next_cursor (str, optional): Cursor for batch processing
492
        invalidate (bool, optional): Invalidate CDN cache
493
        **options: Additional deletion options
494
    
495
    Returns:
496
        dict: Deletion results with details of deleted and failed resources
497
    """
498

499
def delete_derived_by_transformation(public_ids, transformations, resource_type='image', type='upload', invalidate=None, **options):
500
    """Delete derived resources by transformation for specific public IDs.
501
    
502
    Args:
503
        public_ids (list): List of public IDs or single public ID
504
        transformations (list): List of transformations (dict or str) to delete
505
        resource_type (str, optional): Resource type (default: "image")
506
        type (str, optional): Upload type (default: "upload")
507
        invalidate (bool, optional): Invalidate CDN cache
508
        **options: Additional options
509
    
510
    Returns:
511
        dict: Deletion results including public IDs for which derived resources were deleted
512
    """
513

514
def delete_backed_up_assets(asset_id, version_ids, **options):
515
    """Delete backed up versions of a resource.
516
    
517
    Args:
518
        asset_id (str): Asset ID of the resource
519
        version_ids (list): List of version IDs to delete
520
        **options: Additional options
521
    
522
    Returns:
523
        dict: Result of the backup deletion
524
    """
525
```
526

527
### Publishing Operations
528

529
Manage resource publication from private to public delivery.
530

531
```python { .api }
532
def publish_by_ids(public_ids, **options):
533
    """Publish specific resources by their public IDs.
534
    
535
    Args:
536
        public_ids (list): List of public IDs to publish
537
        resource_type (str, optional): Resource type (default: "image")
538
        type (str, optional): Asset type (default: "upload")
539
        overwrite (bool, optional): Overwrite existing published assets
540
        invalidate (bool, optional): Invalidate CDN cache
541
        **options: Additional options
542
    
543
    Returns:
544
        dict: Result of the publish operation
545
    """
546

547
def publish_by_prefix(prefix, **options):
548
    """Publish resources by public ID prefix.
549
    
550
    Args:
551
        prefix (str): Public ID prefix to match for publishing
552
        resource_type (str, optional): Resource type (default: "image")
553
        type (str, optional): Asset type (default: "upload")
554
        overwrite (bool, optional): Overwrite existing published assets
555
        invalidate (bool, optional): Invalidate CDN cache
556
        **options: Additional options
557
    
558
    Returns:
559
        dict: Result of the publish operation
560
    """
561

562
def publish_by_tag(tag, **options):
563
    """Publish resources by tag.
564
    
565
    Args:
566
        tag (str): Tag to match for publishing
567
        resource_type (str, optional): Resource type (default: "image")
568
        type (str, optional): Asset type (default: "upload")
569
        overwrite (bool, optional): Overwrite existing published assets
570
        invalidate (bool, optional): Invalidate CDN cache
571
        **options: Additional options
572
    
573
    Returns:
574
        dict: Result of the publish operation
575
    """
576
```
577

578
### Upload Preset Management
579

580
Manage upload presets for standardized upload configurations.
581

582
```python { .api }
583
def upload_presets(**options):
584
    """List all upload presets in your account.
585
    
586
    Args:
587
        next_cursor (str, optional): Cursor for pagination
588
        max_results (int, optional): Maximum results to return
589
        **options: Additional options
590
    
591
    Returns:
592
        dict: Response containing:
593
            - presets (list): List of upload preset objects
594
            - next_cursor (str): Cursor for next page
595
    """
596

597
def upload_preset(name, **options):
598
    """Get details of a specific upload preset.
599
    
600
    Args:
601
        name (str): Name of the upload preset
602
        max_results (int, optional): Maximum details to return
603
        **options: Additional options
604
    
605
    Returns:
606
        dict: Upload preset details and configuration
607
    """
608

609
def create_upload_preset(**options):
610
    """Create a new upload preset.
611
    
612
    Args:
613
        name (str, optional): Name for the new upload preset
614
        unsigned (bool, optional): Whether preset is unsigned (public)
615
        disallow_public_id (bool, optional): Prevent public ID override during upload
616
        live (bool, optional): Whether preset is for live (video) usage
617
        **options: Upload configuration parameters (folder, tags, transformations, etc.)
618
    
619
    Returns:
620
        dict: Created upload preset details
621
    """
622

623
def update_upload_preset(name, **options):
624
    """Update an existing upload preset.
625
    
626
    Args:
627
        name (str): Name of the upload preset to update
628
        unsigned (bool, optional): Whether preset is unsigned (public)
629
        disallow_public_id (bool, optional): Prevent public ID override during upload
630
        live (bool, optional): Whether preset is for live (video) usage
631
        **options: Upload configuration parameters to update
632
    
633
    Returns:
634
        dict: Updated upload preset details
635
    """
636

637
def delete_upload_preset(name, **options):
638
    """Delete an upload preset.
639
    
640
    Args:
641
        name (str): Name of the upload preset to delete
642
        **options: Additional options
643
    
644
    Returns:
645
        dict: Result of the deletion
646
    """
647
```
648

649
### Folder Management
650

651
Organize resources using folder structures and hierarchies.
652

653
```python { .api }
654
def root_folders(**options):
655
    """List all top-level folders in your account.
656
    
657
    Args:
658
        next_cursor (str, optional): Cursor for pagination
659
        max_results (int, optional): Maximum results to return
660
        **options: Additional options
661
    
662
    Returns:
663
        dict: Response containing:
664
            - folders (list): List of top-level folder objects
665
            - next_cursor (str): Cursor for next page
666
    """
667

668
def subfolders(of_folder_path, **options):
669
    """List subfolders of a given folder path.
670
    
671
    Args:
672
        of_folder_path (str): Path of the parent folder
673
        next_cursor (str, optional): Cursor for pagination
674
        max_results (int, optional): Maximum results to return
675
        **options: Additional options
676
    
677
    Returns:
678
        dict: Response containing subfolders of the specified path
679
    """
680

681
def create_folder(path, **options):
682
    """Create a new folder at the specified path.
683
    
684
    Args:
685
        path (str): Path for the new folder
686
        **options: Additional options
687
    
688
    Returns:
689
        dict: Result of the folder creation
690
    """
691

692
def rename_folder(from_path, to_path, **options):
693
    """Rename/move a folder from one path to another.
694
    
695
    Args:
696
        from_path (str): Current full path of the folder
697
        to_path (str): New full path for the folder
698
        **options: Additional options
699
    
700
    Returns:
701
        dict: Result of the rename operation
702
    """
703

704
def delete_folder(path, **options):
705
    """Delete a folder (must be empty).
706
    
707
    Args:
708
        path (str): Path of the folder to delete
709
        skip_backup (bool, optional): Skip backing up before deletion
710
        **options: Additional options
711
    
712
    Returns:
713
        dict: Result of the folder deletion
714
    """
715
```
716

717
### Backup and Restore Operations
718

719
Manage resource backups and restore deleted assets.
720

721
```python { .api }
722
def restore(public_ids, **options):
723
    """Restore deleted resources by public IDs from backups.
724
    
725
    Args:
726
        public_ids (list): List of public IDs to restore
727
        versions (list, optional): Specific version IDs to restore
728
        resource_type (str, optional): Resource type (default: "image")
729
        type (str, optional): Upload type (default: "upload")
730
        **options: Additional options
731
    
732
    Returns:
733
        dict: Result of the restore operation
734
    """
735

736
def restore_by_asset_ids(asset_ids, **options):
737
    """Restore deleted resources by asset IDs from backups.
738
    
739
    Args:
740
        asset_ids (list): List of asset IDs to restore
741
        versions (list, optional): Specific version IDs to restore
742
        **options: Additional options
743
    
744
    Returns:
745
        dict: Result of the restore operation
746
    """
747
```
748

749
### Upload Mapping Management
750

751
Configure custom upload URL mappings for folder organization.
752

753
```python { .api }
754
def upload_mappings(**options):
755
    """List all upload mappings in your account.
756
    
757
    Args:
758
        next_cursor (str, optional): Cursor for pagination
759
        max_results (int, optional): Maximum results to return
760
        **options: Additional options
761
    
762
    Returns:
763
        dict: Response containing:
764
            - mappings (list): List of upload mapping objects
765
            - next_cursor (str): Cursor for next page
766
    """
767

768
def upload_mapping(name, **options):
769
    """Get details of a specific upload mapping by folder name.
770
    
771
    Args:
772
        name (str): Folder name of the upload mapping
773
        **options: Additional options
774
    
775
    Returns:
776
        dict: Upload mapping details
777
    """
778

779
def create_upload_mapping(name, **options):
780
    """Create a new upload mapping.
781
    
782
    Args:
783
        name (str): Folder name for the mapping
784
        template (str, optional): URL template for the folder
785
        **options: Additional options
786
    
787
    Returns:
788
        dict: Created upload mapping details
789
    """
790

791
def update_upload_mapping(name, **options):
792
    """Update an existing upload mapping.
793
    
794
    Args:
795
        name (str): Folder name of the mapping to update
796
        template (str, optional): URL template for the folder
797
        **options: Additional update options
798
    
799
    Returns:
800
        dict: Updated upload mapping details
801
    """
802

803
def delete_upload_mapping(name, **options):
804
    """Delete an upload mapping by folder name.
805
    
806
    Args:
807
        name (str): Folder name of the mapping to delete
808
        **options: Additional options
809
    
810
    Returns:
811
        dict: Result of the deletion
812
    """
813
```
814

815
### Streaming Profile Management
816

817
Manage adaptive streaming profiles for video delivery optimization.
818

819
```python { .api }
820
def list_streaming_profiles(**options):
821
    """List all custom and built-in streaming profiles.
822
    
823
    Args:
824
        **options: Additional options
825
    
826
    Returns:
827
        dict: Response containing:
828
            - data (list): List of streaming profile objects
829
    """
830

831
def get_streaming_profile(name, **options):
832
    """Get details of a specific streaming profile.
833
    
834
    Args:
835
        name (str): Name of the streaming profile
836
        **options: Additional options
837
    
838
    Returns:
839
        dict: Streaming profile details and configuration
840
    """
841

842
def create_streaming_profile(name, **options):
843
    """Create a new custom streaming profile.
844
    
845
    Args:
846
        name (str): Name for the new streaming profile
847
        display_name (str, optional): Display name for the profile
848
        representations (list, optional): List of transformation objects or strings
849
        **options: Additional options
850
    
851
    Returns:
852
        dict: Created streaming profile details
853
    """
854

855
def update_streaming_profile(name, **options):
856
    """Update an existing streaming profile.
857
    
858
    Args:
859
        name (str): Name of the streaming profile to update
860
        display_name (str, optional): Display name for the profile
861
        representations (list, optional): List of transformation objects or strings
862
        **options: Additional update options
863
    
864
    Returns:
865
        dict: Updated streaming profile details
866
    """
867

868
def delete_streaming_profile(name, **options):
869
    """Delete a streaming profile (or revert built-in profile to default).
870
    
871
    Args:
872
        name (str): Name of the streaming profile to delete
873
        **options: Additional options
874
    
875
    Returns:
876
        dict: Result of the deletion
877
    """
878
```
879

880
### Metadata Field Management
881

882
Define and manage structured metadata fields for resource organization.
883

884
```python { .api }
885
def list_metadata_fields(**options):
886
    """List all metadata field definitions.
887
    
888
    Args:
889
        **options: Additional options
890
    
891
    Returns:
892
        dict: Response containing:
893
            - metadata_fields (list): List of metadata field definitions
894
    """
895

896
def metadata_field_by_field_id(field_external_id, **options):
897
    """Get a specific metadata field by external ID.
898
    
899
    Args:
900
        field_external_id (str): External ID of the metadata field
901
        **options: Additional options
902
    
903
    Returns:
904
        dict: Metadata field details and configuration
905
    """
906

907
def add_metadata_field(field, **options):
908
    """Create a new metadata field definition.
909
    
910
    Args:
911
        field (dict): Field definition containing:
912
            - type (str): Field type ('string', 'integer', 'date', 'enum', etc.)
913
            - external_id (str): External identifier for the field
914
            - label (str): Display label for the field
915
            - mandatory (bool, optional): Whether field is required
916
            - restrictions (dict, optional): Field validation rules
917
            - default_value (any, optional): Default value for the field
918
            - default_disabled (bool, optional): Whether field is disabled by default
919
            - validation (dict, optional): Additional validation rules
920
            - datasource (dict, optional): Data source configuration for enum fields
921
            - allow_dynamic_list_values (bool, optional): Allow dynamic values for list fields
922
        **options: Additional options
923
    
924
    Returns:
925
        dict: Created metadata field details
926
    """
927

928
def update_metadata_field(field_external_id, field, **options):
929
    """Update an existing metadata field.
930
    
931
    Args:
932
        field_external_id (str): External ID of the field to update
933
        field (dict): Updated field definition (same structure as add_metadata_field)
934
        **options: Additional options
935
    
936
    Returns:
937
        dict: Updated metadata field details
938
    """
939

940
def delete_metadata_field(field_external_id, **options):
941
    """Delete a metadata field definition.
942
    
943
    Args:
944
        field_external_id (str): External ID of the field to delete
945
        **options: Additional options
946
    
947
    Returns:
948
        dict: Result of the deletion with "message" key
949
    """
950

951
def delete_datasource_entries(field_external_id, entries_external_id, **options):
952
    """Delete entries from a metadata field datasource.
953
    
954
    Args:
955
        field_external_id (str): External ID of the metadata field
956
        entries_external_id (list): List of entry external IDs to delete
957
        **options: Additional options
958
    
959
    Returns:
960
        dict: Result of the datasource entry deletion
961
    """
962

963
def update_metadata_field_datasource(field_external_id, entries_external_id, **options):
964
    """Update or add entries to a metadata field datasource.
965
    
966
    Args:
967
        field_external_id (str): External ID of the metadata field
968
        entries_external_id (list): List of entry objects with 'external_id' and 'value' keys
969
        **options: Additional options
970
    
971
    Returns:
972
        dict: Updated metadata field details
973
    """
974

975
def restore_metadata_field_datasource(field_external_id, entries_external_ids, **options):
976
    """Restore (unblock) entries in a metadata field datasource.
977
    
978
    Args:
979
        field_external_id (str): External ID of the metadata field
980
        entries_external_ids (list): List of entry external IDs to restore
981
        **options: Additional options
982
    
983
    Returns:
984
        dict: Result of the restore operation
985
    """
986

987
def reorder_metadata_field_datasource(field_external_id, order_by, direction=None, **options):
988
    """Reorder entries in a metadata field datasource.
989
    
990
    Args:
991
        field_external_id (str): External ID of the metadata field
992
        order_by (str): Ordering criteria (currently supports 'value')
993
        direction (str, optional): Sort direction ('asc' or 'desc')
994
        **options: Additional options
995
    
996
    Returns:
997
        dict: Result of the reordering operation
998
    """
999

1000
def reorder_metadata_fields(order_by, direction=None, **options):
1001
    """Reorder metadata fields.
1002
    
1003
    Args:
1004
        order_by (str): Ordering criteria ('label', 'external_id', 'created_at')
1005
        direction (str, optional): Sort direction ('asc' or 'desc')
1006
        **options: Additional options
1007
    
1008
    Returns:
1009
        dict: Result of the reordering operation
1010
    """
1011
```
1012

1013
### Metadata Rules Management
1014

1015
Create and manage automated metadata rules for dynamic asset tagging.
1016

1017
```python { .api }
1018
def list_metadata_rules(**options):
1019
    """List all metadata rule definitions.
1020
    
1021
    Args:
1022
        **options: Additional options
1023
    
1024
    Returns:
1025
        dict: Response containing:
1026
            - metadata_rules (list): List of metadata rule definitions
1027
    """
1028

1029
def add_metadata_rule(rule, **options):
1030
    """Create a new metadata rule definition.
1031
    
1032
    Args:
1033
        rule (dict): Rule definition containing:
1034
            - external_id (str): External identifier for the rule
1035
            - metadata_field_id (str): ID of the target metadata field
1036
            - condition (dict): Rule condition configuration
1037
            - result (dict): Rule result/action configuration
1038
            - name (str): Display name for the rule
1039
            - state (str, optional): Rule state ('active', 'inactive')
1040
        **options: Additional options
1041
    
1042
    Returns:
1043
        dict: Created metadata rule details
1044
    """
1045

1046
def update_metadata_rule(rule_external_id, rule, **options):
1047
    """Update an existing metadata rule.
1048
    
1049
    Args:
1050
        rule_external_id (str): External ID of the rule to update
1051
        rule (dict): Updated rule definition (same structure as add_metadata_rule)
1052
        **options: Additional options
1053
    
1054
    Returns:
1055
        dict: Updated metadata rule details
1056
    """
1057

1058
def delete_metadata_rule(rule_external_id, **options):
1059
    """Delete a metadata rule definition.
1060
    
1061
    Args:
1062
        rule_external_id (str): External ID of the rule to delete
1063
        **options: Additional options
1064
    
1065
    Returns:
1066
        dict: Result of the deletion with "success" key
1067
    """
1068
```
1069

1070
### Advanced Configuration
1071

1072
Access account configuration and resource type information.
1073

1074
```python { .api }
1075
def config(**options):
1076
    """Get account configuration details.
1077
    
1078
    Args:
1079
        settings (bool, optional): Include extended settings in response
1080
        **options: Additional options
1081
    
1082
    Returns:
1083
        dict: Detailed account configuration information including:
1084
            - cloud_name (str): Account cloud name
1085
            - api_key (str): API key (masked)
1086
            - settings (dict): Extended configuration settings (if requested)
1087
    """
1088

1089
def resource_types(**options):
1090
    """Get available resource types in your account.
1091
    
1092
    Args:
1093
        **options: Additional options
1094
    
1095
    Returns:
1096
        dict: Response containing:
1097
            - resource_types (list): List of available resource types
1098
    """
1099
```
1100

1101
### Analysis Operations
1102

1103
Perform AI-powered analysis on resources for enhanced metadata and insights.
1104

1105
```python { .api }
1106
def analyze(input_type, analysis_type, uri=None, **options):
1107
    """Analyze an asset with the specified analysis type.
1108
    
1109
    Args:
1110
        input_type (str): Type of input for the asset ('uri')
1111
        analysis_type (str): Type of analysis ('google_tagging', 'captioning', 'fashion', 'coco', 'lvis', 'unidet', 'shop')
1112
        uri (str, optional): URI of the asset to analyze
1113
        parameters (dict, optional): Additional analysis parameters
1114
        **options: Additional options
1115
    
1116
    Returns:
1117
        dict: Analysis results containing extracted information based on analysis type
1118
    """
1119
```
1120

1121
## Usage Examples
1122

1123
### Resource Discovery
1124

1125
```python
1126
from cloudinary import api
1127

1128
# List recent resources
1129
result = api.resources(max_results=50)
1130
for resource in result['resources']:
1131
    print(f"{resource['public_id']}: {resource['format']} ({resource['bytes']} bytes)")
1132

1133
# List resources with full metadata
1134
result = api.resources(
1135
    tags=True,
1136
    context=True,
1137
    metadata=True,
1138
    max_results=20
1139
)
1140

1141
# List resources by tag
1142
result = api.resources_by_tag("featured", max_results=100)
1143

1144
# List resources by prefix
1145
result = api.resources(prefix="products/", max_results=100)
1146

1147
# Paginate through all resources
1148
next_cursor = None
1149
all_resources = []
1150
while True:
1151
    result = api.resources(
1152
        max_results=500,
1153
        next_cursor=next_cursor
1154
    )
1155
    all_resources.extend(result['resources'])
1156
    next_cursor = result.get('next_cursor')
1157
    if not next_cursor:
1158
        break
1159
```
1160

1161
### Resource Details and Updates
1162

1163
```python
1164
# Get detailed resource information
1165
resource = api.resource(
1166
    "sample_image",
1167
    colors=True,
1168
    faces=True,
1169
    quality_analysis=True,
1170
    coordinates=True
1171
)
1172
print(f"Dimensions: {resource['width']}x{resource['height']}")
1173
print(f"Colors: {resource.get('colors', [])}")
1174
print(f"Faces: {resource.get('faces', [])}")
1175

1176
# Update resource metadata
1177
result = api.update(
1178
    "sample_image",
1179
    tags=["updated", "processed"],
1180
    context={"status": "processed", "version": "2.0"},
1181
    metadata={"category": "electronics", "featured": "true"}
1182
)
1183

1184
# Apply auto-tagging
1185
result = api.update(
1186
    "sample_image",
1187
    auto_tagging=0.8,
1188
    categorization="google_tagging"
1189
)
1190
```
1191

1192
### Bulk Operations
1193

1194
```python
1195
# Delete multiple resources
1196
result = api.delete_resources([
1197
    "old_image_1",
1198
    "old_image_2", 
1199
    "old_image_3"
1200
])
1201

1202
# Delete by prefix
1203
result = api.delete_resources_by_prefix("temp/")
1204

1205
# Delete by tag
1206
result = api.delete_resources_by_tag("to_delete")
1207

1208
# Get all tags
1209
result = api.tags(max_results=1000)
1210
all_tags = result['tags']
1211
```
1212

1213
### Transformation Management
1214

1215
```python
1216
# List all transformations
1217
result = api.transformations()
1218
for trans in result['transformations']:
1219
    print(f"Transformation: {trans['name']}")
1220

1221
# Create named transformation
1222
result = api.create_transformation(
1223
    "product_thumb",
1224
    {"width": 300, "height": 300, "crop": "fill", "quality": "auto"}
1225
)
1226

1227
# Get transformation details
1228
trans_info = api.transformation("product_thumb")
1229
print(f"Used: {trans_info['used']} times")
1230

1231
# Update transformation
1232
api.update_transformation(
1233
    "product_thumb",
1234
    allowed_for_strict=True
1235
)
1236

1237
# Delete transformation
1238
api.delete_transformation("old_transformation")
1239
```
1240

1241
### Account Management
1242

1243
```python
1244
# Test API connection
1245
result = api.ping()
1246
print(f"Status: {result['status']}")
1247

1248
# Get usage statistics
1249
usage = api.usage()
1250
print(f"Plan: {usage['plan']}")
1251
print(f"Credits used: {usage['credits']['used']}/{usage['credits']['limit']}")
1252
print(f"Bandwidth: {usage['bandwidth']['bytes']} bytes")
1253
print(f"Storage: {usage['storage']['bytes']} bytes")
1254
print(f"Resources: {usage['resources']} total")
1255
```
1256

1257
### Visual Search and Discovery
1258

1259
```python
1260
# Search for similar images using an uploaded image
1261
similar_results = api.visual_search(
1262
    image_asset_id="sample_image_id"
1263
)
1264
for resource in similar_results['resources']:
1265
    print(f"Similar image: {resource['public_id']} (score: {resource.get('score', 'N/A')})")
1266

1267
# Search using an external image URL
1268
url_results = api.visual_search(
1269
    image_url="https://example.com/search-image.jpg"
1270
)
1271

1272
# Search using text description
1273
text_results = api.visual_search(
1274
    text="red sports car"
1275
)
1276

1277
# Search with local image file
1278
with open("search_image.jpg", "rb") as f:
1279
    file_results = api.visual_search(image_file=f)
1280
```
1281

1282
### Extended Resource Management
1283

1284
```python
1285
# Get resource by asset ID with full details
1286
asset_details = api.resource_by_asset_id(
1287
    "abc123def456",
1288
    exif=True,
1289
    colors=True,
1290
    faces=True,
1291
    quality_analysis=True,
1292
    accessibility_analysis=True,
1293
    related=True
1294
)
1295
print(f"Asset: {asset_details['public_id']}")
1296
print(f"Quality score: {asset_details.get('quality_analysis', {}).get('focus')}")
1297

1298
# List resources in a specific asset folder
1299
folder_resources = api.resources_by_asset_folder(
1300
    "product_images/electronics",
1301
    max_results=100
1302
)
1303
print(f"Found {len(folder_resources['resources'])} resources in folder")
1304

1305
# Get multiple resources by their asset IDs
1306
asset_ids = ["abc123", "def456", "ghi789"]
1307
multi_assets = api.resources_by_asset_ids(
1308
    asset_ids,
1309
    tags=True,
1310
    context=True
1311
)
1312
```
1313

1314
### Asset Relationships
1315

1316
```python
1317
# Add related assets to create content associations
1318
api.add_related_assets(
1319
    "main_product_image",
1320
    [
1321
        "image/upload/product_detail_1",
1322
        "image/upload/product_detail_2",
1323
        "video/upload/product_demo"
1324
    ]
1325
)
1326

1327
# Add related assets using asset IDs
1328
api.add_related_assets_by_asset_ids(
1329
    "main_asset_id",
1330
    ["related_asset_1", "related_asset_2"]
1331
)
1332

1333
# Remove asset relationships
1334
api.delete_related_assets(
1335
    "main_product_image",
1336
    ["image/upload/old_related_image"]
1337
)
1338
```
1339

1340
### Advanced Deletion and Publishing
1341

1342
```python
1343
# Delete resources by asset IDs
1344
api.delete_resources_by_asset_ids(
1345
    ["asset1", "asset2", "asset3"],
1346
    invalidate=True
1347
)
1348

1349
# Delete specific derived transformations
1350
api.delete_derived_by_transformation(
1351
    ["product_1", "product_2"],
1352
    [
1353
        {"width": 300, "height": 300, "crop": "fill"},
1354
        {"width": 150, "height": 150, "crop": "thumb"}
1355
    ],
1356
    invalidate=True
1357
)
1358

1359
# Publish private resources to make them publicly accessible
1360
api.publish_by_prefix(
1361
    "products/featured/",
1362
    overwrite=True,
1363
    invalidate=True
1364
)
1365

1366
# Publish resources with specific tag
1367
api.publish_by_tag(
1368
    "ready_for_production",
1369
    resource_type="image"
1370
)
1371
```
1372

1373
### Upload Presets and Configuration
1374

1375
```python
1376
# List all upload presets
1377
presets = api.upload_presets()
1378
for preset in presets['presets']:
1379
    print(f"Preset: {preset['name']} (unsigned: {preset.get('unsigned', False)})")
1380

1381
# Create a new upload preset for product images
1382
api.create_upload_preset(
1383
    name="product_images",
1384
    folder="products",
1385
    tags=["product", "auto-uploaded"],
1386
    transformation=[
1387
        {"width": 800, "height": 600, "crop": "limit"},
1388
        {"quality": "auto", "format": "auto"}
1389
    ],
1390
    auto_tagging=0.7,
1391
    categorization="google_tagging"
1392
)
1393

1394
# Update existing upload preset
1395
api.update_upload_preset(
1396
    "product_images",
1397
    tags=["product", "auto-uploaded", "v2"],
1398
    context={"version": "2.0", "department": "marketing"}
1399
)
1400
```
1401

1402
### Folder Organization
1403

1404
```python
1405
# List top-level folders
1406
folders = api.root_folders()
1407
for folder in folders['folders']:
1408
    print(f"Folder: {folder['name']} (path: {folder['path']})")
1409

1410
# Create folder hierarchy
1411
api.create_folder("products/electronics/smartphones")
1412

1413
# List subfolders
1414
electronics_subfolders = api.subfolders("products/electronics")
1415

1416
# Rename/move folder
1417
api.rename_folder("products/old_category", "products/electronics/legacy")
1418

1419
# Delete empty folder
1420
api.delete_folder("products/temp_folder")
1421
```
1422

1423
### Backup and Restore
1424

1425
```python
1426
# Restore deleted resources from backup
1427
restored = api.restore([
1428
    "accidentally_deleted_1",
1429
    "accidentally_deleted_2"
1430
])
1431
print(f"Restored {len(restored['restored'])} resources")
1432

1433
# Restore specific versions
1434
api.restore(
1435
    ["resource_with_versions"],
1436
    versions=["v1234567890", "v0987654321"]
1437
)
1438

1439
# Restore by asset IDs
1440
api.restore_by_asset_ids([
1441
    "asset_id_1",
1442
    "asset_id_2"
1443
])
1444
```
1445

1446
### Streaming Profiles (Video)
1447

1448
```python
1449
# List all streaming profiles
1450
profiles = api.list_streaming_profiles()
1451
for profile in profiles['data']:
1452
    print(f"Profile: {profile['name']} - {profile.get('display_name', '')}")
1453

1454
# Create custom streaming profile for mobile optimization
1455
api.create_streaming_profile(
1456
    "mobile_optimized",
1457
    display_name="Mobile Optimized Streaming",
1458
    representations=[
1459
        {"bit_rate": "500k", "height": 360, "video_codec": "h264"},
1460
        {"bit_rate": "1000k", "height": 720, "video_codec": "h264"},
1461
        {"bit_rate": "2000k", "height": 1080, "video_codec": "h264"}
1462
    ]
1463
)
1464

1465
# Update streaming profile
1466
api.update_streaming_profile(
1467
    "mobile_optimized",
1468
    display_name="Mobile & Tablet Optimized"
1469
)
1470
```
1471

1472
### Metadata Fields and Rules
1473

1474
```python
1475
# List all metadata fields
1476
fields = api.list_metadata_fields()
1477
for field in fields['metadata_fields']:
1478
    print(f"Field: {field['label']} ({field['type']}) - ID: {field['external_id']}")
1479

1480
# Create a new enum metadata field
1481
api.add_metadata_field({
1482
    "type": "enum",
1483
    "external_id": "product_category",
1484
    "label": "Product Category",
1485
    "mandatory": True,
1486
    "datasource": {
1487
        "values": [
1488
            {"external_id": "electronics", "value": "Electronics"},
1489
            {"external_id": "clothing", "value": "Clothing"},
1490
            {"external_id": "books", "value": "Books"}
1491
        ]
1492
    }
1493
})
1494

1495
# Create metadata rule for auto-tagging
1496
api.add_metadata_rule({
1497
    "external_id": "auto_tag_products",
1498
    "name": "Auto-tag Product Images",
1499
    "metadata_field_id": "product_category",
1500
    "condition": {
1501
        "type": "and",
1502
        "conditions": [
1503
            {"field": "folder", "operator": "starts_with", "value": "products/"},
1504
            {"field": "width", "operator": "greater_than", "value": 500}
1505
        ]
1506
    },
1507
    "result": {
1508
        "metadata_field_id": "product_category",
1509
        "value": "electronics"
1510
    }
1511
})
1512

1513
# Update metadata field datasource
1514
api.update_metadata_field_datasource(
1515
    "product_category",
1516
    [
1517
        {"external_id": "home_garden", "value": "Home & Garden"},
1518
        {"external_id": "sports", "value": "Sports & Recreation"}
1519
    ]
1520
)
1521
```
1522

1523
### Analysis and AI Features
1524

1525
```python
1526
# Perform Google tagging analysis
1527
tagging_result = api.analyze(
1528
    "uri",
1529
    "google_tagging",
1530
    uri="image/upload/sample_image",
1531
    parameters={"confidence_threshold": 0.7}
1532
)
1533
print("Detected tags:", tagging_result.get('tags', []))
1534

1535
# Generate image captions
1536
caption_result = api.analyze(
1537
    "uri",
1538
    "captioning",
1539
    uri="image/upload/sample_image"
1540
)
1541
print("Generated caption:", caption_result.get('caption'))
1542

1543
# Fashion analysis for clothing images
1544
fashion_result = api.analyze(
1545
    "uri",
1546
    "fashion",
1547
    uri="image/upload/clothing_item"
1548
)
1549
print("Fashion attributes:", fashion_result.get('attributes', []))
1550
```