Appwrite.Services.Storage (appwrite v1.0.0)

View Source

The Storage service allows you to manage your project files.

File format for uploads

The file_info argument accepted by create_file/5 must be a map with the following string keys:

%{
  "name" => "report.pdf",          # display filename
  "data" => <<binary content>>,    # raw binary — NOT base64 at call site
  "type" => "application/pdf",     # MIME type
  "size" => 204_800                # byte length (integer)
}

The SDK handles base64 encoding internally for chunked uploads.

See CHANGELOG.md for version history.

Summary

Functions

create_file(bucket_id, file_id, file_info, permissions \\ nil, on_progress \\ nil)

Create (upload) a new file. Files larger than 5 MB are uploaded in chunks automatically using Client.chunked_upload/5.

delete_file(bucket_id, file_id)

Delete a file by its unique ID.

get_file(bucket_id, file_id)

Get file metadata by its unique ID.

get_file_download(bucket_id, file_id, token \\ nil)

Build a file download URL.

get_file_preview(bucket_id, file_id, opts \\ [])

Build a file preview URL.

get_file_view(bucket_id, file_id, token \\ nil)

Build a file view URL (inline browser display).

list_files(bucket_id, queries \\ nil, search \\ nil, total \\ nil)

List files in a storage bucket.

update_file(bucket_id, file_id, name \\ nil, permissions \\ nil)

Update a file's display name and/or permissions.

Functions

create_file(bucket_id, file_id, file_info, permissions \\ nil, on_progress \\ nil)

@spec create_file(
  String.t(),
  String.t(),
  %{required(String.t()) => String.t() | binary() | integer()},
  [String.t()] | nil,
  (map() -> any()) | nil
) :: {:ok, map()} | {:error, any()}

Create (upload) a new file. Files larger than 5 MB are uploaded in chunks automatically using Client.chunked_upload/5.

Parameters

  • bucket_id (required)
  • file_id (required) — use Appwrite.Utils.Id.unique() to auto-generate
  • file_info (required) — map with string keys:
    • "name" — display filename (e.g. "report.pdf")
    • "data" — raw binary content
    • "type" — MIME type (e.g. "application/pdf")
    • "size" — byte length as integer
  • permissions (optional) — list of permission strings
  • on_progress (optional) — 1-arity callback called after each chunk with %Appwrite.Types.Client.UploadProgress{}

delete_file(bucket_id, file_id)

@spec delete_file(String.t(), String.t()) :: {:ok, map()} | {:error, any()}

Delete a file by its unique ID.

get_file(bucket_id, file_id)

@spec get_file(String.t(), String.t()) :: {:ok, map()} | {:error, any()}

Get file metadata by its unique ID.

get_file_download(bucket_id, file_id, token \\ nil)

@spec get_file_download(String.t(), String.t(), String.t() | nil) ::
  {:ok, String.t()} | {:error, any()}

Build a file download URL.

Parameters

  • bucket_id (required)
  • file_id (required)
  • token (optional) — file token for unauthenticated access via the Tokens API

get_file_preview(bucket_id, file_id, opts \\ [])

@spec get_file_preview(String.t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, any()}

Build a file preview URL.

Parameters

  • bucket_id (required)
  • file_id (required)
  • opts — optional keyword list:
    • :width, :height, :gravity, :quality
    • :border_width, :border_color, :border_radius
    • :opacity, :rotation, :background, :output
    • :token — file token for unauthenticated access

get_file_view(bucket_id, file_id, token \\ nil)

@spec get_file_view(String.t(), String.t(), String.t() | nil) ::
  {:ok, String.t()} | {:error, any()}

Build a file view URL (inline browser display).

Parameters

  • bucket_id (required)
  • file_id (required)
  • token (optional) — file token for unauthenticated access

list_files(bucket_id, queries \\ nil, search \\ nil, total \\ nil)

@spec list_files(String.t(), [String.t()] | nil, String.t() | nil, boolean() | nil) ::
  {:ok, map()} | {:error, any()}

List files in a storage bucket.

Parameters

  • bucket_id (required)
  • queries (optional) — list of query strings
  • search (optional) — text search term
  • total (optional) — when false, skips count calculation for performance

update_file(bucket_id, file_id, name \\ nil, permissions \\ nil)

@spec update_file(String.t(), String.t(), String.t() | nil, [String.t()] | nil) ::
  {:ok, map()} | {:error, any()}

Update a file's display name and/or permissions.

Parameters

  • bucket_id (required)
  • file_id (required)
  • name (optional) — new display name
  • permissions (optional) — replacement permission list