Skip to main content


Everything that you store in your app storage must be contained in a bucket. Buckets are the basic containers that hold your application data (i.e., files).

Upload file

You can upload a file to an existing bucket by calling the upload method. If there already exists a file with the same name in destination bucket and if upsert is set to true in the file upload options then it overwrites the exsiting file, otherwise returns an error.

// Uploads a file to the profiles-images bucket
let storageName = "default";
let bucketName = "profiles-images";
// Get the file data
const fileToUpload =[0];
const result = await
.upload(, fileToUpload, { isPublic: true, upsert: true });

// If you would like to have a progress indicator during file upload
// you can also provide a callback function with `onProgress` property
const result = await agnost
.upload(, fileToUpload, {
isPublic: true,
upsert: true,
onProgress: (uploaded, total, percent) =>
console.log(`progress: ${uploaded}/${total} ${percent}`),
Example response
"data": {
"id": "fl-234e3rwrwr",
"bucketId": "bck-o5nnyhs19dgw",
"storageId": "str-o0dlitj2x5id",
"path": "Booby.png",
"size": 212233,
"mimeType": "image/png",
"isPublic": true,
"uploadedAt": "2022-03-20T15:01:41.993Z",
"updatedAt": "2022-03-20T15:01:41.993Z",
"userId": "611a45f9f3e7ec001950175f",
"tags": {
"size": "large"
"errors": null

After uploading your files to your storage and if the uploaded files are marked as public meaning that they can be accessed publicly, you can get their contents using the following endpoints which are by default included in your app version's API server:

  1. Using the id of the uploaded file. your API server base URL/object/uploaded file id

Assuming that your API server base URL is "" and the uploaded file id is "fl-234e3rwrwr", you can access your file from the following public link:

  1. Using storage, bucket and file name your API server base URL/object/storage name/bucket name/file path (name)

Assuming that your API server base URL is "", your storage name is "default", you bucket name is "profiles-images" and your uploaded file path (name) is "Booby.png", you can access your file from the following public link:

In both of the above options, if you would like to get the uploaded file as an attachment then just add attachment=true query string parameter to the the file's public link.


Here you can find parameters for the upload method.



Data type



1fileNamestringYesThe name of the file e.g., rooby-avatar.jpg
2fileBodyanyYesThe body of the file that will be stored in the bucket
3optionsFileUploadOptionsNoPrivacy setting of the file, tags of the file and whether to upsert the file if file already exists.
If isPublic is not specified, defaults to the bucket's privacy setting. If upsert is set to true (defaults to false), then overwrites the existing file or creates a new file.

If onProgress callback function is defined in FileUploadOptions, it periodically calls this function to inform about upload progress.

Once you upload a file to bucket, it is stored in the staging area for a few seconds for internal processing. That means that you might not be able to access the file for a few seconds after it is uploaded.


File Upload Options

You can define the options for the file upload by using the FileUploadOptions. It defines the available options that can be set during file upload.



Data type


2isPublicbooleanSpecifies whether file is publicy accessible or not. Defaults to the bucket's privacy setting if not specified.
3upsertbooleanSpecifies whether to create a new file or overwrite an existing file. Defaults to false.
4onProgresscallback functionCallback function to call during file upload to get upload progress.
1. uploaded number Total bytes uploaded
2. total number Total size of file in bytes
3. percent number Percent uploaded (an integer between 0-100), basicly uploaded/total rounded to the nearest integer
5tagsstring arrayKey-value pairs that will be added to the file metadata.

For the moment, onProgress callback function can only be used in clients where XMLHttpRequest object is available (e.g., browsers).