Reference > SDK > File Manager

File Manager

FileManagerSdk: upload, retrieve, and manage files

WHAT YOU'LL LEARN

How to retrieve files and file metadata?
How to upload files using presigned URLs?
How to handle large file uploads with multipart upload?
How to manage file records and tags?

Overview

The FileManagerSdk provides methods for managing files in Webiny File Manager. Access it via sdk.fileManager on a Webiny instance. The SDK handles file metadata operations (create, read, update, delete) and provides helpers for uploading files to S3 using presigned URLs. For large files, multipart upload is supported automatically based on configurable size thresholds.

Reading Files

getFile

Retrieves a single file by ID.

Parameters:

Name	Type	Required	Description
`params`	`GetFileParams`	Yes	Parameters for getting the file
`params.id`	`string`	Yes	ID of the file to retrieve
`params.fields`	`string[]`	Yes	Fields to return (e.g., `["id", "name", "src", "size"]`)

Returns:

Result<FmFile, HttpError | GraphQLError | NetworkError> — Result containing the file data or an error.

Example:

listFiles

Lists files with filtering, sorting, and pagination.

Parameters:

Name	Type	Required	Description
`params`	`ListFilesParams`	Yes	Parameters for listing files
`params.fields`	`string[]`	Yes	Fields to return for each file
`params.search`	`string`	No	Search query to filter files by name
`params.where`	`FmFileListWhereInput`	No	Filter conditions
`params.limit`	`number`	No	Maximum number of files to return
`params.after`	`string`	No	Cursor for pagination
`params.sort`	`FmFileListSorter[]`	No	Sort order (e.g., `["savedOn_DESC"]`)

Returns:

Result<ListFilesResult, HttpError | GraphQLError | NetworkError> — Result containing:

data — Array of FmFile objects
meta — Pagination metadata (cursor, hasMoreItems, totalCount)

Example:

Available sort options:

savedOn_ASC / savedOn_DESC
createdOn_ASC / createdOn_DESC
name_ASC / name_DESC
key_ASC / key_DESC
type_ASC / type_DESC
size_ASC / size_DESC

listTags

Lists all tags used on files with usage counts.

Parameters:

Name	Type	Required	Description
`params`	`ListTagsParams`	No	Parameters for listing tags
`params.where`	`FmTagsListWhereInput`	No	Filter conditions
`params.where.createdBy`	`string`	No	Filter by creator ID
`params.where.tags_startsWith`	`string`	No	Filter tags starting with prefix
`params.where.tags_not_startsWith`	`string`	No	Filter tags not starting with prefix

Returns:

Result<FmTag[], HttpError | GraphQLError | NetworkError> — Result containing array of tags with counts.

Example:

Creating and Updating Files

createFile

Creates a new file record in File Manager. If a file is provided, it uploads to S3 first using presigned POST (small files) or multipart upload (large files).

Parameters:

Name	Type	Required	Description
`params`	`CreateFileParams`	Yes	Parameters for creating the file
`params.data`	`CreateFileData`	Yes	File metadata
`params.data.name`	`string`	Yes*	File name
`params.data.type`	`string`	Yes*	MIME type (e.g., `"image/png"`)
`params.data.size`	`number`	No	File size in bytes
`params.data.key`	`string`	No	Custom S3 key
`params.data.keyPrefix`	`string`	No	Custom key prefix
`params.data.location`	`FmLocationInput`	No	Folder location (`{ folderId: string }`)
`params.data.tags`	`string[]`	No	Tags for the file
`params.file`	`Buffer \\| Blob \\| File`	No	Actual file content to upload
`params.fields`	`string[]`	Yes	Fields to return for created file
`params.onProgress`	`(progress: UploadProgress) => void`	No	Upload progress callback
`params.multiPartThreshold`	`number`	No	Threshold in MB for multipart upload (default: 100)
`params.signal`	`AbortSignal`	No	AbortSignal for cancellation

*Required when file is provided.

Returns:

Result<FmFile, HttpError | GraphQLError | NetworkError> — Result containing the created file data.

Example (metadata only):

Example (with file upload):

createFiles

Creates multiple file records in bulk with concurrent uploads.

Parameters:

Name	Type	Required	Description
`params`	`CreateFilesParams`	Yes	Parameters for creating multiple files
`params.files`	`Array<{ file?, data, fields, onProgress? }>`	Yes	Array of files to create
`params.multiPartThreshold`	`number`	No	Threshold in MB for multipart upload (default: 100)
`params.concurrency`	`number`	No	Number of concurrent uploads (default: 5)
`params.strategy`	`BatchUploadStrategy`	No	`"fail-fast"` or `"continue"` (default: `"fail-fast"`)
`params.signal`	`AbortSignal`	No	AbortSignal for cancellation

Returns:

Result<CreateFilesResult, HttpError | GraphQLError | NetworkError> — Result containing:

successful — Array of successfully created FmFile objects
failed — Array of failed uploads with error details

Example:

updateFile

Updates file metadata (does not re-upload file content).

Parameters:

Name	Type	Required	Description
`params`	`UpdateFileParams`	Yes	Parameters for updating the file
`params.id`	`string`	Yes	ID of the file to update
`params.data`	`UpdateFileData`	Yes	Updated file metadata
`params.data.name`	`string`	No	Updated file name
`params.data.tags`	`string[]`	No	Updated tags
`params.data.location`	`FmLocationInput`	No	Updated folder location
`params.fields`	`string[]`	Yes	Fields to return for updated file

Returns:

Result<FmFile, HttpError | GraphQLError | NetworkError> — Result containing the updated file data.

Example:

deleteFile

Deletes a file record from File Manager.

Parameters:

Name	Type	Required	Description
`params`	`DeleteFileParams`	Yes	Parameters for deleting the file
`params.id`	`string`	Yes	ID of the file to delete

Returns:

Result<boolean, HttpError | GraphQLError | NetworkError> — Result containing true on success.

Example:

Upload Helpers

getPresignedPostPayload

Gets a presigned POST URL for uploading a file directly to S3 from a browser.

Parameters:

Name	Type	Required	Description
`params`	`GetPresignedPostPayloadParams`	Yes	Parameters for getting presigned POST payload
`params.name`	`string`	Yes	File name
`params.type`	`string`	Yes	MIME type
`params.size`	`number`	Yes	File size in bytes
`params.key`	`string`	No	Custom S3 key
`params.keyPrefix`	`string`	No	Custom key prefix

Returns:

Result<PresignedPostPayloadResponse, HttpError | GraphQLError | NetworkError> — Result containing:

data — Presigned POST payload with url and fields
file — File metadata including generated id and key

Example:

getPresignedPostPayloads

Gets presigned POST URLs for multiple files in bulk.

Parameters:

Name	Type	Required	Description
`params`	`GetPresignedPostPayloadsParams`	Yes	Parameters for getting presigned POST payloads
`params.files`	`GetPresignedPostPayloadParams[]`	Yes	Array of file metadata

Returns:

Result<PresignedPostPayloadResponse[], HttpError | GraphQLError | NetworkError> — Result containing array of presigned POST payloads.

Example:

createMultiPartUpload

Initiates a multipart upload for large files.

Parameters:

Name	Type	Required	Description
`params`	`CreateMultiPartUploadParams`	Yes	Parameters for creating multipart upload
`params.data`	`object`	Yes	File metadata (same as `GetPresignedPostPayloadParams`)
`params.data.name`	`string`	Yes	File name
`params.data.type`	`string`	Yes	MIME type
`params.data.size`	`number`	Yes	File size in bytes
`params.data.key`	`string`	No	Custom S3 key
`params.data.keyPrefix`	`string`	No	Custom key prefix
`params.numberOfParts`	`number`	Yes	Number of parts to split file into

Returns:

Result<MultiPartUploadResponse, HttpError | GraphQLError | NetworkError> — Result containing:

uploadId — Upload ID for tracking
file — File metadata including id and key
parts — Array of presigned URLs for each part ({ partNumber, url })

Example:

completeMultiPartUpload

Completes a multipart upload after all parts are uploaded.

Parameters:

Name	Type	Required	Description
`params`	`CompleteMultiPartUploadParams`	Yes	Parameters for completing multipart upload
`params.fileKey`	`string`	Yes	S3 key from `createMultiPartUpload` response
`params.uploadId`	`string`	Yes	Upload ID from `createMultiPartUpload` response

Returns:

Result<boolean, HttpError | GraphQLError | NetworkError> — Result containing true on success.

Example:

Type Reference

FmFile

Represents a file in File Manager.

FmTag

Represents a tag with usage count.

FmListMeta

Pagination metadata for list operations.

FmFile_Metadata

File metadata including image dimensions and EXIF data.

FmFile_AccessControl

File access control settings.

PresignedPostPayloadResponse

Response containing presigned POST data for S3 upload.

MultiPartUploadResponse

Response containing multipart upload data.

UploadProgress

Upload progress callback data.