Asset Management Tools

Tools for uploading, organizing, and managing all your media assets - images, videos, PDFs, and other files used in your Storyblok content.

Overview

Asset management tools help you organize and maintain your media library:

Assets - Upload, update, and manage individual files
Asset Folders - Organize assets into hierarchical folder structures
Bulk Operations - Move, delete, or restore multiple assets at once
Metadata - Add alt text, titles, copyright info, and custom metadata

Total tools: 14 (Assets: 9, Asset Folders: 5)

Assets (9 tools)

Manage individual files - images, videos, PDFs, and other media used in your content.

Listing & Searching Assets

fetch_assets

Purpose: List or search multiple assets with powerful filtering options.

When to use:

Browse assets in a specific folder
Search for assets by filename or metadata
Find assets by tags or copyright info
Filter private vs public assets
Paginate through large asset collections

Common conversation examples:

Show me all images in the "product-photos" folder

Find all assets tagged with "homepage"

List all PDF files uploaded in the last month

Key parameters:

folder_id - Filter by specific folder
search - Text search across filenames
sort_by - Sort by date, filename, etc.
is_private - Filter by privacy status
by_alt - Filter by alt text
by_title - Filter by title
by_copyright - Filter by copyright info
with_tags - Filter by tags
page, per_page - Pagination

Returns: Array of assets with pagination metadata.

get_asset

Purpose: Retrieve details of a single asset by ID.

When to use:

Get complete metadata for a specific file
Check asset properties before updating
Verify file URLs and dimensions

Common conversation examples:

Show me details for asset ID 789012

What are the dimensions of the hero image?

Key parameters:

id - Asset ID (required)

Returns: Single asset object with all metadata.

Uploading Assets

init_asset_upload

Purpose: Initialize asset upload and get signed S3 upload URL.

When to use:

Start the upload process for new files
Get upload credentials and destination URL
First step in two-phase upload process

Common conversation examples:

I want to upload a new product photo called "widget-v2.jpg"

Initialize upload for a 5MB PDF file

Key parameters:

filename - Name of the file to upload (required)
size - File size in bytes (required)
content_type - MIME type like "image/jpeg" or "application/pdf" (required)

Returns: Upload credentials and signed URL.

Note: After uploading to the signed URL, you must call complete_asset_upload to finalize.

complete_asset_upload

Purpose: Complete the asset upload process after S3 upload.

When to use:

Finalize upload after sending file to S3
Register the uploaded file in Storyblok
Second step in two-phase upload process

Common conversation examples:

Finalize the upload for asset ID 123456

Complete the upload process

Key parameters:

asset_id - ID returned from init_asset_upload (required)

Returns: Finalized asset object.

Updating Assets

update_asset

Purpose: Update asset metadata, folder location, or settings.

When to use:

Add or update alt text and titles
Move asset to different folder
Change privacy settings
Add copyright or source information
Set focal point for image cropping
Schedule publish/expiration dates

Common conversation examples:

Update asset 12345 to add alt text "Product hero image showcasing features"

Move the logo file to the "brand-assets" folder

Mark asset 67890 as private

Key parameters:

asset_id - Asset to update (required)
asset_folder_id - Move to new folder
alt - Alt text for images
title - Asset title
copyright - Copyright information
source - Source attribution
is_private - Privacy setting
locked - Lock status
focus - Focal point for cropping
publish_at - Scheduled publish date
expire_at - Scheduled expiration date
internal_tag_ids - Internal tag IDs
meta_data - Custom metadata object

Returns: Updated asset object.

Deleting Assets

delete_asset

Purpose: Delete a single asset permanently.

When to use:

Remove unused files
Clean up test assets
Delete outdated media

Common conversation examples:

Delete asset ID 456789

Remove the old logo file

Key parameters:

id - Asset ID to delete (required)

Returns: Success confirmation.

Warning: Deletion is permanent. Assets in use by stories may cause broken links!

delete_multiple_assets

Purpose: Delete multiple assets at once.

When to use:

Bulk cleanup operations
Remove entire categories of files
Delete test assets in batch

Common conversation examples:

Delete all assets in the "temp" folder

Remove assets 111, 222, 333, 444

Key parameters:

ids - Array of asset IDs to delete (required)

Returns: Bulk deletion results.

Warning: This is a destructive operation. Always confirm before bulk deleting!

Bulk Operations

bulk_move_assets

Purpose: Move multiple assets to a different folder at once.

When to use:

Reorganize asset library
Move files to archive folders
Consolidate assets from multiple folders

Common conversation examples:

Move all product photos to the "products/2024" folder

Move assets 100, 101, 102 to the archive folder

Key parameters:

ids - Array of asset IDs to move (required)
asset_folder_id - Destination folder ID (required)

Returns: Bulk update results.

bulk_restore_assets

Purpose: Restore multiple previously deleted assets.

When to use:

Undo accidental deletions
Recover recently deleted files
Restore assets from trash

Common conversation examples:

Restore the assets I deleted yesterday

Bring back assets 555, 666, 777

Key parameters:

ids - Array of asset IDs to restore (required)

Returns: Restoration results.

Note: Assets may only be restorable for a limited time after deletion.

Asset Folders (5 tools)

Organize assets into hierarchical folder structures for better management.

Listing Folders

retrieve_asset_folders

Purpose: List all asset folders in your space.

When to use:

See folder structure
Find folder IDs for organizing assets
Search for specific folders

Common conversation examples:

Show me all asset folders

List folders inside the "marketing" folder

Find all folders with "2024" in the name

Key parameters:

search - Filter by folder name
with_parent - Filter by parent folder ID
by_ids - Get specific folders by ID
by_uuids - Get specific folders by UUID

Returns: Array of asset folder objects.

fetch_asset_folder

Purpose: Get details of a specific asset folder.

When to use:

Check folder properties
Get folder ID or UUID
Verify folder structure

Common conversation examples:

Show me details for folder ID 123

What's in the "brand-assets" folder?

Key parameters:

folder_id - Folder ID to retrieve (required)

Returns: Single folder object with metadata.

Creating Folders

create_asset_folder

Purpose: Create a new asset folder.

When to use:

Organize assets into categories
Create project or campaign folders
Set up nested folder structures

Common conversation examples:

Create a new folder called "Product Photos 2024"

Make a "Hero Images" subfolder inside the "Homepage" folder

Key parameters:

name - Folder name (required)
parent_id - Parent folder ID for nested folders

Returns: Newly created folder object.

Updating Folders

update_asset_folder

Purpose: Update folder name or move it to a different parent.

When to use:

Rename folders
Reorganize folder hierarchy
Move folders to different locations

Common conversation examples:

Rename folder "temp" to "archive-2024"

Move the "old-campaigns" folder inside "archive"

Key parameters:

folder_id - Folder to update (required)
name - New folder name
parent_id - New parent folder ID

Returns: Updated folder object.

Deleting Folders

delete_asset_folder

Purpose: Delete an asset folder.

When to use:

Remove empty folders
Clean up unused organization
Consolidate folder structure

Common conversation examples:

Delete the empty "test" folder

Remove folder ID 789

Key parameters:

folder_id - Folder ID to delete (required)

Returns: Deletion confirmation.

Warning: Folder must be empty before deletion. Move or delete assets first!

When to Use What

Finding Assets

Goal	Best Tool	Example
Browse folder	`fetch_assets` with `folder_id`	"Show me all images in products folder"
Search by filename	`fetch_assets` with `search`	"Find all files with 'logo' in name"
Find by alt text	`fetch_assets` with `by_alt`	"Find images with 'team photo' alt text"
Get specific asset	`get_asset`	"Show me asset ID 12345"
Find tagged assets	`fetch_assets` with `with_tags`	"All assets tagged 'featured'"

Organizing Assets

Goal	Best Tool	Example
Create folder	`create_asset_folder`	"Make a 'Product Photos' folder"
Move one asset	`update_asset`	"Move this image to marketing folder"
Move many assets	`bulk_move_assets`	"Move all logos to brand-assets"
Rename folder	`update_asset_folder`	"Rename folder to 'Archive 2024'"

Managing Metadata

Goal	Best Tool	Example
Add alt text	`update_asset`	"Add alt text to hero image"
Set copyright	`update_asset`	"Add copyright info to photos"
Add title	`update_asset`	"Set title for PDF document"
Tag assets	`update_asset` with `internal_tag_ids`	"Tag these as 'approved'"

Uploading Files

Goal	Best Tool	Example
Upload new file	`init_asset_upload` → upload → `complete_asset_upload`	"Upload product-photo.jpg"

Cleaning Up

Goal	Best Tool	Example
Delete one asset	`delete_asset`	"Delete asset 123"
Delete many assets	`delete_multiple_assets`	"Delete all temp files"
Restore deleted	`bulk_restore_assets`	"Restore yesterday's deletions"
Delete folder	`delete_asset_folder`	"Remove empty test folder"

Common Patterns

Folder Organization Strategy

Create a folder structure for a new project:
1. Create "Project X" folder
2. Create subfolders: "Images", "Videos", "Documents"
3. Upload assets to appropriate subfolders

Uses: create_asset_folder (multiple times) → init_asset_upload → complete_asset_upload

Asset Metadata Enrichment

Add metadata to all product photos:
1. Find all assets in "products" folder
2. For each asset, add alt text, copyright, and tags

Uses: fetch_assets → update_asset (multiple times)

Seasonal Content Cleanup

Archive last year's holiday assets:
1. Find all assets tagged "holiday-2023"
2. Create "archive/holiday-2023" folder
3. Move all matching assets to archive

Uses: create_asset_folder → fetch_assets → bulk_move_assets

Find Unused Assets

Identify assets not used in any stories:
1. Get all assets
2. Check which ones aren't referenced in content
3. Move unused assets to "review" folder

Uses: fetch_assets → check story references → bulk_move_assets

Guides

Examples

Tips & Best Practices

Use descriptive folder names - Make it easy to find assets later
Add alt text to images - Essential for accessibility and SEO
Tag strategically - Use tags for cross-folder organization (campaigns, seasons, etc.)
Set focal points - Ensure images crop correctly in responsive layouts
Regular cleanup - Archive or delete unused assets to keep library manageable
Bulk operations - Use bulk tools for efficiency when moving/deleting many assets
Copyright info - Document source and rights for all external assets
Test deletions - Verify assets aren't in use before bulk deleting

Need help managing assets? Check out our asset management guides for detailed workflows!