# 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"
      }
    ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coldstack.io/tools/supported-tools/sdk/using-extended-api-with-javascript.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.