Skip to main content

Cloud storage

uploadFile​

1. API Description​

API feature: upload files

API Declaration:

2.x version

uploadFile(options)

1.x version

uploadFile(localPath: string, cloudPath: string)

Note: v2.x is incompatible with v1.x.

2. Input Parameters​

FieldRequiredTypeDescription
localPathYesStringLocal file path. It is recommended to pass an absolute path.
cloudPathRequiredStringCloud file path: dir/data.txt
onProgressRequiredFunctionUpload progress callback function

Note: When localPath is a folder, the SDK will attempt to find a file with the same name as the file in cloudPath within this folder (first-level directory, no deep traversal). For example, if cloudPath is dir/data.txt, it will look for 'data.txt'.

3. Return Results​

N/A

4. Sample Code​

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.uploadFile({
    localPath: path.resolve("./data.txt"),
    cloudPath: "files/data.txt",
    onProgress: (data) => {},
  });
}

test();

uploadDirectory​

1. API Description​

API feature: Uploading folders

API Declaration:

2.x version

uploadDirectory(options)

1.x version

uploadDirectory(source: string, cloudPath: string)

Note: v2.x is incompatible with v1.x.

This API traverses all files in the target folder and uploads them while preserving the folder structure.

2. Input Parameters​

FieldRequiredTypeDescription
localPathRequiredStringLocal folder path
cloudPathRequiredStringCloud folder path
onProgressRequiredFunctionUpload progress callback function

3. Return Results​

N/A

4. Sample Code​

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.uploadDirectory({
    localPath: path.resolve("./files"),
    cloudPath: "",
    onProgress: (data) => {},
  });
}

test();

downloadFile​

1. API Description​

API feature: download files

API Declaration:

2.x version

downloadFile(options)

1.x version

downloadFile(cloudPath: string, localPath)

Note: v2.x is incompatible with v1.x.

2. Input Parameters​

FieldRequiredTypeDescription
cloudPathRequiredStringCloud file path: dir/data.txt
localPathRequiredStringLocal file storage path; the file name must be specified

3. Return Results​

None (undefined)

4. Sample Code​

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.downloadFile({
    cloudPath: "files/data.txt",
    localPath: path.resolve("./data.txt"),
  });
}

test();

downloadDirectory​

1. API Description​

API feature: download folder

API Declaration:

2.x version

downloadDirectory(options)

1.x version

downloadDirectory(cloudPath: string, localPath: string)

Note: v2.x is incompatible with v1.x.

2. Input Parameters​

FieldRequiredTypeDescription
cloudPathRequiredStringCloud folder
localPathRequiredStringLocal file storage path; the file name must be specified

3. Return Results​

N/A

4. Sample Code​

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.downloadDirectory({
    cloudPath: "files/music",
    localPath: path.resolve("./music"),
  });
}

test();

NOTE:

  • This operation traverses all files in the folder. If the number of files is too large, it may cause the execution to fail.
  • When cloudPath does not exist, the SDK will not download the file and will not throw an error.

listDirectoryFiles​

1. API Description​

API feature: List all files in the folder

API declaration: listDirectoryFiles(cloudPath: string): Promise<IListFileInfo[]>

2. Input Parameters​

FieldRequiredTypeDescription
cloudPathRequiredStringCloud folder path: dir/data/

3. Return Results​

FieldRequiredTypeDescription
-RequiredArray<FileItem>File array

FileItem​

FieldTypeDescription
KeyStringObject Key
LastModifiedStringLast modified time of the object, in ISO8601 format, such as 2019-05-24T10:56:40Z date
ETagStringThe entity tag (Entity Tag) of the object, which is an information tag that identifies the content of the object when it is created and can be used to check whether the content of the object has changed
SizeStringObject size, unit: bytes
OwnerStringObject owner information
StorageClassStringCOS storage type: Standard Storage STANDARD

4. Sample Code​

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const res1 = await storage.listDirectoryFiles("dir/data");

  const res2 = await storage.listDirectoryFiles("dir/data", 20);

  const res3 = await storage.listDirectoryFiles("dir/data", 20, "dir/dat");

  for (let item in res1) {
    console.log(item);
  }
}
test();

getFileInfo​

1. API Description​

API feature: Obtain file information

API declaration: getFileInfo(cloudPath: string): Promise<IFileInfo>

2. Input Parameters​

FieldRequiredTypeDescription
cloudPathRequiredStringCloud file path dir/data.txt

3. Return Results​

FieldRequiredTypeDescription
SizeRequiredStringFile size, unit: KB
TypeRequiredStringFile type
DateRequiredStringModification time
ETagYesStringEntity tag of the object (Entity Tag)

4. Sample Code​

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const info = await storage.getFileInfo("files/data.txt");
  console.log(info);
}

test();

deleteFile​

1. API Description​

API feature: Batch delete files

API declaration: deleteFile(cloudPathList: string[])

2. Input Parameters​

FieldRequiredTypeDescription
cloudPathListRequiredArray<String>String array consisting of cloud file paths ['dir/data.txt']

3. Return Results​

N/A

4. Sample Code​

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.deleteFile(["files/data.txt"]);
}

test();

deleteDirectory​

1. API Description​

API feature: Delete a folder

API declaration: deleteDirectory(cloudPath: string)

2. Input Parameters​

FieldRequiredTypeDescription
cloudPathRequiredStringCloud folder path

Note: When cloudPath does not exist, the SDK will not throw an error.

3. Return Results​

N/A

4. Sample Code​

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.deleteDirectory("files/");
}

test();

getTemporaryUrl​

1. API Description​

API feature: Obtain a temporary download link for a file

API declaration: getTemporaryUrl(fileList: (string | TempUrlInfo)[]):Promise<Array.<FileUrlItem>>

2. Input Parameters​

FieldRequiredTypeDescription
fileListRequiredString or Array.<TempUrlInfo>Array of cloud file paths or Array of TempUrlInfo

TempUrlInfo​

FieldRequiredTypeDescription
cloudPathRequiredStringCloud file path
maxAgeRequiredNumberValidity period of the temporary download link, unit: seconds

3. Return Results​

FieldRequiredTypeDescription
-RequiredArray.<FileUrlItem>List of file download URLs

FileUrlItem​

FieldRequiredTypeDescription
fileIdRequiredStringFile Id
urlRequiredStringdownload link

4. Sample Code​

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const urls = await storage.getTemporaryUrl(["files/data.txt"]);

  const urls2 = await storage.getTemporaryUrl([
    {
      cloudPath: "files/data.txt",
      maxAge: 86400,
    },
  ]);

  for (let item in urls) {
    console.log(item.url);
  }
}

test();

getStorageAcl​

1. API Description​

API feature: Obtain file storage permissions

API declaration: getStorageAcl(): Promise<string>

2. Input Parameters​

Empty

3. Return Results​

FieldRequiredTypeDescription
-RequiredStringPermission type

All permission types:

  • READONLY: Readable by all users, writable only by the creator and administrators.
  • PRIVATE: Readable and writable only by the creator and administrators.
  • ADMINWRITE: Readable by all users, writable only by administrators.
  • ADMINONLY: Readable and writable only by administrators

4. Sample Code​

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const acl = await storage.getStorageAcl();
  console.log(acl);
}

test();

setStorageAcl​

1. API Description​

API feature: Set file storage permissions

API declaration: setStorageAcl(acl: string):Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
aclYesStringFile storage permission description

Supported options for acl:

  • READONLY: Readable by all users, writable only by the creator and administrators.
  • PRIVATE: Readable and writable only by the creator and administrators.
  • ADMINWRITE: Readable by all users, writable only by administrators.
  • ADMINONLY: Readable and writable only by administrators

3. Return Results​

FieldRequiredTypeDescription
RequestIdRequiredStringRequest ID

4. Sample Code​

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.setStorageAcl("READONLY");
}

test();

listCurrentDirectory​

1. API Description​

API feature: List files and subdirectories in the specified directory (non-recursive, current level only)

API declaration: app.storage.listCurrentDirectory(dirPath?: string): Promise<Object>

version tip

This API has been supported since v5.0.0.

2. Input Parameters​

FieldRequiredTypeDescription
dirPathOptionalStringCloud directory path. If not provided, the root directory is listed; no trailing / required.

3. Return Results​

FieldTypeDescription
filesIListFileInfo[]File list at the current level
directoriesString[]List of subdirectory names at the current level

4. Sample Code​

const CloudBase = require('@cloudbase/manager-node')
const app = new CloudBase({ secretId: 'Your SecretId', secretKey: 'Your SecretKey', envId: 'your-env-id' })

async function test() {
  const { files, directories } = await app.storage.listCurrentDirectory('images')
  console.log('File:', files)
  console.log('Subdirectory:', directories)
}

test()

copyFile​

1. API Description​

API feature: copies a single cloud file to a new path

API declaration: app.storage.copyFile(options: ICopyOptions): Promise<ICopyResult>

version tip

This API has been supported since v5.0.0.

2. Input Parameters​

ICopyOptions

FieldRequiredTypeDescription
sourcePathRequiredStringSource file cloud path, for example images/a.jpg
destPathRequiredStringTarget file cloud path, for example backup/a.jpg
forceNoBooleanwhether to forcibly overwrite existing target files, defaults to false
skipExistingNoBooleanSkip if target already exists (without error), default false

3. Return Results​

ICopyResult

FieldTypeDescription
successBooleanwhether the operation was successful
sourcePathStringSource path
destPathStringTarget path
sizeNumberFile size (bytes)
statusStringStatus: copied / skipped / failed
errorStringError message when the operation fails

4. Sample Code​

async function test() {
  const result = await app.storage.copyFile({
    sourcePath: 'images/logo.png',
    destPath: 'backup/logo.png',
    force: true
  })
  console.log('Copy result:', result)
}

test()

copyDirectory​

1. API Description​

API feature: recursively copies cloud directories to a new path, supports glob filtering and concurrency control

API declaration: app.storage.copyDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>

version tip

This API has been supported since v5.0.0.

2. Input Parameters​

ICopyDirectoryOptions (extends ICopyOptions)

FieldRequiredTypeDescription
sourcePathRequiredStringCloud path of the source directory
destPathRequiredStringCloud path of the target directory
forceNoBooleanwhether to forcibly overwrite existing files, defaults to false
skipExistingNoBooleanSkip if target already exists, default false
includeNoString | String[]Include pattern (glob format)
excludeNoString | String[]Exclude pattern (glob format)
parallelNoNumberConcurrency, default 20
onProgressNoFunctionProgress callback (info: ICopyProgress) => void

ICopyProgress

FieldTypeDescription
copiedNumberCopied count
skippedNumberSkipped count
totalNumberTotal file count
currentFileStringFile being processed

3. Return Results​

Promise<ICopyResult[]> — An array of copy results for each file, with the same structure as the return value of copyFile.

4. Sample Code​

async function test() {
  const results = await app.storage.copyDirectory({
    sourcePath: 'src-dir/',
    destPath: 'dest-dir/',
    include: ['**/*.jpg', '**/*.png'],
    force: true,
    onProgress: ({ copied, total }) => console.log(`${copied}/${total}`)
  })
  console.log('Directory copy completed, total:', results.length, 'files')
}

test()

moveFile​

1. API Description​

API feature: moves a single cloud file to a new path (copies and then deletes the source file)

API declaration: app.storage.moveFile(options: ICopyOptions): Promise<ICopyResult>

version tip

This API has been supported since v5.0.0.

2. Input Parameters​

Same as copyFile, with exactly the same parameter structure.

ICopyOptions

FieldRequiredTypeDescription
sourcePathRequiredStringCloud path of the source file
destPathRequiredStringCloud path of the target file
forceNoBooleanwhether to forcibly overwrite existing target files, defaults to false
skipExistingNoBooleanSkip if target already exists, default false

3. Return Results​

Same as copyFile, returns ICopyResult.

4. Sample Code​

async function test() {
  const result = await app.storage.moveFile({
    sourcePath: 'temp/upload.jpg',
    destPath: 'images/upload.jpg',
    force: true
  })
  console.log('Move result:', result.status)
}

test()

moveDirectory​

1. API Description​

API feature: recursively move a cloud directory to a new path (copy and then delete the source directory)

API declaration: app.storage.moveDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>

version tip

This API has been supported since v5.0.0.

2. Input Parameters​

Same as copyDirectory, with exactly the same parameter structure.

3. Return Results​

Same as copyDirectory, returns ICopyResult[].

4. Sample Code​

async function test() {
  const results = await app.storage.moveDirectory({
    sourcePath: 'old-dir/',
    destPath: 'new-dir/',
    force: true
  })
  console.log('Directory move completed, total:', results.length, 'files')
}

test()

searchFiles​

1. API Description​

API feature: Search for files in a specified directory using a glob pattern or regular expression.

API declaration: app.storage.searchFiles(options: ISearchOptions): Promise<ISearchResult[]>

version tip

This API has been supported since v5.0.0.

2. Input Parameters​

ISearchOptions

FieldRequiredTypeDescription
patternRequiredStringSearch pattern, supporting glob or regular expression strings
pathOptionalStringSearch directory path. If not specified, the root directory is searched.
isRegexNoBooleanWhen true, parses pattern as a regular expression; default false
fileTypeOptionalStringFile type filtering, e.g., jpg, png
limitOptionalNumberMaximum number of results to return, default 100
includeDetailsNoBooleanwhether to include file size and modification time, default false

3. Return Results​

ISearchResult[]

FieldTypeDescription
keyStringCloud file path
typeStringType: file / directory
sizeNumberFile size (bytes), only valid for files
lastModifiedStringLast modified time (in ISO format), only valid for files

4. Sample Code​

async function test() {
  const results = await app.storage.searchFiles({
    pattern: '**/*.jpg',
    path: 'images',
    limit: 50,
    includeDetails: true
  })
  results.forEach(f => console.log(f.key, f.size))
}

test()

PostgreSQL Environment​

Version Note

The following APIs target CloudBase environments using the PostgreSQL architecture, and are implemented on top of the CloudBase Storage HTTP API. They are available since @cloudbase/manager-node@5.4.0.

  • These APIs target a different architecture from the COS-SDK based ones above (uploadFile / downloadFile / listDirectoryFiles, etc.) and must not be mixed.

  • Every API requires an accessToken (Bearer Token). It can be one of:

    • access_token: end-user login token
    • apiKey: server-side admin token (a long-lived JWT, created by env.createApiKey)
    • publishableKey: anonymous frontend token

    ⚠️ apiKey MUST NEVER be used on the client side.

  • Every API accepts an optional envId field that overrides the current environment ID; if omitted, the envId provided when initializing the manager is used.

Common Error Shape​

When a PG Storage HTTP API call fails, a CloudBaseError is thrown with the following fields:

FieldDescription
messageDescription in the form <code>: <message>
codeThe server-returned Code; falls back to HTTP_<status> if not parseable
requestIdServer-returned RequestId (useful for support tickets)

uploadObject​

1. Description​

Uploads an object via the HTTP API as a binary stream.

Signature: app.storage.uploadObject(options): Promise<IUploadObjectHttpResult>

2. Input Parameters​

IUploadObjectHttpOptions

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name; supports paths, e.g. folder/file.png
localPathNoStringAbsolute or relative path to a local file (use either this or body)
bodyNoBuffer / NodeJS.ReadableStreamFile content (use either this or localPath)
contentTypeNoStringMIME type; if omitted, inferred in order of extension → magic bytes
contentLengthNoNumberFile size in bytes; auto-inferred from localPath or Buffer if omitted
cacheControlNoNumber / StringA number is converted to max-age=<value>; a string is used as the Cache-Control header verbatim
metadataNoObjectCustom metadata; will be Base64(JSON) encoded into the X-Metadata header
xRobotsTagNoStringX-Robots-Tag header
upsertNoBooleanWhen using POST, allows overwriting (x-upsert: true); defaults to false
usePutNoBooleanUse the PUT method, equivalent to forcing overwrite; defaults to false
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

Constraint: maximum single-file size is 100 MB; exceeding it throws FileSizeLimitExceeded.

3. Return Result​

IUploadObjectHttpResult

FieldTypeDescription
IdStringObject ID
KeyStringObject Key (including path)

4. Sample Code​

const res = await app.storage.uploadObject({
  bucketId: 'my-bucket',
  objectName: 'images/avatar.png',
  localPath: './avatar.png',
  cacheControl: 3600,
  metadata: { source: 'manager-node' },
  upsert: true,
  accessToken: '<your-access-token>'
})
console.log(res.Id, res.Key)

deleteObject​

1. Description​

Deletes a single object.

Signature: app.storage.deleteObject(options): Promise<IDeleteObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

FieldTypeDescription
messageStringGateway message, e.g. Successfully deleted

deleteObjects​

1. Description​

Deletes objects in batch; up to 20 objects per call.

Signature: app.storage.deleteObjects(options): Promise<IDeletedObjectInfo[]>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
prefixesYesString[]List of object names to delete, 1 to 20. Despite the field name prefixes, items are matched as full object names (exact match), NOT as prefixes.
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

IDeletedObjectInfo[]. Each item contains fields like name / bucket_id / owner_id. Non-existent objects are silently skipped by the server (they don't appear in the returned array).

4. Sample Code​

const deleted = await app.storage.deleteObjects({
  bucketId: 'my-bucket',
  prefixes: ['test/a.txt', 'test/b.txt'],
  accessToken: '<your-access-token>'
})
console.log(deleted.map(d => d.name))

copyObject​

1. Description​

Copies an object.

Signature: app.storage.copyObject(options): Promise<ICopyObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringSource bucket ID
sourceKeyYesStringSource object name
destinationKeyYesStringDestination object name
destinationBucketNoStringDestination bucket ID; defaults to the source bucket
metadataNoObjectSystem metadata; takes effect only when copyMetadata=false, merged with the source metadata. COS only recognizes cacheControl / mimetype / contentType
userMetadataNoObjectUser custom metadata; takes effect only when copyMetadata=false and fully replaces the destination user_metadata (passed via x-metadata Base64(JSON) header)
copyMetadataNoBooleanWhether to copy the source object's metadata; defaults to true. When true, metadata / userMetadata are ignored
upsertNoBooleanAllow overwriting an existing object at the destination
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

ICopyObjectHttpResult: contains Id / Key / name / bucket_id / owner_id / version / created_at / updated_at / last_accessed_at / metadata / user_metadata, etc.

moveObject​

1. Description​

Moves an object; the server performs copy + delete source atomically.

Signature: app.storage.moveObject(options): Promise<IMoveObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringSource bucket ID
sourceKeyYesStringSource object name
destinationKeyYesStringDestination object name
destinationBucketNoStringDestination bucket ID; defaults to the source bucket
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

FieldTypeDescription
messageStringServer message, e.g. Successfully moved
IdStringDestination object ID
KeyStringDestination object Key

listObjects​

1. Description​

Lists objects under a bucket; supports prefix filtering, pagination and sorting.

Signature: app.storage.listObjects(options): Promise<IListObjectsHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
prefixNoStringPath prefix
limitNoNumberPage size, 1-1000
cursorNoStringPagination cursor (the previous response's nextCursor)
withDelimiterNoBooleanWhether to use / as the folder delimiter
sortByNoObject{ column?: 'name' | 'created_at' | 'updated_at', order?: 'asc' | 'desc' }
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

IListObjectsHttpResult

FieldTypeDescription
foldersIListObjectsFolderItem[]Folder entries
objectsIListObjectsObjectItem[]Object entries (with name / id / metadata / created_at / updated_at, etc.)
hasNextBooleanWhether there is a next page
nextCursorStringCursor for the next page
nextCursorKeyStringKey for the next-page cursor

signObject​

1. Description​

Generates a signed download URL for a single object.

Signature: app.storage.signObject(options): Promise<ISignObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name
expiresInYesNumberExpiration in seconds; >= 1
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

FieldTypeDescription
signedURLStringSigned download URL

signObjects​

1. Description​

Generates signed download URLs for multiple objects in batch; up to 500 objects per call.

Signature: app.storage.signObjects(options): Promise<ISignObjectsHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
pathsYesString[]List of object names, 1-500
expiresInYesNumberExpiration in seconds; >= 1
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

ISignedObjectItem[]

FieldTypeDescription
pathStringObject name
signedURLString / nullSigned URL; null on failure
errorString / nullPer-item error message; null on success

signUploadObject​

1. Description​

Generates a signed upload URL for an object.

Signature: app.storage.signUploadObject(options): Promise<ISignUploadObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name
upsertNoBooleanWhen true, allows overwrite (x-upsert: true); defaults to false
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

FieldTypeDescription
urlStringSigned upload URL
tokenStringSignature token; used together with uploadObjectBySign

uploadObjectBySign​

1. Description​

Uploads an object using a signed URL; does NOT require the Authorization header.

Signature: app.storage.uploadObjectBySign(options): Promise<IUploadObjectBySignHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name
tokenYesStringThe signature token returned by signUploadObject
localPathNoStringLocal file path (use either this or body)
bodyNoBuffer / NodeJS.ReadableStreamFile content
contentTypeNoStringIf omitted, inferred from extension → magic bytes
contentLengthNoNumberAuto-inferred when omitted
envIdNoStringOverrides the current envId

3. Return Result​

FieldTypeDescription
KeyStringThe object Key after a successful upload

downloadAuthenticatedObject​

1. Description​

Downloads an authenticated object; always sends the Authorization header.

Signature: app.storage.downloadAuthenticatedObject(options): Promise<IDownloadObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name
accessTokenYesStringBearer Token
methodNo'GET' / 'HEAD'HTTP method; defaults to GET
downloadNoStringTriggers a browser download; the value is used as the download filename
ifNoneMatchNoStringIf-None-Match header
ifModifiedSinceNoStringIf-Modified-Since header
rangeNoStringRange header (resumable downloads)
envIdNoStringOverrides the current envId

3. Return Result​

IDownloadObjectHttpResult

FieldTypeDescription
statusNumberHTTP status code (200 / 206 / 304, etc.)
headersObjectResponse headers (lowercase keys)
bodyNodeJS.ReadableStream / nullReadable stream for GET; null for HEAD

4. Sample Code​

import fs from 'fs'

const { status, body } = await app.storage.downloadAuthenticatedObject({
  bucketId: 'my-bucket',
  objectName: 'images/avatar.png',
  accessToken: '<your-access-token>'
})
if (body) body.pipe(fs.createWriteStream('./avatar.png'))

downloadObject​

1. Description​

Downloads an object; accessToken is optional. When omitted, only public buckets are accessible.

Signature: app.storage.downloadObject(options): Promise<IDownloadObjectHttpResult>

2. Input Parameters​

Same as downloadAuthenticatedObject, except that accessToken is optional.

3. Return Result​

Same as downloadAuthenticatedObject.

downloadPublicObject​

1. Description​

Downloads a public object; no authentication required. The target must be a public bucket.

Signature: app.storage.downloadPublicObject(options): Promise<IDownloadObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID (must be a public bucket)
objectNameYesStringObject name
methodNo'GET' / 'HEAD'Defaults to GET
downloadNoStringTriggers a browser download
envIdNoStringOverrides the current envId

3. Return Result​

Same as downloadAuthenticatedObject.

downloadObjectBySign​

1. Description​

Downloads an object using a signed URL; does not require the Authorization header.

Signature: app.storage.downloadObjectBySign(options): Promise<IDownloadObjectHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name
tokenYesStringSignature token (extracted from the URL returned by signObject / signObjects, or held by the caller)
methodNo'GET' / 'HEAD'Defaults to GET
downloadNoStringTriggers a browser download
envIdNoStringOverrides the current envId

3. Return Result​

Same as downloadAuthenticatedObject.

getObjectInfoAuthenticated​

1. Description​

Gets object metadata (authenticated).

Signature: app.storage.getObjectInfoAuthenticated(options): Promise<IGetObjectInfoHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID
objectNameYesStringObject name
methodNo'GET' / 'HEAD'GET returns JSON; HEAD returns only response headers
accessTokenYesStringBearer Token
envIdNoStringOverrides the current envId

3. Return Result​

IGetObjectInfoHttpResult

FieldTypeDescription
statusNumberHTTP status code
headersObjectResponse headers (lowercase keys)
bodyIObjectInfoHttpPayload / nullObject metadata for GET; null for HEAD

IObjectInfoHttpPayload: id / name / version / bucket_id / size / content_type / cache_control / etag / metadata / last_modified / created_at.

getObjectInfoPublic​

1. Description​

Gets metadata of a public object; no authentication required. The target must be a public bucket. Only GET is supported.

Signature: app.storage.getObjectInfoPublic(options): Promise<IGetObjectInfoHttpResult>

2. Input Parameters​

FieldRequiredTypeDescription
bucketIdYesStringBucket ID (must be a public bucket)
objectNameYesStringObject name
envIdNoStringOverrides the current envId

3. Return Result​

Same as getObjectInfoAuthenticated; body is always an IObjectInfoHttpPayload.