> For the complete documentation index, see [llms.txt](https://docs.coldstack.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coldstack.io/tools/supported-tools/sdk/using-extended-api-with-javascript.md).

# Using extended API with JavaScript

### Initialization

```bash
npm i axios aws4-axios
```

```typescript
import axios from 'axios';
import { aws4Interceptor } from 'aws4-axios';

const client = axios.create({
  baseURL: 'https://s3.coldstack.io'
})

client.interceptors.request.use(aws4Interceptor({
  region: 'us-east-1',
  service: 's3',
}, {
  accessKeyId: '...',
  secretAccessKey: '...',
}));
```

### Getting extended list of buckets

```typescript
const response = await client.get('/?extendedBuckets', {
    params: {
        format: 'json',
        perPage: 10,
        page: 1,
    },
});

console.log(response.data)
```

#### Result

```javascript
{
  "ListAllMyBucketsExtendedResult": {
    "PerPage": 10,
    "Page": 1,
    "Owner": {
      "ID": "...",
      "DisplayName": "..."
    },
    "Buckets": [
      {
        "Name": "bucket-1",
        "CreationDate": "2021-04-11T16:34:16.364Z",
        "ObjectsCount": "14",
        "ObjectsWithoutFoldersCount": "13"
      },
      {
        "Name": "bucket-2",
        "CreationDate": "2021-05-30T14:53:33.899Z",
        "ObjectsCount": "0",
        "ObjectsWithoutFoldersCount": "0"
      }
    ]
  }
}
```

### Getting extended list of objects

```typescript
const response = await client.get('/BUCKET?extendedObjects', {
    params: {
        format: 'json',
        perPage: 10,
        page: 1,
        delimiter: '/',
        prefix: 'folder/nested-folder/',
    },
});

console.log(response.data)
```

#### Result

```javascript
{
  "ListExtendedObjects": {
    "Name": "BUCKET",
    "PerPage": 10,
    "Page": 1,
    "Prefix": "folder/nested-folder/",
    "KeyCount": 2, // Количество результатов в данном ответе сервера
    "AvailableKeyCount": 2, // Количество файлов в этой папке
    "Delimiter": "/",
    "IsTruncated": false, // Урезан ли список файлов
    "Contents": [
      {
        "Key": "folder/nested-folder/15mb.random",
        "LastModified": "2021-08-12T22:14:53.608Z",
        "ETag": "\"bc71d03e01a1d931e15cf07bd0a90c2f-2\"",
        "Size": "15000000",
        "SizeReadable": "15 MB",
        "StorageClass": "STANDARD",
        "StorageClassReadable": "Standrad",
        "ContentType": "application/octet-stream",
        "ACL": "private",
        "FileType": "file"
      },
      {
        "Key": "folder/nested-folder/icon.png",
        "LastModified": "2021-08-12T22:13:05.894Z",
        "ETag": "\"629e4d5c1d0086a8c833bef7f3427994\"",
        "Size": "6459",
        "SizeReadable": "15 MB",
        "StorageClass": "STANDARD",
        "StorageClassReadable": "Standrad",
        "ContentType": "image/png",
        "ACL": "public-read",
        "FileType": "file"
      }
    ],
    "CommonPrefixes": [
      {
        "Prefix": "folder/nested-folder/other-nested-folder/",
        "Size": "6459",
        "SizeReadable": "15 MB",
        "LastModified": "2021-08-12T22:13:05.894Z"
      }
    ]
  }
}
```

### Get statistics

```typescript
const response = await client.get('/?statistics', {
    params: { format: 'json' } },
);

console.log(response.data);
```

#### Result

```javascript
{
  "Statistics": {
    "BucketsCount": 4,
    "ObjectsCount": 14,
    "UsedStorage": {
      "UsedStorageBytes": "286249388",
      "UsedStorageReadableQuantity": "286",
      "UsedStorageReadableUnit": "MB"
    },
    "Bandwidth": {
      "BandwidthBytes": "20159227",
      "BandwidthReadableQuantity": "20.2",
      "BandwidthReadableUnit": "MB"
    }
  }
}
```

### Get bandwidth analytics

```typescript
const response = await client.get('/?bandwidthAnalytics', {
  params: {
    format: 'json',
    fromDate: '...',
    toDate: '...',
  }
});

console.log(response.data);
```

#### Result

```javascript
{
  "BandwidthAnalytics": {
    "Records": [
      {
        "Date": "2021-08-13",
        "DownloadBandwidth": "15000000",
        "DownloadBandwidthReadable": "15 MB",
        "UploadBandwidth": "5159227",
        "UploadBandwidthReadable": "5.16 MB"
      },
      {
        "Date": "2021-08-14",
        "DownloadBandwidth": "15000000",
        "DownloadBandwidthReadable": "15 MB",
        "UploadBandwidth": "5159227",
        "UploadBandwidthReadable": "5.16 MB"
      }
    ]
  }
}
```

### Get storage usage analytics

```typescript
const response = await client.get('/?storageAnalytics', {
  params: {
    format: 'json',
    fromDate: '...',
    toDate: '...',
  }
});

console.log(response.data);
```

#### Result

```javascript
{
  "StorageUsageAnalytics": {
    "Records": [
      {
        "Timestamp": "2021-08-31T01:00:00.000Z",
        "UsedStorage": "15000000",
        "UsedStorageReadable": "15 MB"
      },
      {
        "Timestamp": "2021-08-31T02:00:00.000Z",
        "UsedStorage": "16000000",
        "UsedStorageReadable": "16 MB"
      }
    ]
  }
}
```

### Rename bucket

```typescript
await client({
  url: '/old-bucket-name',
  method: 'MOVE',
  headers: {
    'Destination': 'new-bucket-name',
  },
});
```

### Rename a file

```typescript
await client({
  url: '/old-bucket-name/file.txt',
  method: 'MOVE',
  headers: {
    'Destination': 'file-2.txt',
  },
});
```

### Rename a folder

```typescript
await client({
  url: '/old-bucket-name/folder/',
  method: 'MOVE',
  headers: {
    'Destination': 'folder-2/',
    'X-ColdStack-Prefix': 'true',
  },
});
```

### Get Extended info about file (extended HeadObject)

```typescript
await client({
  url: '/old-bucket-name/file?extendedInfo',
  method: 'GET',
  params: {
    format: 'json',
  },
});
```

#### Result

```javascript
{
  "ObjectExtendedInfo": {
    "CacheControl": "...",
    "ContentDisposition": "...",
    "ContentEncoding": "...",
    "ContentLanguage": "...",
    "Expires": "...",
    "ContentType": "...",
    "FileType": "...",
    "ETag": "...",
    "Size": 1024,
    "SizeReadable": "1 KB",
    "LastModified": "...",
    "StorageClass": "...",
    "StorageClassReadable": "...",
    "Metadata": {
      "key": "value"
    },
    "ACL": "private" | "public-read",
    "Owner": {
      "ID": "...",
      "DisplayName": "..."
    }
  }
}
```

### Check if user can upload

```typescript
await client({
  url: '/?canUpload',
  method: 'GET',
});
```

#### Result

```typescript
{
    "CanUpload": true
}
```

or

```typescript
{
    "CanUpload": true,
    "Message": "To store files or create folders you have to maintain balance in CLS worth of at least 1 dollar."
}
```

### Check if user can download

```typescript
await client({
  url: '/?canDownload',
  method: 'GET',
});
```

#### Result

```typescript
{
    "CanDownload": true
}
```

or

```typescript
{
    "CanDownload": true,
    "Message": "To store files or create folders you have to maintain balance in CLS worth of at least 1 dollar."
}
```

### Search files

```typescript
await client({
  url: '/?searchFiles',
  method: 'GET',
  params: {
    "perPage": 10,
    "page": 1,
    "format": "json",
    "filename": "video"
  }
});
```

Result

```json
{
  "SearchFilesResult": {
    "Query": {
      "perPage": 10,
      "page": 1
    },
    "Files": [
      {
        "Key": "videos/pres-video.mp4",
        "FileType": "video",
        "Bucket": "personal-files",
        "FileName": "pres-video.mp4"
      },
      {
        "Key": "other-files/videos-list.txt",
        "FileType": "file",
        "Bucket": "other-bucket",
        "FileName": "videos-list.txt"
      }
    ]
}
```