Upload Node.js SDK

Install

To install the Upload Node.js SDK via NPM:

npm install upload-js-full node-fetch

To install via YARN:

yarn install upload-js-full node-fetch

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

Examples

Upload a File

To upload a file with the Upload Node.js SDK:

1import * as Upload from "upload-js-full";
2import fetch from "node-fetch";
3
4const uploadManager = new Upload.UploadManager(
5  new Upload.Configuration({
6    fetchApi: fetch,
7    apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
8  })
9);
10
11uploadManager
12  .upload({
13
14    // ---------
15    // Required:
16    // ---------
17
18    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
19
20    // Supported types for 'data' field:
21    // - String
22    // - Blob
23    // - Buffer
24    // - ReadableStream (Node.js), e.g. fs.createReadStream("file.txt")
25    data: "Hello World",
26
27    // Required when: 'data' is a stream.
28    // size: 5098,
29
30    // ---------
31    // Optional:
32    // ---------
33
34    // Required when: 'data' is a stream, buffer, or string.
35    mime: "text/plain",
36
37    // Required when: 'data' is a stream, buffer, or string.
38    originalFileName: "my_file.txt",
39
40    // Supported when: 'data' is not a stream.
41    maxConcurrentUploadParts: 4,
42
43    metadata: {
44      // Up to 2KB of arbitrary JSON.
45      productId: 60891
46    },
47
48    tags: [
49      // Up to 25 tags per file.
50      "example_tag"
51    ],
52
53    path: {
54      // See path variables: https://upload.io/docs/path-variables
55      folderPath: "/uploads/{UTC_YEAR}/{UTC_MONTH}/{UTC_DAY}",
56      fileName: "{UNIQUE_DIGITS_8}{ORIGINAL_FILE_EXT}"
57    },
58
59    cancellationToken: {
60      // Set to 'true' after invoking 'upload' to cancel the upload.
61      isCancelled: false
62    }
63  })
64  .then(
65    ({ fileUrl, filePath }) => {
66
67      // --------------------------------------------
68      // File successfully uploaded!
69      // --------------------------------------------
70      // The 'filePath' uniquely identifies the file,
71      // and is what you should save to your DB.
72      // --------------------------------------------
73      console.log(`File uploaded to: ${fileUrl}`);
74
75    },
76    error => console.error(`Upload failed: ${error.message}`, error)
77  );

See also: UploadManagerParams and Path Variables

Download a File

To download a file from your Upload account:

1import * as Upload from "upload-js-full";
2import fetch from "node-fetch";
3
4const fileApi = new Upload.FileApi(
5  new Upload.Configuration({
6    fetchApi: fetch,
7    apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
8  })
9);
10
11fileApi
12  .downloadFile({
13    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
14    filePath: "/uploads/2022/12/25/hello_world.txt"
15  })
16  .then(response => response.text()) // .text() | .json() | .blob() | .stream()
17  .then(
18    fileContents => console.log(fileContents),
19    error => console.error(error)
20  );

Learn more about the DownloadFile operation »

Process a File

To process a file and download the result:

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

Learn more about the ProcessFile operation »

Delete a File

To delete an uploaded file:

1import * as Upload from "upload-js-full";
2import fetch from "node-fetch";
3
4const fileApi = new Upload.FileApi(
5  new Upload.Configuration({
6    fetchApi: fetch,
7    apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
8  })
9);
10
11fileApi
12  .deleteFile({
13    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
14    filePath: "/uploads/2022/12/25/image.jpg"
15  })
16  .then(
17    () => console.log("File deleted."),
18    error => console.error(error)
19  );

List Files

To list the children of a folder:

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

Get File Metadata

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

1import * as Upload from "upload-js-full";
2import fetch from "node-fetch";
3
4const fileApi = new Upload.FileApi(
5  new Upload.Configuration({
6    fetchApi: fetch,
7    apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
8  })
9);
10
11fileApi
12  .getFileDetails({
13    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
14    filePath: "/uploads/2022/12/25/image.jpg"
15  })
16  .then(
17    fileDetails => console.log(fileDetails), // includes: size, mime, metadata, etc.
18    error => console.error(error)
19  );

API Reference

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

{
  "accountId": "YOUR_ACCOUNT_ID",
  "cancellationToken": {
    "isCancelled": false
  },
  "data": "Hello World",
  "maxConcurrentUploadParts": 2,
  "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"
  },
  "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 Upload from "upload-js-full";
import fetch from "node-fetch";

const uploadManager = new Upload.UploadManager(
  new Upload.Configuration({
    fetchApi: fetch,
    apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
  })
);

uploadManager
  .upload({
    "accountId": "YOUR_ACCOUNT_ID",
    "cancellationToken": {
      "isCancelled": false
    },
    "data": "Hello World",
    "maxConcurrentUploadParts": 2,
    "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"
    },
    "size": 11,
    "tags": [
      "example_tag"
    ]
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

UploadApi

Client methods for the Single & Multipart Upload APIs.

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.upload.io/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 Upload from "upload-js-full";
import fetch from "node-fetch";

const uploadApi = new Upload.UploadApi(
  new Upload.Configuration({
    fetchApi: fetch,
    apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
  })
);

uploadApi
  .uploadFromUrl({
    "accountId": "YOUR_ACCOUNT_ID",
    "uploadFromUrlRequest": {
      "url": "https://assets.upload.io/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 Upload from "upload-js-full";
import fetch from "node-fetch";

const uploadApi = new Upload.UploadApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const uploadApi = new Upload.UploadApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const uploadApi = new Upload.UploadApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const uploadApi = new Upload.UploadApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Management 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 Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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",
  "version": "1"
}

See details: ProcessFileParams

Result

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

See details: BinaryResult

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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",
    "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"
}

See details: ProcessFileAndSaveParams

Result

{
  "accountId": "YOUR_ACCOUNT_ID",
  "basePath": "/example-path",
  "baseUrl": "https://upcdn.io/A623uY2/raw/example-path",
  "summary": {
    "exampleArtifact": "/example-artifact.txt"
  }
}

See details: ProcessFileAndSaveResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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"
  })
  .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 Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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://upload.io/docs/upload-api/jobs/GetJob",
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "ExampleJob",
  "jobUrl": "https://api.upload.io/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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://upload.io/docs/upload-api/jobs/GetJob",
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "ExampleJob",
  "jobUrl": "https://api.upload.io/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const fileApi = new Upload.FileApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Management 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 Upload from "upload-js-full";
import fetch from "node-fetch";

const folderApi = new Upload.FolderApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const folderApi = new Upload.FolderApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const folderApi = new Upload.FolderApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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://upload.io/docs/upload-api/jobs/GetJob",
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "ExampleJob",
  "jobUrl": "https://api.upload.io/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const folderApi = new Upload.FolderApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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.

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://upload.io/docs/upload-api/jobs/GetJob",
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "ExampleJob",
  "jobUrl": "https://api.upload.io/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const folderApi = new Upload.FolderApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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://upload.io/docs/upload-api/jobs/GetJob",
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "ExampleJob",
  "jobUrl": "https://api.upload.io/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const folderApi = new Upload.FolderApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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://upload.io/docs/upload-api/jobs/GetJob",
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "ExampleJob",
  "jobUrl": "https://api.upload.io/v2/accounts/FW25aki/jobs/ExampleJob/01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

See details: AsyncResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const folderApi = new Upload.FolderApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Management 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",
  "attempts": 2,
  "created": 1615680311115,
  "error": {
    "code": "error_code",
    "message": "Error message."
  },
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "DeleteFileBatchJob",
  "lastUpdated": 1615680311115,
  "status": "Cancelled",
  "summary": {
    "deletions": [
      "/file/to/delete.jpg"
    ]
  }
}

See details: JobSummary

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const jobApi = new Upload.JobApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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",
      "attempts": 2,
      "created": 1615680311115,
      "error": {
        "code": "error_code",
        "message": "Error message."
      },
      "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "jobType": "DeleteFileBatchJob",
      "lastUpdated": 1615680311115,
      "status": "Cancelled",
      "summary": {
        "deletions": [
          "/file/to/delete.jpg"
        ]
      }
    }
  ]
}

See details: ListRecentJobsResponse

Example

import * as Upload from "upload-js-full";
import fetch from "node-fetch";

const jobApi = new Upload.JobApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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 Upload from "upload-js-full";
import fetch from "node-fetch";

const jobApi = new Upload.JobApi(
  new Upload.Configuration({
    fetchApi: fetch,
    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:

File Uploading

File Processing APIs

Data Types

More Resources

Upload Node.js SDK

Install

Examples

Upload a File

Download a File

Process a File

Delete a File

List Files

Get File Metadata

API Reference

UploadManager

upload

UploadApi

uploadFromUrl

beginMultipartUpload

completeUploadPart

getUploadPart

listUploadParts

FileApi

downloadFile

processFile

processFileAndSave

getFileDetails

copyFile

copyFileBatch

deleteFile

deleteFileBatch

FolderApi

putFolder

getFolderDetails

listFolder

copyFolder

copyFolderBatch

deleteFolder

deleteFolderBatch

JobApi

getJob

listRecentJobs

cancelJob

Upload Node.js SDK

You are using an outdated browser.