Docs
Contents

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

Authentication and Permissions

For authentication and request header conventions, see Common Conventions. Scopes in this domain:

ScopeCoverage
buckets.read / buckets.writeBucket CRUD
files.read / files.writeFile 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 + pathPurpose
GET /storage/bucketsList buckets
POST /storage/bucketsCreate 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}/filesList files
POST /storage/buckets/{bucketId}/filesUpload 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}/downloadDownload (Content-Disposition: attachment)
GET /storage/buckets/{bucketId}/files/{fileId}/previewImage preview (server-side image transformation)
GET /storage/buckets/{bucketId}/files/{fileId}/viewInline view (opens directly in browser)

Endpoint details

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:

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []Filterable fields: enabled, name, fileSecurity, maximumFileSize, encryption, antivirus, transformations
searchquerystringNoFuzzy search term (max 256 characters), covering the bucket name
totalquerybooleanNoDefault truePass false to skip counting

Output: 200, returning the bucketList model: total + buckets[]. For the bucket field structure see POST /v1/storage/buckets.

FieldTypeDescription
totalintegerTotal 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdbodystringYesBucket ID: custom or pass unique(); allowed characters a-z, A-Z, 0-9, ., -, _, max 36 characters
namebodystringYesBucket name
permissionsbodystring[]NoArray of bucket-level permission strings, e.g. read("any"); defaults to an empty array (no user role granted)
fileSecuritybodybooleanNoDefault falseEnable file-level permissions: a user with either bucket-level or file-level permission can access the file
enabledbodybooleanNoDefault truefalse acts as an access switch: user-side access is disabled, API Keys can still access, and files are not lost
maximumFileSizebodyintegerNoPer-file size limit (bytes); exceeding it returns storage_invalid_file_size
allowedFileExtensionsbodystring[]NoAt most 100 items, each max 64 charactersExtension whitelist; an empty array means no restriction
compressionbodystringNonone (default) / gzip / zstdCompression algorithm; files over 20MB skip compression even when enabled
encryptionbodybooleanNoDefault trueEncryption at rest; files over 20MB skip
antivirusbodybooleanNoDefault falseVirus scanning; files over 20MB skip
transformationsbodybooleanNoDefault falseWhether to enable image transformation (a prerequisite for /preview)
clientFileListingbodybooleanNoDefault trueWhether 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:

FieldTypeDescription
$idstringBucket ID
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
$permissionsstring[]Bucket-level permission strings (see permissions)
fileSecuritybooleanWhether file-level permissions are enabled
namestringBucket name
enabledbooleanWhether it is enabled; when false, it is inaccessible on the user side, but API Keys can still access it
maximumFileSizeintegerMaximum size per file (bytes)
allowedFileExtensionsstring[]Extension allowlist (empty array means no restriction)
compressionstringCompression algorithm: none / gzip / zstd
encryptionbooleanWhether encryption at rest is enabled
antivirusbooleanWhether virus scanning is enabled
transformationsbooleanWhether image transformations are enabled (a prerequisite for preview)
totalSizeintegerTotal 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
namebodystringYesBucket name
permissionsbodystring[]NoArray of bucket-level permission strings; if omitted, current permissions are kept
fileSecuritybodybooleanNoFile-level permissions toggle
enabledbodybooleanNoAccess toggle
maximumFileSizebodyintegerNoMaximum size per file (bytes)
allowedFileExtensionsbodystring[]NoExtension allowlist
compressionbodystringNonone / gzip / zstdCompression algorithm
encryptionbodybooleanNoEncryption-at-rest toggle
antivirusbodybooleanNoVirus scanning toggle
transformationsbodybooleanNoImage transformations toggle
clientFileListingbodybooleanNoClient 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
queriesquerystring[]NoDefault []Filterable fields: name, signature, mimeType, sizeOriginal, chunksTotal, chunksUploaded
searchquerystringNoFuzzy search term (up to 256 characters), matching file names
totalquerybooleanNoDefault truePass 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.

FieldTypeDescription
totalintegerTotal 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdbody(form)stringYesFile ID: custom or pass unique(); allowed characters are a-z, A-Z, 0-9, ., -, _, up to 36 characters
filebody(form)string(binary)YesBinary file content; the SDK provides an InputFile wrapper, and it can also be constructed directly in browser/Node environments
permissionsbody(form)string[]NoArray 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:

FieldTypeDescription
$idstringFile ID
bucketIdstringID of the bucket the file belongs to
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
$permissionsstring[]File-level permission strings (effective when the bucket has fileSecurity enabled)
namestringFile name
signaturestringMD5 signature of the content (can be used to verify integrity)
mimeTypestringMIME type detected by the server
sizeOriginalintegerOriginal size (bytes)
chunksTotal / chunksUploadedintegerTotal chunks and uploaded chunks; upload is complete when the two are equal
encryptionbooleanWhether encryption at rest is enabled
compressionstringCompression 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile ID
namebodystringNoNew file name
permissionsbodystring[]NoArray 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile ID
tokenquerystringNoFile 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile ID
tokenquerystringNoFile 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile ID (must be an image)
width / heightqueryintegerNoDefaults to 0 (keeps original aspect ratio), 0–4000Target width/height (pixels); passing only one scales proportionally
gravityquerystringNocenter (default) / top-left / top / top-right / left / right / bottom-left / bottom / bottom-rightCrop anchor point
qualityqueryintegerNoDefaults to -1 (uses the original image), 0–100Output quality
borderWidthqueryintegerNoDefaults to 0Border width (pixels)
borderColorquerystringNoBorder color (HEX, e.g. ff0000)
borderRadiusqueryintegerNoDefaults to 0Corner radius (pixels)
opacityquerynumberNoDefaults to 1, 0–1Opacity; only effective for formats with an alpha channel
rotationqueryintegerNoDefaults to 0, -360–360Rotation angle
backgroundquerystringNoBackground color for transparent areas (HEX, e.g. ffffff)
outputquerystringNojpg / jpeg / png / webp / heic / avif / gifOutput format
tokenquerystringNoFile 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

Correspondence with the Server SDK

service.methodEndpoint
Storage.listBucketsGET /storage/buckets
Storage.createBucketPOST /storage/buckets
Storage.getBucketGET /storage/buckets/{bucketId}
Storage.updateBucketPUT /storage/buckets/{bucketId}
Storage.deleteBucketDELETE /storage/buckets/{bucketId}
Storage.listFilesGET /storage/buckets/{bucketId}/files
Storage.createFilePOST /storage/buckets/{bucketId}/files
Storage.getFileGET /storage/buckets/{bucketId}/files/{fileId}
Storage.updateFilePUT /storage/buckets/{bucketId}/files/{fileId}
Storage.deleteFileDELETE /storage/buckets/{bucketId}/files/{fileId}
Storage.getFileDownloadGET .../files/{fileId}/download
Storage.getFilePreviewGET .../files/{fileId}/preview
Storage.getFileViewGET .../files/{fileId}/view