The Storage service allows you to manage your project files. Using the Storage service, you can upload, view, download, and query all your project files.
Files are managed using buckets. Storage buckets are similar to Collections we have in our Databases service. The difference is, buckets also provide more power to decide what kinds of files, what sizes you want to allow in that bucket, whether or not to encrypt the files, scan with antivirus and more.
Using Appwrite permissions architecture, you can assign read or write access to each bucket or file in your project for either a specific user, team, user role, or even grant it with public access (any
). You can learn more about how Appwrite handles permissions and access control.
The preview endpoint allows you to generate preview images for your files. Using the preview endpoint, you can also manipulate the resulting image so that it will fit perfectly inside your app in terms of dimensions, file size, and style. The preview endpoint also allows you to change the resulting image file format for better compression or image quality for better delivery over the network.
https://cloud.appwrite.io/v1
List buckets
Get a list of all the storage buckets. You can use the query params to filter your results.
Request
queries Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: enabled, name, fileSecurity, maximumFileSize, encryption, antivirus
search Search term to filter your list results. Max length: 256 chars.
Response
200
GET /storage/buckets
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.listBuckets(
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Create bucket
Create a new storage bucket.
Request
bucketId requiredUnique Id. Choose your own unique ID or pass the string
ID.unique()
to auto generate it. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.name requiredBucket name
permissions An array of permission strings. By default no user is granted with any permissions. Learn more about permissions.
fileSecurity Enables configuring permissions for individual file. A user needs one of file or bucket level permissions to access a file. Learn more about permissions.
enabled Is bucket enabled?
maximumFileSize Maximum file size allowed in bytes. Maximum allowed value is 30MB. For self-hosted setups you can change the max limit by changing the
_APP_STORAGE_LIMIT
environment variable. Learn more about storage environment variablesallowedFileExtensions Allowed file extensions. Maximum of 100 extensions are allowed, each 64 characters long.
compression Compression algorithm choosen for compression. Can be one of none, gzip, or zstd, For file size above 20MB compression is skipped even if it's enabled
encryption Is encryption enabled? For file size above 20MB encryption is skipped even if it's enabled
antivirus Is virus scanning enabled? For file size above 20MB AntiVirus scanning is skipped even if it's enabled
Response
201
POST /storage/buckets
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.createBucket(
bucketId = "[BUCKET_ID]",
name = "[NAME]",
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Get Bucket
Get a storage bucket by its unique ID. This endpoint response returns a JSON object with the storage bucket metadata.
Request
bucketId requiredBucket unique ID.
Response
200
GET /storage/buckets/{bucketId}
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.getBucket(
bucketId = "[BUCKET_ID]"
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Update Bucket
Update a storage bucket by its unique ID.
Request
bucketId requiredBucket unique ID.
name requiredBucket name
permissions An array of permission strings. By default the current permissions are inherited. Learn more about permissions.
fileSecurity Enables configuring permissions for individual file. A user needs one of file or bucket level permissions to access a file. Learn more about permissions.
enabled Is bucket enabled?
maximumFileSize Maximum file size allowed in bytes. Maximum allowed value is 30MB. For self hosted version you can change the limit by changing _APP_STORAGE_LIMIT environment variable. Learn more about storage environment variables
allowedFileExtensions Allowed file extensions. Maximum of 100 extensions are allowed, each 64 characters long.
compression Compression algorithm choosen for compression. Can be one of none, gzip, or zstd, For file size above 20MB compression is skipped even if it's enabled
encryption Is encryption enabled? For file size above 20MB encryption is skipped even if it's enabled
antivirus Is virus scanning enabled? For file size above 20MB AntiVirus scanning is skipped even if it's enabled
Response
200
PUT /storage/buckets/{bucketId}
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.updateBucket(
bucketId = "[BUCKET_ID]",
name = "[NAME]",
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Delete Bucket
Delete a storage bucket by its unique ID.
Request
bucketId requiredBucket unique ID.
Response
204
DELETE /storage/buckets/{bucketId}
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.deleteBucket(
bucketId = "[BUCKET_ID]"
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
List Files
Get a list of all the user files. You can use the query params to filter your results.
Request
bucketId requiredStorage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
queries Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, signature, mimeType, sizeOriginal, chunksTotal, chunksUploaded
search Search term to filter your list results. Max length: 256 chars.
Response
200
GET /storage/buckets/{bucketId}/files
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.listFiles(
bucketId = "[BUCKET_ID]",
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Create File
Create a new file. Before using this route, you should create a new bucket resource using either a server integration API or directly from your Appwrite console.
Larger files should be uploaded using multiple requests with the content-range header to send a partial request with a maximum supported chunk of 5MB
. The content-range
header values should always be in bytes.
When the first request is sent, the server will return the File object, and the subsequent part request must include the file's id in x-appwrite-id
header to allow the server to know that the partial upload is for the existing file and not for a new one.
If you're creating a new file using one of the Appwrite SDKs, all the chunking logic will be managed by the SDK internally.
Request
bucketId requiredStorage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
fileId requiredFile ID. Choose your own unique ID or pass the string
ID.unique()
to auto generate it. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.file requiredBinary file.
permissions An array of permission strings. By default the current user is granted with all permissions. Learn more about permissions.
Response
201
Rate limits
This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with
setSession
, these rate limits will still apply. Learn more about SSR rate limits.The limit is applied for each unique limit key.
Time frameAttemptsKey1 minutes 60 requests IP + METHOD + URL + USER ID
POST /storage/buckets/{bucketId}/files
import io.appwrite.Client
import io.appwrite.models.InputFile
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.createFile(
bucketId = "[BUCKET_ID]",
fileId = "[FILE_ID]",
file = InputFile.fromPath("file.png"),
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Get File
Get a file by its unique ID. This endpoint response returns a JSON object with the file metadata.
Request
bucketId requiredStorage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
fileId requiredFile ID.
Response
200
GET /storage/buckets/{bucketId}/files/{fileId}
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.getFile(
bucketId = "[BUCKET_ID]",
fileId = "[FILE_ID]"
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Update File
Update a file by its unique ID. Only users with write permissions have access to update this resource.
Request
bucketId requiredStorage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
fileId requiredFile unique ID.
permissions An array of permission string. By default the current permissions are inherited. Learn more about permissions.
Response
200
Rate limits
This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with
setSession
, these rate limits will still apply. Learn more about SSR rate limits.The limit is applied for each unique limit key.
Time frameAttemptsKey1 minutes 60 requests IP + METHOD + URL + USER ID
PUT /storage/buckets/{bucketId}/files/{fileId}
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.updateFile(
bucketId = "[BUCKET_ID]",
fileId = "[FILE_ID]",
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Delete File
Delete a file by its unique ID. Only users with write permissions have access to delete this resource.
Request
bucketId requiredStorage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
fileId requiredFile ID.
Response
204
Rate limits
This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with
setSession
, these rate limits will still apply. Learn more about SSR rate limits.The limit is applied for each unique limit key.
Time frameAttemptsKey1 minutes 60 requests IP + METHOD + URL + USER ID
DELETE /storage/buckets/{bucketId}/files/{fileId}
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.deleteFile(
bucketId = "[BUCKET_ID]",
fileId = "[FILE_ID]"
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Get File for Download
Get a file content by its unique ID. The endpoint response return with a 'Content-Disposition: attachment' header that tells the browser to start downloading the file to user downloads directory.
Request
bucketId requiredStorage bucket ID. You can create a new storage bucket using the Storage service server integration.
fileId requiredFile ID.
Response
200
GET /storage/buckets/{bucketId}/files/{fileId}/download
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.getFileDownload(
bucketId = "[BUCKET_ID]",
fileId = "[FILE_ID]"
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Get File Preview
Get a file preview image. Currently, this method supports preview for image files (jpg, png, and gif), other supported formats, like pdf, docs, slides, and spreadsheets, will return the file icon image. You can also pass query string arguments for cutting and resizing your preview image. Preview is supported only for image files smaller than 10MB.
Request
bucketId requiredStorage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
fileId requiredFile ID
width Resize preview image width, Pass an integer between 0 to 4000.
height Resize preview image height, Pass an integer between 0 to 4000.
gravity Image crop gravity. Can be one of center,top-left,top,top-right,left,right,bottom-left,bottom,bottom-right
quality Preview image quality. Pass an integer between 0 to 100. Defaults to 100.
borderWidth Preview image border in pixels. Pass an integer between 0 to 100. Defaults to 0.
borderColor Preview image border color. Use a valid HEX color, no # is needed for prefix.
borderRadius Preview image border radius in pixels. Pass an integer between 0 to 4000.
opacity Preview image opacity. Only works with images having an alpha channel (like png). Pass a number between 0 to 1.
rotation Preview image rotation in degrees. Pass an integer between -360 and 360.
background Preview image background color. Only works with transparent images (png). Use a valid HEX color, no # is needed for prefix.
output Output format type (jpeg, jpg, png, gif and webp).
Response
200
GET /storage/buckets/{bucketId}/files/{fileId}/preview
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.getFilePreview(
bucketId = "[BUCKET_ID]",
fileId = "[FILE_ID]",
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}
Get File for View
Get a file content by its unique ID. This endpoint is similar to the download method but returns with no 'Content-Disposition: attachment' header.
Request
bucketId requiredStorage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
fileId requiredFile ID.
Response
200
GET /storage/buckets/{bucketId}/files/{fileId}/view
import io.appwrite.Client
import io.appwrite.services.Storage
public void main() {
Client client = Client(context)
.setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
.setProject("5df5acd0d48c2") // Your project ID
.setKey("919c2d18fb5d4...a2ae413da83346ad2"); // Your secret API key
Storage storage = new Storage(client);
storage.getFileView(
bucketId = "[BUCKET_ID]",
fileId = "[FILE_ID]"
new Continuation<Response>() {
@NotNull
@Override
public CoroutineContext getContext() {
return EmptyCoroutineContext.INSTANCE;
}
@Override
public void resumeWith(@NotNull Object o) {
String json = "";
try {
if (o instanceof Result.Failure) {
Result.Failure failure = (Result.Failure) o;
throw failure.exception;
} else {
Response response = (Response) o;
}
} catch (Throwable th) {
Log.e("ERROR", th.toString());
}
}
}
);
}