Data Types

Bytescale JavaScript SDK (Node.js)

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

Install

To install via NPM:

npm install @bytescale/sdk node-fetch

Note: this SDK depends on the Fetch API (a polyfill is included above).

Upload a File

To upload a file with the Bytescale JavaScript SDK (Node.js):

1import * as Bytescale from "@bytescale/sdk";
2import nodeFetch from "node-fetch";
3
4const uploadManager = new Bytescale.UploadManager({
5 fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
6 apiKey: "free" // Get API key: https://www.bytescale.com/get-started
7});
8
9uploadManager
10 .upload({
11
12 // Supported types:
13 // - String
14 // - Blob
15 // - ArrayBuffer
16 // - Buffer
17 // - ReadableStream (Node.js), e.g. fs.createReadStream("file.txt")
18 data: "Hello World",
19
20 // ---------
21 // Optional:
22 // ---------
23
24 // Required if 'data' is a stream.
25 // size: 5098, // e.g. fs.statSync("file.txt").size
26
27 // Required if 'data' is a stream, buffer, or string.
28 mime: "text/plain",
29
30 // Required if 'data' is a stream, buffer, or string.
31 originalFileName: "my_file.txt",
32
33 // Reports progress: bytesTotal, bytesSent, progress.
34 // onProgress: ({ progress }) => console.log(progress),
35
36 // Controls multipart upload concurrency. Ignored if 'data' is a stream.
37 // maxConcurrentUploadParts: 4,
38
39 // Up to 2KB of arbitrary JSON.
40 // metadata: {
41 // productId: 60891
42 // },
43
44 // Up to 25 tags per file.
45 // tags: [
46 // "example_tag"
47 // ],
48
49 // About file paths:
50 // - Your API key's "file upload path" is used by default, and can be changed by editing the API key's settings.
51 // - You can override the API key's file upload path by specifying a path below.
52 // - You may use path variables (e.g. "{UTC_DAY}"): https://www.bytescale.com/docs/path-variables
53 // path: {
54 // folderPath: "/uploads/{UTC_YEAR}/{UTC_MONTH}/{UTC_DAY}",
55 // fileName: "{UTC_TIME_TOKEN_INVERSE}{UNIQUE_DIGITS_2}{ORIGINAL_FILE_EXT}"
56 // },
57
58 // Set to 'isCancelled = true' after invoking 'upload' to cancel the upload.
59 // cancellationToken: {
60 // isCancelled: false
61 // }
62 })
63 .then(
64 ({ fileUrl, filePath }) => {
65
66 // --------------------------------------------
67 // File successfully uploaded!
68 // --------------------------------------------
69 // The 'filePath' uniquely identifies the file,
70 // and is what you should save to your DB.
71 // --------------------------------------------
72 console.log(`File uploaded to: ${fileUrl}`);
73
74 },
75 error => console.error(`Error: ${error.message}`, error)
76 );

See also: UploadManagerParams and Path Variables

Download a File

To download a file from your Bytescale account:

1import * as Bytescale from "@bytescale/sdk";
2import nodeFetch from "node-fetch";
3
4const fileApi = new Bytescale.FileApi({
5 fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
6 apiKey: "YOUR_API_KEY" // e.g. "public_xxxxx"
7});
8
9fileApi
10 .downloadFile({
11 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
12 filePath: "/uploads/2022/12/25/hello_world.txt"
13 })
14 .then(response => response.text()) // .text() | .json() | .blob() | .stream()
15 .then(
16 fileContents => console.log(fileContents),
17 error => console.error(error)
18 );

Learn more about the DownloadFile operation »

Process a File

To process a file and download the result:

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

Learn more about the ProcessFile operation »

Delete a File

To delete an uploaded file:

1import * as Bytescale from "@bytescale/sdk";
2import nodeFetch from "node-fetch";
3
4const fileApi = new Bytescale.FileApi({
5 fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
6 apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
7});
8
9fileApi
10 .deleteFile({
11 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
12 filePath: "/uploads/2022/12/25/image.jpg"
13 })
14 .then(
15 () => console.log("File deleted."),
16 error => console.error(error)
17 );

List Files

To list the children of a folder:

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

Get File Metadata

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

1import * as Bytescale from "@bytescale/sdk";
2import nodeFetch from "node-fetch";
3
4const fileApi = new Bytescale.FileApi({
5 fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
6 apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
7});
8
9fileApi
10 .getFileDetails({
11 accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
12 filePath: "/uploads/2022/12/25/image.jpg"
13 })
14 .then(
15 fileDetails => console.log(fileDetails), // includes: size, mime, metadata, etc.
16 error => console.error(error)
17 );

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";
import nodeFetch from "node-fetch";
const uploadManager = new Bytescale.UploadManager({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const uploadApi = new Bytescale.UploadApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const uploadApi = new Bytescale.UploadApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const uploadApi = new Bytescale.UploadApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const uploadApi = new Bytescale.UploadApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const uploadApi = new Bytescale.UploadApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const fileApi = new Bytescale.FileApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const folderApi = new Bytescale.FolderApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const jobApi = new Bytescale.JobApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const jobApi = new Bytescale.JobApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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";
import nodeFetch from "node-fetch";
const jobApi = new Bytescale.JobApi({
fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
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: