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      "product_image"
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  );

Or download files via the URL: https://upcdn.io/{accountId}/raw/{filePath}

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  );

Or process files via the URL: https://upcdn.io/{accountId}/{transformation}/{filePath}

To create transformations: see the Upload Dashboard »

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  .listFolderChildren({
13    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
14    folderPath: "/"
15  })
16  .then(
17    // Note: operation is paginated, see 'result.cursor' and 'params.cursor'.
18    result => console.log(`Items in folder: ${result.children.length}`),
19    error => console.error(error)
20  );

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": "image/jpeg",
  "originalFileName": "example.jpg",
  "path": {
    "fileName": "image.jpg",
    "fileNameVariablesEnabled": true,
    "folderPath": "/uploads",
    "folderPathVariablesEnabled": true
  },
  "protocol": "1.0",
  "size": 11,
  "tags": [
    "images/profile"
  ]
}

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": [
    "images/profile"
  ]
}

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": "image/jpeg",
    "originalFileName": "example.jpg",
    "path": {
      "fileName": "image.jpg",
      "fileNameVariablesEnabled": true,
      "folderPath": "/uploads",
      "folderPathVariablesEnabled": true
    },
    "protocol": "1.0",
    "size": 11,
    "tags": [
      "images/profile"
    ]
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

UploadApi

Client methods for the File Upload API.

Use the UploadManager instead of calling these methods directly.

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": "image/jpeg",
    "originalFileName": "example.jpg",
    "path": {
      "fileName": "image.jpg",
      "fileNameVariablesEnabled": true,
      "folderPath": "/uploads",
      "folderPathVariablesEnabled": true
    },
    "protocol": "1.0",
    "size": 43182,
    "tags": [
      "images/profile"
    ]
  }
}

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": [
      "images/profile"
    ]
  },
  "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": "image/jpeg",
      "originalFileName": "example.jpg",
      "path": {
        "fileName": "image.jpg",
        "fileNameVariablesEnabled": true,
        "folderPath": "/uploads",
        "folderPathVariablesEnabled": true
      },
      "protocol": "1.0",
      "size": 43182,
      "tags": [
        "images/profile"
      ]
    }
  })
  .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,
  "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,
    "filePath": "/uploads/image.jpg",
    "version": "1"
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

processFile

Processes a file and downloads the result.

Signature

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

Parameters

{
  "accountId": "YOUR_ACCOUNT_ID",
  "artifact": "/example/video/part-a.ts",
  "cache": true,
  "filePath": "/uploads/image.jpg",
  "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,
    "filePath": "/uploads/image.jpg",
    "transformation": "thumbnail",
    "version": "1"
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

getFileDetails

Retrieves the full details 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": [
    "images/profile"
  ]
}

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)
  );

deleteFile

Synchronously deletes a single file.

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

Asynchronously deletes multiple files.

Signature

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

Parameters

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

See details: DeleteFileBatchParams

Result

{
  "jobId": "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": [
                  "thumbnail"
                ]
              }
            },
            "scope": "Children"
          }
        ]
      },
      "storageLayer": {
        "set": true,
        "value": {
          "type": "InternalStorageV2"
        }
      }
    }
  }
}

See details: PutFolderParams

Result

{
  "folderPath": "/uploads",
  "settings": {
    "description": "This is an example folder description.",
    "publicPermissions": [
      {
        "permissions": {
          "file": {
            "downloadFile": [
              "thumbnail"
            ]
          }
        },
        "scope": "Children"
      }
    ],
    "storageLayer": {
      "type": "InternalStorageV2"
    }
  },
  "settingsInherited": {
    "publicPermissions": {
      "folderPath": "/uploads",
      "value": [
        {
          "permissions": {
            "file": {
              "downloadFile": [
                "thumbnail"
              ]
            }
          },
          "scope": "Children"
        }
      ]
    },
    "storageLayer": {
      "folderPath": "/uploads",
      "value": {
        "type": "InternalStorageV1"
      }
    }
  },
  "status": "Deleting",
  "type": "Folder"
}

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": [
                    "thumbnail"
                  ]
                }
              },
              "scope": "Children"
            }
          ]
        },
        "storageLayer": {
          "set": true,
          "value": {
            "type": "InternalStorageV2"
          }
        }
      }
    }
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

getFolderDetails

Gets the settings for this folder. Returns an empty object if none exist.

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": [
              "thumbnail"
            ]
          }
        },
        "scope": "Children"
      }
    ],
    "storageLayer": {
      "type": "InternalStorageV2"
    }
  },
  "settingsInherited": {
    "publicPermissions": {
      "folderPath": "/uploads",
      "value": [
        {
          "permissions": {
            "file": {
              "downloadFile": [
                "thumbnail"
              ]
            }
          },
          "scope": "Children"
        }
      ]
    },
    "storageLayer": {
      "folderPath": "/uploads",
      "value": {
        "type": "InternalStorageV1"
      }
    }
  },
  "status": "Deleting",
  "type": "Folder"
}

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)
  );

listFolderChildren

Lists the children (files and sub-folders) of a folder. Pagination is complete when the response cursor matches the request cursor.

Signature

function listFolderChildren(params: ListFolderChildrenParams): Promise<ListFolderChildrenResponse>

Parameters

{
  "accountId": "YOUR_ACCOUNT_ID",
  "cursor": "aGVsbG8=",
  "folderPath": "/uploads",
  "includeFiles": true,
  "includeFolders": true,
  "limit": 50,
  "traverseVirtualFolders": true
}

See details: ListFolderChildrenParams

Result

{
  "children": [
    {
      "filePath": "/uploads/image.jpg",
      "fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg",
      "lastModified": 1615680311115,
      "size": 43182,
      "type": "File"
    }
  ],
  "cursor": "aGVsbG8=",
  "parent": {
    "folderPath": "/uploads",
    "settings": {
      "description": "This is an example folder description.",
      "publicPermissions": [
        {
          "permissions": {
            "file": {
              "downloadFile": [
                "thumbnail"
              ]
            }
          },
          "scope": "Children"
        }
      ],
      "storageLayer": {
        "type": "InternalStorageV2"
      }
    },
    "status": "Deleting",
    "type": "Folder"
  }
}

See details: ListFolderChildrenResponse

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
  .listFolderChildren({
    "accountId": "YOUR_ACCOUNT_ID",
    "cursor": "aGVsbG8=",
    "folderPath": "/uploads",
    "includeFiles": true,
    "includeFolders": true,
    "limit": 50,
    "traverseVirtualFolders": true
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

deleteFolder

Asynchronously deletes a folder.

Signature

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

Parameters

{
  "accountId": "YOUR_ACCOUNT_ID",
  "deleteFolderRequest": {
    "folderPath": "/uploads",
    "retainFolderSettings": false,
    "scope": "All"
  }
}

See details: DeleteFolderParams

Result

{
  "jobId": "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": {
      "folderPath": "/uploads",
      "retainFolderSettings": false,
      "scope": "All"
    }
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

deleteFolderBatch

Asynchronously deletes multiple folders.

Signature

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

Parameters

{
  "accountId": "YOUR_ACCOUNT_ID",
  "deleteFolderBatchRequest": {
    "folders": [
      {
        "folderPath": "/uploads",
        "retainFolderSettings": false,
        "scope": "All"
      }
    ]
  }
}

See details: DeleteFolderBatchParams

Result

{
  "jobId": "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": [
        {
          "folderPath": "/uploads",
          "retainFolderSettings": false,
          "scope": "All"
        }
      ]
    }
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

JobApi

Client methods for the Job Management API.

getJob

Gets information on a job (e.g. a batch file deletion). Requires a secret_* API key.

Signature

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

Parameters

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

See details: GetJobParams

Result

{
  "accountId": "YOUR_ACCOUNT_ID",
  "attempts": 2,
  "created": 1615680311115,
  "error": {
    "code": "error_code",
    "message": "Error message."
  },
  "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobType": "BatchFileDeletionJob",
  "lastUpdated": 1615680311115,
  "payload": {
    "deletions": [
      "/file/to/delete.jpg"
    ]
  },
  "status": "Cancelled"
}

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": "BatchFileDeletionJob"
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

listRecentJobs

Lists the most recently issued jobs (e.g. batch file deletions, folder deletions, etc.). Requires a secret_* API key.

Signature

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

Parameters

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

See details: ListRecentJobsParams

Result

{
  "items": [
    {
      "accountId": "YOUR_ACCOUNT_ID",
      "attempts": 2,
      "created": 1615680311115,
      "error": {
        "code": "error_code",
        "message": "Error message."
      },
      "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "jobType": "BatchFileDeletionJob",
      "lastUpdated": 1615680311115,
      "payload": {
        "deletions": [
          "/file/to/delete.jpg"
        ]
      },
      "status": "Cancelled"
    }
  ]
}

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": [
      "BatchFileDeletionJob"
    ]
  })
  .then(
    result => console.log(result),
    error => console.error(error)
  );

cancelJob

Cancels an in-progress job. Requires a secret_* API key.

Signature

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

Parameters

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

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": "BatchFileDeletionJob"
  })
  .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:

Documentation

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

beginMultipartUpload

completeUploadPart

getUploadPart

listUploadParts

FileApi

downloadFile

processFile

getFileDetails

deleteFile

deleteFileBatch

FolderApi

putFolder

getFolderDetails

listFolderChildren

deleteFolder

deleteFolderBatch

JobApi

getJob

listRecentJobs

cancelJob

Upload Node.js SDK

You are using an outdated browser.