Data Types

Bytescale JavaScript SDK

Lightweight headless SDK for uploading, processing, and managing files with Bytescale.

Install

To install via NPM:

npm install @bytescale/sdk

To install via a script tag:

<script src="https://js.bytescale.com/sdk/v3"></script>

Upload a File

To upload a file with the Bytescale JavaScript SDK:

1<html>
2 <head>
3 <script src="https://js.bytescale.com/sdk/v3"></script>
4 <script>
5 // import * as Bytescale from "@bytescale/sdk";
6 const uploadManager = new Bytescale.UploadManager({
7 apiKey: "free" // Get API key: https://www.bytescale.com/get-started
8 });
9
10 const onFileSelected = async event => {
11 const file = event.target.files[0];
12
13 try {
14 const { fileUrl, filePath } = await uploadManager.upload({
15
16 // Supported types:
17 // - String
18 // - Blob
19 // - ArrayBuffer
20 // - File (i.e. from a DOM file input element)
21 data: file,
22
23 // ---------
24 // Optional:
25 // ---------
26
27 // Required if 'data' is a stream. Node.js only. (Not required when uploading files from the browser.)
28 // size: 5098, // e.g. fs.statSync("file.txt").size
29
30 // Required if 'data' is a stream, buffer, or string. (Not required for DOM file inputs or blobs.)
31 // mime: "application/octet-stream",
32
33 // Required if 'data' is a stream, buffer, or string. (Not required for DOM file inputs or blobs.)
34 // originalFileName: "my_file.txt",
35
36 // Reports progress: bytesTotal, bytesSent, progress.
37 // onProgress: ({ progress }) => console.log(progress),
38
39 // Controls multipart upload concurrency. Ignored if 'data' is a stream.
40 // maxConcurrentUploadParts: 4,
41
42 // Up to 2KB of arbitrary JSON.
43 // metadata: {
44 // productId: 60891
45 // },
46
47 // Up to 25 tags per file.
48 // tags: [
49 // "example_tag"
50 // ],
51
52 // About file paths:
53 // - Your API key's "file upload path" is used by default, and can be changed by editing the API key's settings.
54 // - You can override the API key's file upload path by specifying a path below.
55 // - You may use path variables (e.g. "{UTC_DAY}"): https://www.bytescale.com/docs/path-variables
56 // path: {
57 // folderPath: "/uploads/{UTC_YEAR}/{UTC_MONTH}/{UTC_DAY}",
58 // fileName: "{UTC_TIME_TOKEN_INVERSE}{UNIQUE_DIGITS_2}{ORIGINAL_FILE_EXT}"
59 // },
60
61 // Set to 'isCancelled = true' after invoking 'upload' to cancel the upload.
62 // cancellationToken: {
63 // isCancelled: false
64 // }
65 });
66
67 // --------------------------------------------
68 // File successfully uploaded!
69 // --------------------------------------------
70 // The 'filePath' uniquely identifies the file,
71 // and is what you should save to your API.
72 // --------------------------------------------
73 alert(`File uploaded:\n${fileUrl}`);
74
75 } catch (e) {
76 alert(`Error:\n${e.message}`);
77 }
78 }
79 </script>
80 </head>
81 <body>
82 <input type="file" onchange="onFileSelected(event)" />
83 </body>
84</html>

See also: UploadManagerParams and Path Variables

Live example:

Download a File

To download a file from your Bytescale account:

1import * as Bytescale from "@bytescale/sdk";
2
3const fileApi = new Bytescale.FileApi({
4 apiKey: "YOUR_API_KEY" // e.g. "public_xxxxx"
5});
6
7fileApi
8 .downloadFile({
9 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
10 filePath: "/uploads/2022/12/25/hello_world.txt"
11 })
12 .then(response => response.text()) // .text() | .json() | .blob() | .stream()
13 .then(
14 fileContents => console.log(fileContents),
15 error => console.error(error)
16 );

Learn more about the DownloadFile operation »

Process a File

To process a file and download the result:

1import * as Bytescale from "@bytescale/sdk";
2import fs from "fs";
3
4const fileApi = new Bytescale.FileApi({
5 apiKey: "YOUR_API_KEY" // e.g. "public_xxxxx"
6});
7
8fileApi
9 .processFile({
10 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
11 filePath: "/uploads/2022/12/25/image.jpg",
12 transformation: "thumbnail"
13 })
14 .then(response => response.stream()) // .text() | .json() | .blob() | .stream()
15 .then(
16 imageByteStream =>
17 new Promise((resolve, reject) => {
18 const writer = fs.createWriteStream("image-thumbnail.jpg");
19 writer.on("close", resolve);
20 writer.on("error", reject);
21 imageByteStream.pipe(writer);
22 })
23 )
24 .then(
25 () => console.log("Thumbnail saved to 'image-thumbnail.jpg'"),
26 error => console.error(error)
27 );

Learn more about the ProcessFile operation »

Delete a File

To delete an uploaded file:

1import * as Bytescale from "@bytescale/sdk";
2
3const fileApi = new Bytescale.FileApi({
4 apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
5});
6
7fileApi
8 .deleteFile({
9 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
10 filePath: "/uploads/2022/12/25/image.jpg"
11 })
12 .then(
13 () => console.log("File deleted."),
14 error => console.error(error)
15 );

List Files

To list the children of a folder:

1import * as Bytescale from "@bytescale/sdk";
2
3const folderApi = new Bytescale.FolderApi({
4 apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
5});
6
7folderApi
8 .listFolder({
9 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
10 folderPath: "/",
11 recursive: false
12 })
13 .then(
14 // Note: operation is paginated, see 'result.cursor' and 'params.cursor'.
15 result => console.log(`Items in folder: ${result.items.length}`),
16 error => console.error(error)
17 );

Get File Metadata

To get the full details of a file (including any custom metadata):

1import * as Bytescale from "@bytescale/sdk";
2
3const fileApi = new Bytescale.FileApi({
4 apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
5});
6
7fileApi
8 .getFileDetails({
9 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
10 filePath: "/uploads/2022/12/25/image.jpg"
11 })
12 .then(
13 fileDetails => console.log(fileDetails), // includes: size, mime, metadata, etc.
14 error => console.error(error)
15 );

UploadManager

Helper class for performing file uploads.

upload

Uploads a file, string, blob, or stream as the data parameter. (size is only required if the data is a stream.)

Signature

function upload(params: UploadManagerParams): Promise<FileDetails>

Parameters

{
"cancellationToken": {
"isCancelled": false
},
"data": "Hello World",
"maxConcurrentUploadParts": 2,
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "text/plain",
"onProgress": Function,
"originalFileName": "example.txt",
"path": {
"fileName": "example-{UNIQUE_DIGITS_4}{ORIGINAL_FILE_EXT}",
"folderPath": "/uploads"
},
"size": 11,
"tags": [
"example_tag"
]
}

See details: UploadManagerParams

Result

{
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg",
"fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg",
"lastModified": 1615680311115,
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "image/jpeg",
"originalFileName": "example.jpg",
"size": 43182,
"tags": [
"example_tag"
]
}

See details: FileDetails

Example

import * as Bytescale from "@bytescale/sdk";
const uploadManager = new Bytescale.UploadManager({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
uploadManager
.upload({
"cancellationToken": {
"isCancelled": false
},
"data": "Hello World",
"maxConcurrentUploadParts": 2,
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "text/plain",
"onProgress": Function,
"originalFileName": "example.txt",
"path": {
"fileName": "example-{UNIQUE_DIGITS_4}{ORIGINAL_FILE_EXT}",
"folderPath": "/uploads"
},
"size": 11,
"tags": [
"example_tag"
]
})
.then(
result => console.log(result),
error => console.error(error)
);

UploadApi

Client methods for the Upload API.

Use the UploadManager instead of calling these methods directly.

uploadFromUrl

Upload from a URL with a single HTTP request:

Signature

function uploadFromUrl(params: UploadFromUrlParams): Promise<BasicUploadResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"uploadFromUrlRequest": {
"url": "https://assets.bytescale.com/example.jpg"
}
}

See details: UploadFromUrlParams

Result

{
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/file.txt",
"fileUrl": "https://upcdn.io/A623uY2/raw/uploads/file.txt"
}

See details: BasicUploadResponse

Example

import * as Bytescale from "@bytescale/sdk";
const uploadApi = new Bytescale.UploadApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
uploadApi
.uploadFromUrl({
"accountId": "YOUR_ACCOUNT_ID",
"uploadFromUrlRequest": {
"url": "https://assets.bytescale.com/example.jpg"
}
})
.then(
result => console.log(result),
error => console.error(error)
);

beginMultipartUpload

Begins a new multipart file upload process.

Signature

function beginMultipartUpload(params: BeginMultipartUploadParams): Promise<BeginMultipartUploadResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"beginMultipartUploadRequest": {
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "text/plain",
"originalFileName": "example.txt",
"path": {
"fileName": "example-{UNIQUE_DIGITS_4}{ORIGINAL_FILE_EXT}",
"folderPath": "/uploads"
},
"protocol": "1.0",
"size": 43182,
"tags": [
"example_tag"
]
}
}

See details: BeginMultipartUploadParams

Result

{
"file": {
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg",
"fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg",
"lastModified": 1615680311115,
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "image/jpeg",
"originalFileName": "example.jpg",
"size": 43182,
"tags": [
"example_tag"
]
},
"uploadId": "Kd759aLFxttm69kZ",
"uploadParts": {
"count": 12,
"first": {
"range": {
"inclusiveEnd": 5242879,
"inclusiveStart": 0
},
"uploadId": "Kd759aLFxttm69kZ",
"uploadPartIndex": 7,
"uploadUrl": "https://...long-url...x-id=PutObject"
}
}
}

See details: BeginMultipartUploadResponse

Example

import * as Bytescale from "@bytescale/sdk";
const uploadApi = new Bytescale.UploadApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
uploadApi
.beginMultipartUpload({
"accountId": "YOUR_ACCOUNT_ID",
"beginMultipartUploadRequest": {
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "text/plain",
"originalFileName": "example.txt",
"path": {
"fileName": "example-{UNIQUE_DIGITS_4}{ORIGINAL_FILE_EXT}",
"folderPath": "/uploads"
},
"protocol": "1.0",
"size": 43182,
"tags": [
"example_tag"
]
}
})
.then(
result => console.log(result),
error => console.error(error)
);

completeUploadPart

Marks an upload part as uploaded.

You must call this endpoint after you have successfully issued a PUT request to the uploadUrl on the corresponding UploadPart.

Signature

function completeUploadPart(params: CompleteUploadPartParams): Promise<void>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"completeUploadPartRequest": {
"etag": "33a64df551425fcc55e4d42a148795d9f25f89d4"
},
"uploadId": "Kd759aLFxttm69kZ",
"uploadPartIndex": 7
}

See details: CompleteUploadPartParams

Result

This method has no result.

Example

import * as Bytescale from "@bytescale/sdk";
const uploadApi = new Bytescale.UploadApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
uploadApi
.completeUploadPart({
"accountId": "YOUR_ACCOUNT_ID",
"completeUploadPartRequest": {
"etag": "33a64df551425fcc55e4d42a148795d9f25f89d4"
},
"uploadId": "Kd759aLFxttm69kZ",
"uploadPartIndex": 7
})
.then(
result => console.log(result),
error => console.error(error)
);

getUploadPart

Gets a remaining upload part for a multipart file upload.

Signature

function getUploadPart(params: GetUploadPartParams): Promise<UploadPart>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"uploadId": "Kd759aLFxttm69kZ",
"uploadPartIndex": 7
}

See details: GetUploadPartParams

Result

{
"range": {
"inclusiveEnd": 5242879,
"inclusiveStart": 0
},
"uploadId": "Kd759aLFxttm69kZ",
"uploadPartIndex": 7,
"uploadUrl": "https://...long-url...x-id=PutObject"
}

See details: UploadPart

Example

import * as Bytescale from "@bytescale/sdk";
const uploadApi = new Bytescale.UploadApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
uploadApi
.getUploadPart({
"accountId": "YOUR_ACCOUNT_ID",
"uploadId": "Kd759aLFxttm69kZ",
"uploadPartIndex": 7
})
.then(
result => console.log(result),
error => console.error(error)
);

listUploadParts

Lists the remaining upload parts for a multipart file upload.

An empty array is returned when the upload is complete.

Signature

function listUploadParts(params: ListUploadPartsParams): Promise<UploadPartList>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"uploadId": "Kd759aLFxttm69kZ"
}

See details: ListUploadPartsParams

Result

{
"remainingUploadParts": [
3,
4,
6
]
}

See details: UploadPartList

Example

import * as Bytescale from "@bytescale/sdk";
const uploadApi = new Bytescale.UploadApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
uploadApi
.listUploadParts({
"accountId": "YOUR_ACCOUNT_ID",
"uploadId": "Kd759aLFxttm69kZ"
})
.then(
result => console.log(result),
error => console.error(error)
);

FileApi

Client methods for the File API.

downloadFile

Downloads a file in its original/unprocessed state.

Signature

function downloadFile(params: DownloadFileParams): Promise<BinaryResult>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"cache": true,
"cache_ttl": 31536000,
"filePath": "/uploads/image.jpg",
"version": "1"
}

See details: DownloadFileParams

Result

{
"blob": Function,
"json": Function,
"stream": Function,
"text": Function
}

See details: BinaryResult

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.downloadFile({
"accountId": "YOUR_ACCOUNT_ID",
"cache": true,
"cache_ttl": 31536000,
"filePath": "/uploads/image.jpg",
"version": "1"
})
.then(
result => console.log(result),
error => console.error(error)
);

processFile

Processes a file and returns the result.

Signature

function processFile(params: ProcessFileParams): Promise<BinaryResult>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"artifact": "/example/video/part-a.ts",
"cache": true,
"cache_perm": "auto",
"cache_ttl": 31536000,
"filePath": "/uploads/image.jpg",
"large": false,
"transformation": "thumbnail",
"transformationParams": {},
"version": "1"
}

See details: ProcessFileParams

Result

{
"blob": Function,
"json": Function,
"stream": Function,
"text": Function
}

See details: BinaryResult

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.processFile({
"accountId": "YOUR_ACCOUNT_ID",
"artifact": "/example/video/part-a.ts",
"cache": true,
"cache_perm": "auto",
"cache_ttl": 31536000,
"filePath": "/uploads/image.jpg",
"large": false,
"transformation": "thumbnail",
"transformationParams": {},
"version": "1"
})
.then(
result => console.log(result),
error => console.error(error)
);

processFileAndSave

Processes a file and saves the result.

Signature

function processFileAndSave(params: ProcessFileAndSaveParams): Promise<ProcessFileAndSaveResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg",
"processFileAndSaveRequest": {
"destination": {
"fileName": "example-{UNIQUE_DIGITS_4}{ORIGINAL_FILE_EXT}"
}
},
"transformation": "thumbnail",
"transformationParams": {}
}

See details: ProcessFileAndSaveParams

Result

{
"async": false,
"accountId": "A623uY2",
"filePath": "/my-processed-image.jpg",
"fileUrl": "https://upcdn.io/A623uY2/raw/my-processed-image.jpg"
}

See details: ProcessFileAndSaveResponse

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.processFileAndSave({
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg",
"processFileAndSaveRequest": {
"destination": {
"fileName": "example-{UNIQUE_DIGITS_4}{ORIGINAL_FILE_EXT}"
}
},
"transformation": "thumbnail",
"transformationParams": {}
})
.then(
result => console.log(result),
error => console.error(error)
);

getFileDetails

Gets the full details (e.g. metadata, tags, etc.) for a file.

Signature

function getFileDetails(params: GetFileDetailsParams): Promise<FileDetails>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg"
}

See details: GetFileDetailsParams

Result

{
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg",
"fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg",
"lastModified": 1615680311115,
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "image/jpeg",
"originalFileName": "example.jpg",
"size": 43182,
"tags": [
"example_tag"
]
}

See details: FileDetails

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.getFileDetails({
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg"
})
.then(
result => console.log(result),
error => console.error(error)
);

copyFile

Copies a file synchronously.

Signature

function copyFile(params: CopyFileParams): Promise<CopyFileResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"copyFileRequest": {
"condition": {
"equals": "*",
"type": "Equals"
},
"destination": "/destination/file.txt",
"source": "/source/file.txt"
}
}

See details: CopyFileParams

Result

{
"status": "Copied"
}

See details: CopyFileResponse

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.copyFile({
"accountId": "YOUR_ACCOUNT_ID",
"copyFileRequest": {
"condition": {
"equals": "*",
"type": "Equals"
},
"destination": "/destination/file.txt",
"source": "/source/file.txt"
}
})
.then(
result => console.log(result),
error => console.error(error)
);

copyFileBatch

Copies multiple files asynchronously.

Signature

function copyFileBatch(params: CopyFileBatchParams): Promise<AsyncResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"copyFileBatchRequest": {
"files": [
{
"condition": {
"equals": "*",
"type": "Equals"
},
"destination": "/destination/file.txt",
"source": "/source/file.txt"
}
]
}
}

See details: CopyFileBatchParams

Result

{
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.copyFileBatch({
"accountId": "YOUR_ACCOUNT_ID",
"copyFileBatchRequest": {
"files": [
{
"condition": {
"equals": "*",
"type": "Equals"
},
"destination": "/destination/file.txt",
"source": "/source/file.txt"
}
]
}
})
.then(
result => console.log(result),
error => console.error(error)
);

deleteFile

Deletes a file synchronously.

Signature

function deleteFile(params: DeleteFileParams): Promise<void>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg"
}

See details: DeleteFileParams

Result

This method has no result.

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.deleteFile({
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg"
})
.then(
result => console.log(result),
error => console.error(error)
);

deleteFileBatch

Deletes multiple files asynchronously.

Signature

function deleteFileBatch(params: DeleteFileBatchParams): Promise<AsyncResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"deleteFileBatchRequest": {
"files": [
"/uploads/image.jpg"
]
}
}

See details: DeleteFileBatchParams

Result

{
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Bytescale from "@bytescale/sdk";
const fileApi = new Bytescale.FileApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
fileApi
.deleteFileBatch({
"accountId": "YOUR_ACCOUNT_ID",
"deleteFileBatchRequest": {
"files": [
"/uploads/image.jpg"
]
}
})
.then(
result => console.log(result),
error => console.error(error)
);

FolderApi

Client methods for the Folder API.

putFolder

Creates or updates the folder specified by the folderPath.

If the folder's ancestors do not exist, they will be created automatically (with empty FolderSettings).

Note: you don't need to create folders before uploading files to them.

Signature

function putFolder(params: PutFolderParams): Promise<FolderDetails>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"putFolderRequest": {
"allowUnnamedFolder": false,
"folderPath": "/uploads",
"folderSettings": {
"description": {
"set": true,
"value": "This is an example folder description."
},
"publicPermissions": {
"set": true,
"value": [
{
"permissions": {
"file": {
"downloadFile": [
"*"
]
}
},
"scope": "Children"
}
]
},
"storageLayer": {
"set": true,
"value": {
"bucket": {
"bucketName": "my-bucket",
"bucketRegion": "nyc3",
"objectKeyPrefix": "an/example/key"
},
"credentials": {
"spacesAccessKey": "AKIAIOSFODNN7EXAMPLE",
"spacesSecretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
"type": "DigitalOceanSpace",
"useAbsolutePaths": true
}
}
}
}
}

See details: PutFolderParams

Result

{
"folderPath": "/uploads",
"settings": {
"description": "This is an example folder description.",
"publicPermissions": [
{
"permissions": {
"file": {
"downloadFile": [
"*"
]
}
},
"scope": "Children"
}
],
"storageLayer": {
"type": "InternalStorageV2"
}
},
"settingsInherited": {
"publicPermissions": {
"folderPath": "/uploads",
"value": [
{
"permissions": {
"file": {
"downloadFile": [
"*"
]
}
},
"scope": "Children"
}
]
},
"storageLayer": {
"folderPath": "/uploads",
"value": {
"bucket": {
"bucketName": "my-bucket",
"bucketRegion": "nyc3",
"objectKeyPrefix": "an/example/key"
},
"type": "DigitalOceanSpace",
"useAbsolutePaths": true
}
}
},
"type": "Folder",
"virtual": true
}

See details: FolderDetails

Example

import * as Bytescale from "@bytescale/sdk";
const folderApi = new Bytescale.FolderApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
folderApi
.putFolder({
"accountId": "YOUR_ACCOUNT_ID",
"putFolderRequest": {
"allowUnnamedFolder": false,
"folderPath": "/uploads",
"folderSettings": {
"description": {
"set": true,
"value": "This is an example folder description."
},
"publicPermissions": {
"set": true,
"value": [
{
"permissions": {
"file": {
"downloadFile": [
"*"
]
}
},
"scope": "Children"
}
]
},
"storageLayer": {
"set": true,
"value": {
"bucket": {
"bucketName": "my-bucket",
"bucketRegion": "nyc3",
"objectKeyPrefix": "an/example/key"
},
"credentials": {
"spacesAccessKey": "AKIAIOSFODNN7EXAMPLE",
"spacesSecretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
"type": "DigitalOceanSpace",
"useAbsolutePaths": true
}
}
}
}
})
.then(
result => console.log(result),
error => console.error(error)
);

getFolderDetails

Gets the full details (e.g. permission, storage layer, etc.) for a folder.

Returns an empty object if no settings have been configured for this folder.

Signature

function getFolderDetails(params: GetFolderDetailsParams): Promise<FolderDetails>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"folderPath": "/uploads"
}

See details: GetFolderDetailsParams

Result

{
"folderPath": "/uploads",
"settings": {
"description": "This is an example folder description.",
"publicPermissions": [
{
"permissions": {
"file": {
"downloadFile": [
"*"
]
}
},
"scope": "Children"
}
],
"storageLayer": {
"type": "InternalStorageV2"
}
},
"settingsInherited": {
"publicPermissions": {
"folderPath": "/uploads",
"value": [
{
"permissions": {
"file": {
"downloadFile": [
"*"
]
}
},
"scope": "Children"
}
]
},
"storageLayer": {
"folderPath": "/uploads",
"value": {
"bucket": {
"bucketName": "my-bucket",
"bucketRegion": "nyc3",
"objectKeyPrefix": "an/example/key"
},
"type": "DigitalOceanSpace",
"useAbsolutePaths": true
}
}
},
"type": "Folder",
"virtual": true
}

See details: FolderDetails

Example

import * as Bytescale from "@bytescale/sdk";
const folderApi = new Bytescale.FolderApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
folderApi
.getFolderDetails({
"accountId": "YOUR_ACCOUNT_ID",
"folderPath": "/uploads"
})
.then(
result => console.log(result),
error => console.error(error)
);

listFolder

Lists the folder's contents.

The result may be paginated: subsequent pages can be requested by passing the cursor from the response into the cursor request parameter.

Pagination is complete when the response includes isPaginationComplete=true.

Signature

function listFolder(params: ListFolderParams): Promise<ListFolderResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"cursor": "aGVsbG8=",
"dryRun": true,
"folderPath": "/uploads",
"includeFiles": true,
"includeOverriddenStorage": true,
"includePhysicalFolders": true,
"includeVirtualFolders": true,
"limit": 50,
"recursive": true
}

See details: ListFolderParams

Result

{
"cursor": "/uploads/file.jpg",
"folder": {
"folderPath": "/uploads",
"settings": {
"description": "This is an example folder description.",
"publicPermissions": [
{
"permissions": {
"file": {
"downloadFile": [
"*"
]
}
},
"scope": "Children"
}
],
"storageLayer": {
"type": "InternalStorageV2"
}
},
"type": "Folder",
"virtual": true
},
"isPaginationComplete": true,
"items": [
{
"filePath": "/uploads/image.jpg",
"fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg",
"lastModified": 1615680311115,
"size": 43182,
"type": "File"
}
]
}

See details: ListFolderResponse

Example

import * as Bytescale from "@bytescale/sdk";
const folderApi = new Bytescale.FolderApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
folderApi
.listFolder({
"accountId": "YOUR_ACCOUNT_ID",
"cursor": "aGVsbG8=",
"dryRun": true,
"folderPath": "/uploads",
"includeFiles": true,
"includeOverriddenStorage": true,
"includePhysicalFolders": true,
"includeVirtualFolders": true,
"limit": 50,
"recursive": true
})
.then(
result => console.log(result),
error => console.error(error)
);

copyFolder

Copies a folder asynchronously.

You can use ListFolder to preview the operation: set dryRun=true with recursive, includeFiles, includeOverriddenStorage and includeVirtualFolders set to match the values you're using here. Leave all other flags unset.

Signature

function copyFolder(params: CopyFolderParams): Promise<AsyncResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"copyFolderRequest": {
"condition": {
"equals": "*",
"type": "Equals"
},
"copyFiles": true,
"copyOverriddenStorage": false,
"copyVirtualFolders": true,
"destination": "/destination/folder",
"recursive": true,
"source": "/source/folder"
}
}

See details: CopyFolderParams

Result

{
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Bytescale from "@bytescale/sdk";
const folderApi = new Bytescale.FolderApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
folderApi
.copyFolder({
"accountId": "YOUR_ACCOUNT_ID",
"copyFolderRequest": {
"condition": {
"equals": "*",
"type": "Equals"
},
"copyFiles": true,
"copyOverriddenStorage": false,
"copyVirtualFolders": true,
"destination": "/destination/folder",
"recursive": true,
"source": "/source/folder"
}
})
.then(
result => console.log(result),
error => console.error(error)
);

copyFolderBatch

Copies multiple folders asynchronously.

You can use ListFolder to preview the operation: set dryRun=true with recursive, includeFiles, includeOverriddenStorage and includeVirtualFolders set to match the values you're using here. Leave all other flags unset.

Signature

function copyFolderBatch(params: CopyFolderBatchParams): Promise<AsyncResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"copyFolderBatchRequest": {
"folders": [
{
"condition": {
"equals": "*",
"type": "Equals"
},
"copyFiles": true,
"copyOverriddenStorage": false,
"copyVirtualFolders": true,
"destination": "/destination/folder",
"recursive": true,
"source": "/source/folder"
}
]
}
}

See details: CopyFolderBatchParams

Result

{
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Bytescale from "@bytescale/sdk";
const folderApi = new Bytescale.FolderApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
folderApi
.copyFolderBatch({
"accountId": "YOUR_ACCOUNT_ID",
"copyFolderBatchRequest": {
"folders": [
{
"condition": {
"equals": "*",
"type": "Equals"
},
"copyFiles": true,
"copyOverriddenStorage": false,
"copyVirtualFolders": true,
"destination": "/destination/folder",
"recursive": true,
"source": "/source/folder"
}
]
}
})
.then(
result => console.log(result),
error => console.error(error)
);

deleteFolder

Deletes a folder asynchronously.

If the folder has overridden storage settings, then no files will be deleted.

You can use ListFolder to preview the operation: set dryRun=true with recursive, includeFiles and includeVirtualFolders set to match the values you're using here. Leave all other flags unset.

Signature

function deleteFolder(params: DeleteFolderParams): Promise<AsyncResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"deleteFolderRequest": {
"deleteFiles": true,
"deleteVirtualFolders": true,
"folderPath": "/uploads",
"recursive": true
}
}

See details: DeleteFolderParams

Result

{
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Bytescale from "@bytescale/sdk";
const folderApi = new Bytescale.FolderApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
folderApi
.deleteFolder({
"accountId": "YOUR_ACCOUNT_ID",
"deleteFolderRequest": {
"deleteFiles": true,
"deleteVirtualFolders": true,
"folderPath": "/uploads",
"recursive": true
}
})
.then(
result => console.log(result),
error => console.error(error)
);

deleteFolderBatch

Deletes multiple folders asynchronously.

If the folder has overridden storage settings, then no files will be deleted.

You can use ListFolder to preview the operation: set dryRun=true with recursive, includeFiles and includeVirtualFolders set to match the values you're using here. Leave all other flags unset.

Signature

function deleteFolderBatch(params: DeleteFolderBatchParams): Promise<AsyncResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"deleteFolderBatchRequest": {
"folders": [
{
"deleteFiles": true,
"deleteVirtualFolders": true,
"folderPath": "/uploads",
"recursive": true
}
]
}
}

See details: DeleteFolderBatchParams

Result

{
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Bytescale from "@bytescale/sdk";
const folderApi = new Bytescale.FolderApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
folderApi
.deleteFolderBatch({
"accountId": "YOUR_ACCOUNT_ID",
"deleteFolderBatchRequest": {
"folders": [
{
"deleteFiles": true,
"deleteVirtualFolders": true,
"folderPath": "/uploads",
"recursive": true
}
]
}
})
.then(
result => console.log(result),
error => console.error(error)
);

JobApi

Client methods for the Job API.

getJob

Gets information on a background job.

Requires a secret_* API key.

Signature

function getJob(params: GetJobParams): Promise<JobSummary>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "CopyFileBatchJob"
}

See details: GetJobParams

Result

{
"accountId": "YOUR_ACCOUNT_ID",
"created": 1615680311115,
"error": {
"code": "error_code",
"message": "Error message."
},
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV",
"lastUpdated": 1615680311115,
"status": "Cancelled",
"summary": {
"deletions": [
"/file/to/delete.jpg"
]
}
}

See details: JobSummary

Example

import * as Bytescale from "@bytescale/sdk";
const jobApi = new Bytescale.JobApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
jobApi
.getJob({
"accountId": "YOUR_ACCOUNT_ID",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "CopyFileBatchJob"
})
.then(
result => console.log(result),
error => console.error(error)
);

listRecentJobs

Lists the most recently issued background jobs.

Requires a secret_* API key.

Signature

function listRecentJobs(params: ListRecentJobsParams): Promise<ListRecentJobsResponse>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"jobType": [
"CopyFileBatchJob"
]
}

See details: ListRecentJobsParams

Result

{
"items": [
{
"accountId": "YOUR_ACCOUNT_ID",
"created": 1615680311115,
"error": {
"code": "error_code",
"message": "Error message."
},
"jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "ExampleJob",
"jobUrl": "https://api.bytescale.com/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV",
"lastUpdated": 1615680311115,
"status": "Cancelled",
"summary": {
"deletions": [
"/file/to/delete.jpg"
]
}
}
]
}

See details: ListRecentJobsResponse

Example

import * as Bytescale from "@bytescale/sdk";
const jobApi = new Bytescale.JobApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
jobApi
.listRecentJobs({
"accountId": "YOUR_ACCOUNT_ID",
"jobType": [
"CopyFileBatchJob"
]
})
.then(
result => console.log(result),
error => console.error(error)
);

cancelJob

Cancels an in-progress background job.

Requires a secret_* API key.

Signature

function cancelJob(params: CancelJobParams): Promise<void>

Parameters

{
"accountId": "YOUR_ACCOUNT_ID",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "CopyFileBatchJob"
}

See details: CancelJobParams

Result

This method has no result.

Example

import * as Bytescale from "@bytescale/sdk";
const jobApi = new Bytescale.JobApi({
apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});
jobApi
.cancelJob({
"accountId": "YOUR_ACCOUNT_ID",
"jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"jobType": "CopyFileBatchJob"
})
.then(
result => console.log(result),
error => console.error(error)
);

Was this section helpful? Yes No

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: