Object Storage API
Bucket and file management: bucket creation and policy configuration, file upload (including resumable chunked upload for large files), metadata and permission maintenance, download/preview/inline viewing. For file short-term access tokens see file-tokens; for the two-layer bucket/file permission semantics see permissions.
Service and resource boundaries
The Object Storage API (/v1/storage/*) manages the full lifecycle of storage buckets (Bucket, such as the knowledge base source file bucket kb_enterprise_docs and the agent multimedia bucket agent_multimedia_bucket in the showcase project) and files (File) within a project: it supports maximum single-file size limits, extension whitelists, Gzip/Zstd compression, encryption at rest, ClamAV virus scanning, 5MB resumable chunked upload, online image cropping/format conversion preview (/preview), and integrates seamlessly with knowledge base document ingestion and Memory multimodal parsing.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/storage.Resources:
bucket(bucket,{bucketId}),file(file,{fileId}, belongs to a bucket).ID constraints: custom IDs use a-z, A-Z, 0-9,
.,-,_; cannot start with a special character; max 36 characters.
Authentication and Permissions
For authentication and request header conventions, see Common Conventions. Scopes in this domain:
| Scope | Coverage |
|---|---|
buckets.read / buckets.write | Bucket CRUD |
files.read / files.write | File upload, read, download/preview/view, update, delete |
Resource-level permissions (bucket $permissions + fileSecurity, file $permissions) constrain user-identity access; API Key access only performs scope checks. When permissions do not match, download/preview returns 404 instead of 403 (no existence leak).
Endpoint overview
The Storage module provides 13 endpoints in total: including 5 bucket management endpoints (/storage/buckets*) and 8 file management and streaming read endpoints (/storage/buckets/{bucketId}/files*, covering the download, preview, and view binary output modes).
Endpoint List
| Method + path | Purpose |
|---|---|
GET /storage/buckets | List buckets |
POST /storage/buckets | Create bucket |
GET /storage/buckets/{bucketId} | Get bucket |
PUT /storage/buckets/{bucketId} | Update bucket configuration |
DELETE /storage/buckets/{bucketId} | Delete bucket (cascades to files) |
GET /storage/buckets/{bucketId}/files | List files |
POST /storage/buckets/{bucketId}/files | Upload file (regular or first chunk of chunked upload) |
GET /storage/buckets/{bucketId}/files/{fileId} | Get file metadata |
PUT /storage/buckets/{bucketId}/files/{fileId} | Update file name/permissions |
DELETE /storage/buckets/{bucketId}/files/{fileId} | Delete file |
GET /storage/buckets/{bucketId}/files/{fileId}/download | Download (Content-Disposition: attachment) |
GET /storage/buckets/{bucketId}/files/{fileId}/preview | Image preview (server-side image transformation) |
GET /storage/buckets/{bucketId}/files/{fileId}/view | Inline view (opens directly in browser) |
Endpoint details
Large-file chunked upload protocol: when the uploaded file exceeds
5 MiB, the client must split it into chunks per5 MiB; the first chunkfileIdpassesunique()or a custom ID, subsequent chunksfileIdpass the$idreturned by the first chunk, and each request must include theContent-Range: bytes start-end/totalandx-appwrite-id: <fileId>headers.Differences among the three binary read endpoints:
/downloadattachesContent-Disposition: attachmentto trigger the browser to save the file;/viewattachesContent-Disposition: inlineso the browser renders PDFs/audio/video/images directly;/previewprovides real-time width/height scaling, rounded corners, borders, background color, and WebP/AVIF format conversion for images.
Requests and Responses
The following sections give inputs, outputs, copyable call examples, and response examples for each endpoint. Upload endpoints are multipart/form-data; all other write endpoints are application/json; see General conventions for authentication headers and example variable conventions.
GET /v1/storage/buckets
List all buckets in the project.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | Filterable fields: enabled, name, fileSecurity, maximumFileSize, encryption, antivirus, transformations |
search | query | string | No | Fuzzy search term (max 256 characters), covering the bucket name | |
total | query | boolean | No | Default true | Pass false to skip counting |
Output: 200, returning the bucketList model: total + buckets[]. For the bucket field structure see POST /v1/storage/buckets.
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of buckets matching the query |
| buckets[] | bucket[] | Bucket object |
Call example:
curl \
"https://<your-endpoint>/v1/storage/buckets?queries[]=limit(25)&total=false" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 1,
"buckets": [
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}
]
}POST /v1/storage/buckets
Create a bucket and configure access and processing policies. By default no user role is granted — user-side file reading requires explicitly configuring permissions (see permissions).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | body | string | Yes | Bucket ID: custom or pass unique(); allowed characters a-z, A-Z, 0-9, ., -, _, max 36 characters | |
name | body | string | Yes | Bucket name | |
permissions | body | string[] | No | Array of bucket-level permission strings, e.g. read("any"); defaults to an empty array (no user role granted) | |
fileSecurity | body | boolean | No | Default false | Enable file-level permissions: a user with either bucket-level or file-level permission can access the file |
enabled | body | boolean | No | Default true | When false, ordinary application users cannot access the bucket; API key and privileged project-management identities are exempt from this switch but still require applicable authentication and authorization. Disabling does not delete files |
maximumFileSize | body | integer | No | Per-file size limit (bytes); exceeding it returns storage_invalid_file_size | |
allowedFileExtensions | body | string[] | No | At most 100 items, each max 64 characters | Extension whitelist; an empty array means no restriction |
compression | body | string | No | none (default) / gzip / zstd | Compression algorithm; files over 20MB skip compression even when enabled |
encryption | body | boolean | No | Default true | Encryption at rest; files over 20MB skip |
antivirus | body | boolean | No | Default true | Virus scanning additionally requires environment enablement, local storage, and a file at most 20,000,000 bytes; it runs after device upload and completion of all chunks |
transformations | body | boolean | No | Default true | Whether to enable image transformation (a prerequisite for /preview) |
clientFileListing | body | boolean | No | Default true | Whether to allow app clients to list files; when false, only authorized admin clients can list files, while upload and single-file access permissions remain unchanged |
Output: 201, returning the bucket model. Full field table:
| Field | Type | Description |
|---|---|---|
| $id | string | Bucket ID |
| $createdAt / $updatedAt | string | Creation/update time (ISO 8601) |
| $permissions | string[] | Bucket-level permission strings (see permissions) |
| fileSecurity | boolean | Whether file-level permissions are enabled |
| name | string | Bucket name |
| enabled | boolean | Whether it is enabled; when false, it is inaccessible on the user side, but API Keys can still access it |
| maximumFileSize | integer | Maximum size per file (bytes) |
| allowedFileExtensions | string[] | Extension allowlist (empty array means no restriction) |
| compression | string | Compression algorithm: none / gzip / zstd |
| encryption | boolean | Whether encryption at rest is enabled |
| antivirus | boolean | Whether virus scanning is enabled |
| transformations | boolean | Whether image transformations are enabled (a prerequisite for preview) |
| totalSize | integer | Total bytes of files in the bucket |
Call example:
curl \
-X POST \
"https://<your-endpoint>/v1/storage/buckets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"bucketId": "app-assets",
"name": "App Assets",
"permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true
}'Response example:
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}GET /v1/storage/buckets/{bucketId}
Get the bucket configuration by ID.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID |
Output: 200, returning the bucket model; see fields in POST /v1/storage/buckets.
Call example:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}PUT /v1/storage/buckets/{bucketId}
Update the bucket configuration. name is required; all other parameters are optional. Omitted configuration items keep their current values (permissions with an empty array clears them).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
name | body | string | Yes | Bucket name | |
permissions | body | string[] | No | Array of bucket-level permission strings; if omitted, current permissions are kept | |
fileSecurity | body | boolean | No | File-level permissions toggle | |
enabled | body | boolean | No | Access toggle | |
maximumFileSize | body | integer | No | Maximum size per file (bytes) | |
allowedFileExtensions | body | string[] | No | Extension allowlist | |
compression | body | string | No | none / gzip / zstd | Compression algorithm |
encryption | body | boolean | No | Encryption-at-rest toggle | |
antivirus | body | boolean | No | Virus scanning toggle | |
transformations | body | boolean | No | Image transformations toggle | |
clientFileListing | body | boolean | No | Client file listing toggle: when false, only authorized admin clients can list files; if omitted, the current value is kept, and upload and per-file access permissions are unchanged |
Output : 200, returns a bucket model.
Call example:
curl \
-X PUT \
"https://<your-endpoint>/v1/storage/buckets/app-assets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "App Assets",
"maximumFileSize": 50000000,
"transformations": true
}'Response example:
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 50000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}DELETE /v1/storage/buckets/{bucketId}
Delete the bucket and cascade-delete all files inside it. This action is irreversible.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID |
Output: 204 No Content, no response body.
Call example:
curl \
-X DELETE \
"https://<your-endpoint>/v1/storage/buckets/app-assets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files
List files in the bucket. When the bucket clientFileListing=false, app clients (including anonymous requests, user sessions, and JWTs) cannot list files; authenticated server-side and project management requests remain subject to project authorization and the files.read scope.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
queries | query | string[] | No | Default [] | Filterable fields: name, signature, mimeType, sizeOriginal, chunksTotal, chunksUploaded |
search | query | string | No | Fuzzy search term (up to 256 characters), matching file names | |
total | query | boolean | No | Default true | Pass false to skip counting |
Output: 200, returning the fileList model: total + files[]. See POST /v1/storage/buckets/{bucketId}/files for the structure of the file field.
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of files matching the query |
| files[] | file[] | File objects |
Call example:
curl \
'https://<your-endpoint>/v1/storage/buckets/app-assets/files?queries[]=limit(25)&total=false' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 1,
"files": [
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "pink.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}
]
}POST /v1/storage/buckets/{bucketId}/files
Upload a file (multipart/form-data, rate limited to 60 requests/minute). Small files are completed in a single request; large files use resumable chunked upload on the same endpoint (see notes below).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | body(form) | string | Yes | File ID: custom or pass unique(); allowed characters are a-z, A-Z, 0-9, ., -, _, up to 36 characters | |
file | body(form) | string(binary) | Yes | Binary file content; the SDK provides an InputFile wrapper, and it can also be constructed directly in browser/Node environments | |
permissions | body(form) | string[] | No | Array of file-level permission strings; only takes effect when the bucket has fileSecurity enabled. By default, only the creator (in a user context) holds all permissions |
Output: 201, returning the file model. Full field table:
| Field | Type | Description |
|---|---|---|
| $id | string | File ID |
| bucketId | string | ID of the bucket the file belongs to |
| $createdAt / $updatedAt | string | Creation/update time (ISO 8601) |
| $permissions | string[] | File-level permission strings (effective when the bucket has fileSecurity enabled) |
| name | string | File name |
| signature | string | MD5 signature of the content (can be used to verify integrity) |
| mimeType | string | MIME type detected by the server |
| sizeOriginal | integer | Original size (bytes) |
| chunksTotal / chunksUploaded | integer | Total chunks and uploaded chunks; upload is complete when the two are equal |
| encryption | boolean | Whether encryption at rest is enabled |
| compression | string | Compression algorithm actually used: none / gzip / zstd |
Call example:
curl \
-X POST \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F fileId="66a9d9ab03c7d" \
-F permissions[]='read("any")' \
-F file="@./pink.png"Response example:
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "pink.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}Chunked upload (resumable large-file upload): call the same endpoint repeatedly with the X-Appwrite-ID: {fileId} header and the Content-Range: bytes <start>-<end>/<total> header, with the chunk binary as the body, until chunksUploaded == chunksTotal. After an interruption, resend the same fileId to resume from the breakpoint; progress can be queried via the chunksUploaded of GET .../files/{fileId}. An invalid Content-Range range returns storage_invalid_content_range / storage_invalid_range. Chunked call example:
curl -X POST "https://<your-endpoint>/v1/storage/buckets/app-assets/files" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Range: bytes 0-10485759/17890123" \
-H "X-Appwrite-ID: 66a9d9ab03c7d" \
--data-binary "@./pink.png.part0"GET /v1/storage/buckets/{bucketId}/files/{fileId}
Get file metadata (does not return the file content). During chunked uploads, chunksUploaded can be polled to observe progress.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID |
Output: 200, returning the file model; see fields in POST /v1/storage/buckets/{bucketId}/files.
Call example:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "pink.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}PUT /v1/storage/buckets/{bucketId}/files/{fileId}
Update file metadata (file name and permissions). File content is immutable—the update semantics only cover metadata.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID | |
name | body | string | No | New file name | |
permissions | body | string[] | No | Array of file-level permission strings (full replacement); if omitted, current permissions are kept |
Output : 200, returns a file model.
Call example:
curl \
-X PUT \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "pink-updated.png",
"permissions": [
"read(\"label:vip\")"
]
}'Response example:
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"label:vip\")"
],
"name": "pink-updated.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}DELETE /v1/storage/buckets/{bucketId}/files/{fileId}
Delete a single file (rate limited to 60 requests/minute).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID |
Output: 204 No Content, no response body.
Call example:
curl \
-X DELETE \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files/{fileId}/download
Download the file content: the response carries Content-Disposition: attachment and Content-Type: <文件 MIME>, triggering a save in browsers. Returns a binary stream, not JSON.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID | |
token | query | string | No | File token (see file-tokens), used in scenarios without a Session/Cookie (<img>, email links) |
Output: 200, returning the file binary stream; response headers include Content-Type, Content-Length, Content-Disposition: attachment; filename="...", ETag.
Call example:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/download" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files/{fileId}/view
View a file inline: Content-Disposition: inline, which browsers can open directly (PDF/images/text). Returns a binary stream, not JSON.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID | |
token | query | string | No | File token (see file-tokens) |
Output: 200, returning the file binary stream (inline). Non-image files are returned as-is without transformation.
Call example:
curl \
'https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/view?token=<TOKEN>' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files/{fileId}/preview
Image preview: available only for image files; the server transforms the image in real time based on query parameters. Returns storage_bucket_transformations_disabled when the bucket does not have transformations enabled.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID (must be an image) | |
width / height | query | integer | No | Defaults to 0 (keeps original aspect ratio), 0–4000 | Target width/height (pixels); passing only one scales proportionally |
gravity | query | string | No | center (default) / top-left / top / top-right / left / right / bottom-left / bottom / bottom-right | Crop anchor point |
quality | query | integer | No | Defaults to -1 (uses the original image), 0–100 | Output quality |
borderWidth | query | integer | No | Defaults to 0 | Border width (pixels) |
borderColor | query | string | No | Border color (HEX, e.g. ff0000) | |
borderRadius | query | integer | No | Defaults to 0 | Corner radius (pixels) |
opacity | query | number | No | Defaults to 1, 0–1 | Opacity; only effective for formats with an alpha channel |
rotation | query | integer | No | Defaults to 0, -360–360 | Rotation angle |
background | query | string | No | Background color for transparent areas (HEX, e.g. ffffff) | |
output | query | string | No | jpg / jpeg / png / webp / heic / avif / gif | Output format |
token | query | string | No | File token (see file-tokens) |
Output: 200, returning the transformed image binary stream (Content-Type follows the output parameter or the original image format).
Call example:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/preview?width=400&height=300&gravity=center&quality=80&output=jpg" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Errors and boundaries
Bucket/file not found:
404+storage_bucket_not_found/storage_file_not_found; permission mismatches likewise returnstorage_file_not_foundon download/preview/view paths (does not reveal existence).Duplicate ID:
409+storage_bucket_already_exists/storage_file_already_exists.File type/size violations:
storage_file_type_unsupported(extension outside the allowlist),storage_invalid_file_size(exceedsmaximumFileSize),storage_invalid_file/storage_file_empty(empty file).Storage quota exceeded:
storage_limit_exceeded(413); project object storage limits can only be read from quota/limits-type responses (see projects).After upload, files larger than 20,000,000 bytes skip compression, application-level encryption and this antivirus scan. Antivirus also requires both environment and bucket enablement and a local storage device; the bucket toggle alone does not guarantee every file was scanned.
Deleting a bucket cascade-deletes all files and is irreversible;
enabled=falseis only an access toggle.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Storage.listBuckets | GET /storage/buckets |
Storage.createBucket | POST /storage/buckets |
Storage.getBucket | GET /storage/buckets/{bucketId} |
Storage.updateBucket | PUT /storage/buckets/{bucketId} |
Storage.deleteBucket | DELETE /storage/buckets/{bucketId} |
Storage.listFiles | GET /storage/buckets/{bucketId}/files |
Storage.createFile | POST /storage/buckets/{bucketId}/files |
Storage.getFile | GET /storage/buckets/{bucketId}/files/{fileId} |
Storage.updateFile | PUT /storage/buckets/{bucketId}/files/{fileId} |
Storage.deleteFile | DELETE /storage/buckets/{bucketId}/files/{fileId} |
Storage.getFileDownload | GET .../files/{fileId}/download |
Storage.getFilePreview | GET .../files/{fileId}/preview |
Storage.getFileView | GET .../files/{fileId}/view |