# 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.

<a id="asset-management-overview">

## Asset Management Overview

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

| Method                                            | Purpose                                     | Return Type      |
| ------------------------------------------------- | ------------------------------------------- | ---------------- |
| [`getAsset(id)`](#getting-a-single-asset)         | Retrieve a single asset by ID               | `CKBoxAsset`     |
| [`getAssets(options)`](#basic-asset-listing)      | List assets with filtering and pagination   | `CKBoxAssetList` |
| [`softDeleteAssets(ids)`](#soft-delete-assets)    | Soft delete multiple assets (move to trash) | `void`           |
| [`deleteAssets(ids)`](#permanently-delete-assets) | Permanently delete multiple assets          | `void`           |

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

<a id="basic-asset-retrieval">

## Basic Asset Retrieval

<a id="getting-a-single-asset">

### Getting a Single Asset

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

```javascript
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');
```

<a id="listing-assets-with-pagination">

## Listing Assets with Pagination

<a id="basic-asset-listing">

### Basic Asset Listing

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

```javascript
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;
  }
}
```

<a id="asset-operations">

## Asset Operations

<a id="soft-delete-assets">

### Soft Delete Assets

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

```javascript
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);
```

<a id="permanently-delete-assets">

### Permanently Delete Assets

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

```javascript
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);
```

---

Full index of the CKBox documentation: [llms.txt](../../../../llms.txt)