Assets Management Guide

The CKBox Node.js SDK provides comprehensive asset management capabilities that allow you to retrieve, organize, and manage your uploaded files. This guide covers all aspects of asset management, from basic retrieval to advanced filtering and bulk operations.

Asset Management Overview

The assets component of the CKBox SDK provides the following main operations:

Method	Purpose	Return Type
`getAsset(id)`	Retrieve a single asset by ID	`CKBoxAsset`
`getAssets(options)`	List assets with filtering and pagination	`CKBoxAssetList`
`softDeleteAssets(ids)`	Soft delete multiple assets (move to trash)	`void`
`deleteAssets(ids)`	Permanently delete multiple assets	`void`

All methods support workspace isolation and respect user permissions based on the configured role.

Basic Asset Retrieval

Getting a Single Asset

Retrieve a specific asset using its unique ID to access detailed information about the file.

import CKBox from '@ckbox/sdk-node';

const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
});

async function getAssetById(assetId) {
  try {
    const asset = await ckbox.assets.getAsset(assetId);
    
    console.log('Asset Details:');
    console.log('- Name:', asset.name);
    console.log('- Size (B):', asset.size);
    console.log('- URL:', asset.url);
    console.log('- Category:', asset.categoryId);
    console.log('- Last Modified:', new Date(asset.lastModifiedAt).toLocaleString());
    
    return asset;
  } catch (error) {
    console.error('Failed to retrieve asset:', error.message);
    throw error;
  }
}

// Usage
const asset = await getAssetById('asset_12345');

Listing Assets with Pagination

Basic Asset Listing

Retrieve a paginated list of assets with filtering and sorting options to manage large collections efficiently.

async function listAssets() {
  try {
    const assetList = await ckbox.assets.getAssets({
      categoryId: {{categoryId}},
      limit: 20,
      offset: 0,
      sortBy: 'uploadedAt',
      order: 'desc'
    });
    
    console.log(`Found ${assetList.totalCount} assets`);
    console.log(`Showing ${assetList.items.length} assets (offset: ${assetList.offset})`);
    
    assetList.items.forEach((asset, index) => {
      console.log(`${index + 1}. ${asset.name} (${asset.size})`);
    });
    
    return assetList;
  } catch (error) {
    console.error('Failed to list assets:', error.message);
    throw error;
  }
}

Asset Operations

Soft Delete Assets

Move multiple assets to trash (soft delete) - assets can be restored later:

async function softDeleteAssets(assetIds) {
  try {
    console.log(`Moving ${assetIds.length} assets to trash...`);
    
    // Soft delete the assets (move to trash)
    await ckbox.assets.softDeleteAssets(assetIds);
    
    console.log(`✅ ${assetIds.length} assets moved to trash successfully`);
    return true;
  } catch (error) {
    console.error(`❌ Failed to move assets to trash:`, error.message);
    throw error;
  }
}

// Usage
const assetIds = ['asset_1', 'asset_2', 'asset_3'];
await softDeleteAssets(assetIds);

Permanently Delete Assets

Permanently remove multiple assets from CKBox (cannot be restored):

async function permanentlyDeleteAssets(assetIds) {
  try {
    console.log(`Permanently deleting ${assetIds.length} assets...`);
    
    // Permanently delete the assets
    await ckbox.assets.deleteAssets(assetIds);
    
    console.log(`✅ ${assetIds.length} assets permanently deleted`);
    return true;
  } catch (error) {
    console.error(`❌ Failed to permanently delete assets:`, error.message);
    throw error;
  }
}

// Usage - be careful, this cannot be undone!
const assetIds = ['asset_1', 'asset_2', 'asset_3'];
await permanentlyDeleteAssets(assetIds);