Buckets

Service for managing UiPath storage Buckets.

Buckets are cloud storage containers that can be used to store and manage files used by automation processes. UiPath Buckets Guide

Buckets with encryption enabled, including those using Customer Managed Keys, are also supported.

Usage¶

Prerequisites: Initialize the SDK first - see Getting Started

import { Buckets } from '@uipath/uipath-typescript/buckets';

const buckets = new Buckets(sdk);
const allBuckets = await buckets.getAll();

Methods¶

deleteFile()¶

Call Signature¶

deleteFile(bucketRef: BucketRef, path: string, options?: BucketDeleteFileOptions): Promise<void>

Deletes a file from a bucket

Parameters¶

Parameter	Type	Description
`bucketRef`	`BucketRef`	Bucket ref (`{ id }` or `{ name }`). `{ name }` triggers an internal name lookup where runtime resource overrides may redirect the target across folders.
`path`	`string`	The full path to the file to delete
`options?`	`BucketDeleteFileOptions`	Folder scoping (`folderId` / `folderKey` / `folderPath`)

Returns¶

Promise<void>

Promise resolving when the file is deleted

Example¶

// By bucket id
await buckets.deleteFile({ id: <bucketId> }, '/folder/file.pdf', { folderId: <folderId> });

// By bucket name
await buckets.deleteFile({ name: 'MyBucket' }, '/folder/file.pdf', { folderPath: 'Shared/Finance' });

Call Signature¶

deleteFile(bucketId: number, path: string, options?: BucketDeleteFileOptions): Promise<void>

Deletes a file from a bucket — numeric bucket id form.

Parameters¶

Parameter	Type	Description
`bucketId`	`number`	The ID of the bucket
`path`	`string`	The full path to the file to delete
`options?`	`BucketDeleteFileOptions`	Folder scoping (`folderId` / `folderKey` / `folderPath`)

Returns¶

Promise<void>

Promise resolving when the file is deleted

Deprecated¶

Use the ref-based form: deleteFile({ id: bucketId }, path, options?). See BucketRef.

getAll()¶

getAll<T>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketGetResponse> : NonPaginatedResponse<BucketGetResponse>>

Gets all buckets across folders with optional filtering

The method returns either: - A NonPaginatedResponse with data and totalCount (when no pagination parameters are provided) - A paginated result with navigation cursors (when any pagination parameter is provided)

Type Parameters¶

Type Parameter	Default type
`T` extends `BucketGetAllOptions`	`BucketGetAllOptions`

Parameters¶

Parameter	Type	Description
`options?`	`T`	Query options including optional folderId and pagination options

Returns¶

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketGetResponse> : NonPaginatedResponse<BucketGetResponse>>

Promise resolving to either an array of buckets NonPaginatedResponse or a PaginatedResponse when pagination options are used. BucketGetResponse

Example¶

// Get all buckets across folders
const allBuckets = await buckets.getAll();

// Get buckets within a specific folder
const folderBuckets = await buckets.getAll({
  folderId: <folderId>
});

// Get buckets with filtering
const filteredBuckets = await buckets.getAll({
  filter: "name eq 'MyBucket'"
});

// First page with pagination
const page1 = await buckets.getAll({ pageSize: 10 });

// Navigate using cursor
if (page1.hasNextPage) {
  const page2 = await buckets.getAll({ cursor: page1.nextCursor });
}

// Jump to specific page
const page5 = await buckets.getAll({
  jumpToPage: 5,
  pageSize: 10
});

getById()¶

getById(bucketId: number, folderId: number, options?: BucketGetByIdOptions): Promise<BucketGetResponse>

Gets a single bucket by ID

Parameters¶

Parameter	Type	Description
`bucketId`	`number`	Bucket ID
`folderId`	`number`	Required folder ID
`options?`	`BucketGetByIdOptions`	Optional query parameters

Returns¶

Promise<BucketGetResponse>

Promise resolving to a bucket definition BucketGetResponse

Example¶

// Get bucket by ID
const bucket = await buckets.getById(<bucketId>, <folderId>);

getByName()¶

getByName(name: string, options?: BucketGetByNameOptions): Promise<BucketGetResponse>

Retrieves a single orchestrator storage bucket by name.

Parameters¶

Parameter	Type	Description
`name`	`string`	Bucket name to search for
`options?`	`BucketGetByNameOptions`	Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional query parameters (`expand`, `select`)

Returns¶

Promise<BucketGetResponse>

Promise resolving to a single bucket BucketGetResponse

Example¶

// By folder ID
await buckets.getByName('MyBucket', { folderId: <folderId> });

// By folder key (GUID)
await buckets.getByName('MyBucket', { folderKey: '<folderKey>' });

// By folder path
await buckets.getByName('MyBucket', { folderPath: '<folderPath>' });

getFileMetaData()¶

Call Signature¶

getFileMetaData<T>(bucketRef: BucketRef, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>

Gets metadata for files in a bucket with optional filtering and pagination.

Folder context can be supplied as folderId, folderKey, or folderPath inside the options.

The method returns either: - A NonPaginatedResponse with items array (when no pagination parameters are provided) - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)

Type Parameters¶

Type Parameter	Default type
`T` extends `BucketGetFileMetaDataWithPaginationOptions`	`BucketGetFileMetaDataWithPaginationOptions`

Parameters¶

Parameter	Type	Description
`bucketRef`	`BucketRef`	Bucket ref (`{ id }` or `{ name }`). `{ name }` triggers an internal name lookup where runtime resource overrides may redirect the target across folders.
`options?`	`T`	Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for filtering and pagination

Returns¶

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>

Promise resolving to either an array of files metadata NonPaginatedResponse or a PaginatedResponse when pagination options are used. BlobItem

Example¶

// By bucket id
const fileMetadata = await buckets.getFileMetaData({ id: <bucketId> }, { folderId: <folderId> });

// By bucket name (folder scoping applies to both the name lookup and the meta-data read)
await buckets.getFileMetaData({ name: 'InvoicesBucket' }, { folderPath: 'Shared/Finance' });

// Filter by prefix
await buckets.getFileMetaData({ id: <bucketId> }, { folderId: <folderId>, prefix: '/folder1' });

// First page with pagination
const page1 = await buckets.getFileMetaData({ id: <bucketId> }, { folderId: <folderId>, pageSize: 10 });

// Navigate using cursor
if (page1.hasNextPage) {
  const page2 = await buckets.getFileMetaData({ id: <bucketId> }, { folderId: <folderId>, cursor: page1.nextCursor });
}

Call Signature¶

getFileMetaData<T>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>

Gets metadata for files in a bucket — numeric bucket id form.

Type Parameters¶

Type Parameter	Default type
`T` extends `BucketGetFileMetaDataWithPaginationOptions`	`BucketGetFileMetaDataWithPaginationOptions`

Parameters¶

Parameter	Type	Description
`bucketId`	`number`	The ID of the bucket to get file metadata from
`options?`	`T`	Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for filtering and pagination

Returns¶

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>

Promise resolving to either an array of files metadata NonPaginatedResponse or a PaginatedResponse when pagination options are used. BlobItem

Deprecated¶

Use the ref-based form: getFileMetaData({ id: bucketId }, options?). See BucketRef.

Call Signature¶

getFileMetaData<T>(bucketId: number, folderId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>

Gets metadata for files in a bucket — positional folderId form.

Type Parameters¶

Type Parameter	Default type
`T` extends `BucketGetFileMetaDataWithPaginationOptions`	`BucketGetFileMetaDataWithPaginationOptions`

Parameters¶

Parameter	Type	Description
`bucketId`	`number`	The ID of the bucket to get file metadata from
`folderId`	`number`	Required folder ID (numeric)
`options?`	`T`	Optional parameters for filtering and pagination

Returns¶

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>

Promise resolving to either an array of files metadata NonPaginatedResponse or a PaginatedResponse when pagination options are used. BlobItem

Deprecated¶

Use the ref-based form: getFileMetaData({ id: bucketId }, { folderId }). See BucketRef.

getFiles()¶

Call Signature¶

getFiles<T>(bucketRef: BucketRef, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketFile> : NonPaginatedResponse<BucketFile>>

Lists all files in a bucket.

Returns a flat, recursive listing of all files in the bucket. Supports regex filtering and filter / orderby / select / expand. BucketFile entries include isDirectory so callers can distinguish folders from files.

The method returns either: - A NonPaginatedResponse with items array (when no pagination parameters are provided) - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)

Type Parameters¶

Type Parameter	Default type
`T` extends `BucketGetFilesOptions`	`BucketGetFilesOptions`

Parameters¶

Parameter	Type	Description
`bucketRef`	`BucketRef`	Bucket ref (`{ id }` or `{ name }`). `{ name }` triggers an internal name lookup where runtime resource overrides may redirect the target across folders.
`options?`	`T`	Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for regex filtering, query options, and pagination BucketGetFilesOptions

Returns¶

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketFile> : NonPaginatedResponse<BucketFile>>

Promise resolving to either an array of files NonPaginatedResponse or a PaginatedResponse when pagination options are used. BucketFile

Example¶

// By bucket id
const files = await buckets.getFiles({ id: <bucketId> }, { folderId: <folderId> });

// By bucket name (folder scoping applies to both the name lookup and the listing)
const filesByName = await buckets.getFiles({ name: 'MyBucket' }, { folderPath: 'Shared/Finance' });

// Filter by regex pattern
const pdfs = await buckets.getFiles({ id: <bucketId> }, {
  folderId: <folderId>,
  fileNameRegex: '.*\\.pdf$'
});

// First page with pagination
const page1 = await buckets.getFiles({ id: <bucketId> }, { folderId: <folderId>, pageSize: 10 });

// Navigate using cursor
if (page1.hasNextPage) {
  const page2 = await buckets.getFiles({ id: <bucketId> }, { folderId: <folderId>, cursor: page1.nextCursor });
}

// Jump to specific page
const page5 = await buckets.getFiles({ id: <bucketId> }, {
  folderId: <folderId>,
  jumpToPage: 5,
  pageSize: 10
});

Call Signature¶

getFiles<T>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketFile> : NonPaginatedResponse<BucketFile>>

Lists all files in a bucket — numeric bucket id form.

Type Parameters¶

Type Parameter	Default type
`T` extends `BucketGetFilesOptions`	`BucketGetFilesOptions`

Parameters¶

Parameter	Type	Description
`bucketId`	`number`	The ID of the bucket
`options?`	`T`	Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for regex filtering, query options, and pagination BucketGetFilesOptions

Returns¶

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketFile> : NonPaginatedResponse<BucketFile>>

Promise resolving to either an array of files NonPaginatedResponse or a PaginatedResponse when pagination options are used. BucketFile

Deprecated¶

Use the ref-based form: getFiles({ id: bucketId }, options?). See BucketRef.

getReadUri()¶

Call Signature¶

getReadUri(bucketRef: BucketRef, path: string, options?: BucketGetReadUriRequestOptions): Promise<BucketGetUriResponse>

Gets a direct download URL for a file in the bucket.

Folder context can be supplied as folderId, folderKey, or folderPath in the options.

Parameters¶

Parameter	Type	Description
`bucketRef`	`BucketRef`	Bucket ref (`{ id }` or `{ name }`). `{ name }` triggers an internal name lookup where runtime resource overrides may redirect the target across folders.
`path`	`string`	The full path to the file
`options?`	`BucketGetReadUriRequestOptions`	Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional `expiryInMinutes`

Returns¶

Promise<BucketGetUriResponse>

Promise resolving to blob file access information BucketGetUriResponse

Example¶

// By bucket id
await buckets.getReadUri({ id: <bucketId> }, '/folder/file.pdf', { folderId: <folderId> });

// By bucket name (folder scoping applies to both the name lookup and the read)
await buckets.getReadUri({ name: 'MyBucket' }, '/folder/file.pdf', { folderPath: 'Shared/Finance' });

Call Signature¶

getReadUri(bucketId: number, path: string, options?: BucketGetReadUriRequestOptions): Promise<BucketGetUriResponse>

Gets a direct download URL for a file in the bucket — numeric bucket id form.

Parameters¶

Parameter	Type	Description
`bucketId`	`number`	The ID of the bucket
`path`	`string`	The full path to the file
`options?`	`BucketGetReadUriRequestOptions`	Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional `expiryInMinutes`

Returns¶

Promise<BucketGetUriResponse>

Promise resolving to blob file access information BucketGetUriResponse

Deprecated¶

Use the ref-based form: getReadUri({ id: bucketId }, path, options?). See BucketRef.

Call Signature¶

getReadUri(options: BucketGetReadUriOptions): Promise<BucketGetUriResponse>

Gets a direct download URL for a file in the bucket — options-only form.

Parameters¶

Parameter	Type	Description
`options`	`BucketGetReadUriOptions`	Contains bucketId, folder scoping (`folderId` / `folderKey` / `folderPath`), file path and optional expiry time

Returns¶

Promise<BucketGetUriResponse>

Promise resolving to blob file access information BucketGetUriResponse

Deprecated¶

Use the ref-based form: getReadUri({ id: bucketId }, path, options?). See BucketRef.

uploadFile()¶

Call Signature¶

uploadFile(bucketRef: BucketRef, path: string, content: Uint8Array<ArrayBuffer> | Blob | File, options?: BucketUploadFileRequestOptions): Promise<BucketUploadResponse>

Uploads a file to a bucket.

Folder context can be supplied as folderId, folderKey, or folderPath in the options.

Parameters¶

Parameter	Type	Description
`bucketRef`	`BucketRef`	Bucket ref (`{ id }` or `{ name }`). `{ name }` triggers an internal name lookup where runtime resource overrides may redirect the target across folders.
`path`	`string`	Path where the file should be stored in the bucket
`content`	`Uint8Array`<`ArrayBuffer`> \| `Blob` \| `File`	File content to upload
`options?`	`BucketUploadFileRequestOptions`	Folder scoping (`folderId` / `folderKey` / `folderPath`)

Returns¶

Promise<BucketUploadResponse>

Promise resolving bucket upload response BucketUploadResponse

Example¶

// By bucket id
const file = new File(['file content'], 'example.txt');
await buckets.uploadFile({ id: <bucketId> }, '/folder/example.txt', file, { folderId: <folderId> });

// By bucket name (folder scoping applies to both the name lookup and the upload)
await buckets.uploadFile({ name: 'MyBucket' }, '/folder/example.txt', file, { folderPath: 'Shared/Finance' });

// In Node env with Uint8Array or Buffer
const content = new TextEncoder().encode('file content');
await buckets.uploadFile({ id: <bucketId> }, '/folder/example.txt', content, { folderId: <folderId> });

Call Signature¶

uploadFile(bucketId: number, path: string, content: Uint8Array<ArrayBuffer> | Blob | File, options?: BucketUploadFileRequestOptions): Promise<BucketUploadResponse>

Uploads a file to a bucket — numeric bucket id form.

Parameters¶

Parameter	Type	Description
`bucketId`	`number`	The ID of the bucket
`path`	`string`	Path where the file should be stored in the bucket
`content`	`Uint8Array`<`ArrayBuffer`> \| `Blob` \| `File`	File content to upload
`options?`	`BucketUploadFileRequestOptions`	Folder scoping (`folderId` / `folderKey` / `folderPath`)

Returns¶

Promise<BucketUploadResponse>

Promise resolving bucket upload response BucketUploadResponse

Deprecated¶

Use the ref-based form: uploadFile({ id: bucketId }, path, content, options?). See BucketRef.

Call Signature¶

uploadFile(options: BucketUploadFileOptions): Promise<BucketUploadResponse>

Uploads a file to a bucket — options-only form.

Parameters¶

Parameter	Type	Description
`options`	`BucketUploadFileOptions`	Options for file upload including bucket ID, folder scoping (`folderId` / `folderKey` / `folderPath`), path, and content

Returns¶

Promise<BucketUploadResponse>

Promise resolving bucket upload response BucketUploadResponse

Deprecated¶

Use the ref-based form: uploadFile({ id: bucketId }, path, content, options?). See BucketRef.