Storage — API Reference

The supabase-storage module is a typed, Result-first wrapper over the Supabase Storage REST API (/storage/v1). It manages buckets, uploads and downloads objects, lists them with offset or cursor paging, builds public/authenticated/signed/render URLs locally, runs resumable (TUS) uploads, and exposes the analytics (Apache Iceberg) catalog and S3-Vectors surfaces.

Every suspending call returns a SupabaseResult<T> rather than throwing — network and HTTP errors (for example 404 for a missing object, 409 on an upsert conflict) arrive as Failure, so they are values you handle rather than exceptions you catch. The non-suspending URL builders compute a string locally and never touch the network.

• Maven artifact: io.github.androidpoet:supabase-storage
• Entry point: createStorageClient(client) (or the client.storage accessor)
• Package: io.github.androidpoet.supabase.storage (models in …storage.models)

Object paths are bucket-relative keys (for example folder/file.png) and are URL-encoded for you, with / preserved as a path separator.

Setup

createStorageClient

Builds a StorageClient from an existing SupabaseClient.

fun createStorageClient(supabaseClient: SupabaseClient): StorageClient

• supabaseClient — the configured client whose project URL the storage calls target.

Returns a StorageClient. This call does no I/O and does not fail.

val storage = createStorageClient(client)

SupabaseClient.storage

A discoverable extension property that calls createStorageClient for you, so you can reach storage as client.storage. The returned client is a thin, stateless wrapper, so reading the property repeatedly is cheap.

val SupabaseClient.storage: StorageClient

val files = client.storage.list(bucket = "avatars")

StorageClient

The interface exposing every storage operation. Suspending calls return SupabaseResult<T>; the URL builders return a String (or collection) computed locally. The sections below group the members by area.

Buckets

listBuckets

Lists the buckets visible to the current credentials (GET /bucket).

suspend fun listBuckets(
    limit: Int? = null,
    offset: Int? = null,
    sortColumn: String? = null,
    sortOrder: SortOrder? = null,
    search: String? = null,
): SupabaseResult<List<Bucket>>

• limit — maximum number of buckets to return. Default null.
• offset — number of buckets to skip, for paging. Default null.
• sortColumn — column to sort by (server-defined, e.g. name/created_at). Default null.
• sortOrder — ascending or descending order for sortColumn. Default null.
• search — case-insensitive filter applied server-side to bucket names. Default null.

Returns SupabaseResult<List<Bucket>> — Success with the buckets, Failure on error.

val buckets = storage.listBuckets(search = "avatars")

getBucket

Fetches a single bucket by id.

suspend fun getBucket(id: String): SupabaseResult<Bucket>

• id — the bucket id.

Returns SupabaseResult<Bucket> — Success with the bucket, Failure (404) if no such bucket exists.

val bucket = storage.getBucket("avatars")

createBucket

Creates a bucket, returning the created Bucket.

suspend fun createBucket(
    id: String,
    name: String,
    public: Boolean = false,
    fileSizeLimit: Long? = null,
    allowedMimeTypes: List<String>? = null,
): SupabaseResult<Bucket>

• id — the bucket id (its stable identifier and URL segment).
• name — human-readable bucket name.
• public — when true, objects are readable via the public endpoint without a token. Default false.
• fileSizeLimit — optional per-object size cap in bytes; null leaves it unset. Default null.
• allowedMimeTypes — optional whitelist of accepted content types; null allows any. Default null.

Returns SupabaseResult<Bucket> — Success with the created bucket, Failure (e.g. 409) if id is already taken.

val bucket = storage.createBucket(
    id = "avatars",
    name = "avatars",
    public = true,
    fileSizeLimit = 5 * 1024 * 1024,
    allowedMimeTypes = listOf("image/png", "image/jpeg"),
)

updateBucket

Updates a bucket’s mutable attributes. Only non-null arguments are sent, so omitted fields are left unchanged.

suspend fun updateBucket(
    id: String,
    name: String? = null,
    public: Boolean? = null,
    fileSizeLimit: Long? = null,
    allowedMimeTypes: List<String>? = null,
): SupabaseResult<Bucket>

• id — the bucket to update.
• name — new bucket name, or null to keep it. Default null.
• public — new public flag, or null to keep it. Default null.
• fileSizeLimit — new per-object size cap in bytes, or null to keep it. Default null.
• allowedMimeTypes — new MIME whitelist, or null to keep it. Default null.

Returns SupabaseResult<Bucket> — Success with the updated bucket, Failure on error.

storage.updateBucket(id = "avatars", public = false)

deleteBucket

Deletes a bucket. The bucket must be empty first; see clearBucket.

suspend fun deleteBucket(id: String): SupabaseResult<Unit>

• id — the bucket to delete.

Returns SupabaseResult<Unit> — Success on deletion, Failure (e.g. if the bucket is not empty) otherwise.

storage.deleteBucket("avatars")

clearBucket

Removes every object from a bucket without deleting the bucket itself.

suspend fun clearBucket(id: String): SupabaseResult<Unit>

• id — the bucket to empty.

Returns SupabaseResult<Unit> — Success when cleared, Failure on error.

storage.clearBucket("avatars")        // then deleteBucket succeeds

Objects

upload

Uploads data to path in bucket.

suspend fun upload(
    bucket: String,
    path: String,
    data: ByteArray,
    contentType: String = "application/octet-stream",
    upsert: Boolean = false,
    cacheControl: Int? = null,
    metadata: JsonObject? = null,
): SupabaseResult<String>

• bucket — target bucket.
• path — bucket-relative key to write.
• data — the bytes to upload.
• contentType — MIME type stored for the object. Default "application/octet-stream".
• upsert — when true, overwrite an existing object at path. Default false.
• cacheControl — cache-control max-age in seconds, when set. Default null.
• metadata — optional user metadata; Base64-encoded into the x-metadata header. Default null.

Returns SupabaseResult<String> — Success with the server-reported key, Failure (e.g. 409 without upsert) on error.

val key = storage.upload(
    bucket = "avatars",
    path = "jane/profile.png",
    data = pngBytes,
    contentType = "image/png",
    upsert = true,
)

update

Replaces the object at path in bucket with data. Same parameters and return as upload.

suspend fun update(
    bucket: String,
    path: String,
    data: ByteArray,
    contentType: String = "application/octet-stream",
    upsert: Boolean = false,
    cacheControl: Int? = null,
    metadata: JsonObject? = null,
): SupabaseResult<String>

Returns SupabaseResult<String> — Success with the key, Failure on error.

storage.update(bucket = "avatars", path = "jane/profile.png", data = newBytes)

createResumableUpload

Creates a resumable (TUS) upload handle. The upload is not started until ResumableUpload.await is called. Pass uploadUrl (a previously captured ResumableUpload.uploadUrl) to resume an interrupted upload instead of starting a new one.

fun createResumableUpload(
    bucket: String,
    path: String,
    data: ByteArray,
    contentType: String = "application/octet-stream",
    upsert: Boolean = false,
    cacheControl: Int? = null,
    chunkSize: Int = RESUMABLE_DEFAULT_CHUNK_SIZE,
    uploadUrl: String? = null,
    metadata: JsonObject? = null,
): ResumableUpload

• bucket — target bucket.
• path — bucket-relative key to write.
• data — the full payload to upload in chunks.
• contentType — MIME type stored for the object. Default "application/octet-stream".
• upsert — overwrite an existing object. Default false.
• cacheControl — cache-control max-age in seconds, when set. Default null.
• chunkSize — bytes per chunk; must be positive (a non-positive value throws IllegalArgumentException eagerly). Every chunk except the last must be a multiple of RESUMABLE_DEFAULT_CHUNK_SIZE (6 MiB). Default RESUMABLE_DEFAULT_CHUNK_SIZE.
• uploadUrl — a previously persisted upload URL to resume; null starts a new upload. Default null.
• metadata — optional user metadata; Base64-encoded into the TUS Upload-Metadata header. Default null.

Returns a ResumableUpload handle (no I/O until await).

val handle = storage.createResumableUpload("videos", "clip.mp4", videoBytes)
val result = handle.await()

uploadResumable

Extension that runs a resumable upload to completion in one call. Use createResumableUpload directly when you need progress or pause/resume.

suspend fun StorageClient.uploadResumable(
    bucket: String,
    path: String,
    data: ByteArray,
    contentType: String = "application/octet-stream",
    upsert: Boolean = false,
    cacheControl: Int? = null,
    chunkSize: Int = RESUMABLE_DEFAULT_CHUNK_SIZE,
    metadata: JsonObject? = null,
): SupabaseResult<Unit>

• Parameters mirror createResumableUpload (without uploadUrl).

Returns SupabaseResult<Unit> — Success when the upload completes, Failure on error.

storage.uploadResumable("videos", "clip.mp4", videoBytes)

uploadToSignedUrl

Uploads data to a pre-signed upload URL identified by token (see createSignedUploadUrl).

suspend fun uploadToSignedUrl(
    bucket: String,
    path: String,
    token: String,
    data: ByteArray,
    contentType: String = "application/octet-stream",
    upsert: Boolean = false,
    cacheControl: Int? = null,
    metadata: JsonObject? = null,
): SupabaseResult<String>

• bucket — bucket the token was issued for.
• path — the object path bound to the token.
• token — the signed upload token.
• data — the bytes to upload.
• contentType — MIME type stored for the object. Default "application/octet-stream".
• upsert — overwrite an existing object. Default false.
• cacheControl — cache-control max-age in seconds, when set. Default null.
• metadata — optional user metadata; Base64-encoded into the x-metadata header. Default null.

Returns SupabaseResult<String> — Success with the key, Failure on error.

storage.uploadToSignedUrl("avatars", "jane/profile.png", token, pngBytes)

download

Downloads an object’s body as a UTF-8 string from the authenticated endpoint. Text-only — for binary data use downloadBytes. Two overloads:

suspend fun download(bucket: String, path: String): SupabaseResult<String>
 
suspend fun download(
    bucket: String,
    path: String,
    download: Boolean = true,
    fileName: String? = null,
): SupabaseResult<String>

• bucket / path — the object to read.
• download — when true, send the download query so the server marks the response as an attachment. Default true (in the second overload).
• fileName — optional file name suggested for the saved attachment. Default null.

Returns SupabaseResult<String> — Success with the decoded text, Failure on error.

val text = storage.download(bucket = "docs", path = "notes.txt")

downloadPublic

Like download but reads from the public endpoint; no token required. Same two overloads (download defaults to true in the parameterized one).

suspend fun downloadPublic(bucket: String, path: String): SupabaseResult<String>
 
suspend fun downloadPublic(
    bucket: String,
    path: String,
    download: Boolean = true,
    fileName: String? = null,
): SupabaseResult<String>

Returns SupabaseResult<String> — Success with the decoded text, Failure on error.

val text = storage.downloadPublic("public-docs", "readme.txt")

downloadBytes

Downloads an object’s raw bytes from the authenticated endpoint. Prefer this over download for any non-text content. An empty object returns an empty ByteArray, not a failure. Two overloads — plain and with an image transform (the render endpoint):

suspend fun downloadBytes(
    bucket: String,
    path: String,
    download: Boolean = false,
    fileName: String? = null,
): SupabaseResult<ByteArray>
 
suspend fun downloadBytes(
    bucket: String,
    path: String,
    transform: ImageTransformOptions,
    download: Boolean = false,
    fileName: String? = null,
): SupabaseResult<ByteArray>

• bucket / path — the object to read.
• transform — server-side image resize/format/quality (render endpoint).
• download — request an attachment response. Default false.
• fileName — suggested attachment file name. Default null.

Returns SupabaseResult<ByteArray> — Success with the bytes, Failure on error.

val bytes = storage.downloadBytes("avatars", "jane/profile.png")
val thumb = storage.downloadBytes(
    "avatars", "jane/profile.png",
    transform = ImageTransformOptions(width = 64, height = 64),
)

downloadPublicBytes

Binary download from the public endpoint. Same two overloads as downloadBytes (plain and with transform, the public render endpoint).

suspend fun downloadPublicBytes(
    bucket: String,
    path: String,
    download: Boolean = false,
    fileName: String? = null,
): SupabaseResult<ByteArray>
 
suspend fun downloadPublicBytes(
    bucket: String,
    path: String,
    transform: ImageTransformOptions,
    download: Boolean = false,
    fileName: String? = null,
): SupabaseResult<ByteArray>

Returns SupabaseResult<ByteArray> — Success with the bytes, Failure on error.

val bytes = storage.downloadPublicBytes("public-images", "logo.png")

info

Fetches an object’s metadata (FileObject) without its body, via the authenticated info endpoint.

suspend fun info(bucket: String, path: String): SupabaseResult<FileObject>

• bucket / path — the object to inspect.

Returns SupabaseResult<FileObject> — Success with the metadata, Failure (404) if the object does not exist.

val meta = storage.info("avatars", "jane/profile.png")

infoPublic

Like info but from the public info endpoint.

suspend fun infoPublic(bucket: String, path: String): SupabaseResult<FileObject>

Returns SupabaseResult<FileObject> — Success with the metadata, Failure on error.

val meta = storage.infoPublic("public-images", "logo.png")

exists

Reports whether an object exists, via info. A 404 maps to Success(false); any other failure (auth, network) is still surfaced as Failure.

suspend fun exists(bucket: String, path: String): SupabaseResult<Boolean>

Returns SupabaseResult<Boolean> — Success(true/false), or Failure for non-404 errors.

val present = storage.exists("avatars", "jane/profile.png")

existsPublic

Like exists but probes the public endpoint via infoPublic.

suspend fun existsPublic(bucket: String, path: String): SupabaseResult<Boolean>

Returns SupabaseResult<Boolean> — Success(true/false), or Failure on error.

val present = storage.existsPublic("public-images", "logo.png")

list

Lists objects and folders under prefix in bucket (POST /object/list). This is the offset-paged listing; for cursor paging use listV2.

suspend fun list(
    bucket: String,
    prefix: String = "",
    limit: Int = 100,
    offset: Int = 0,
    sortBy: String? = null,
    sortOrder: SortOrder = SortOrder.ASC,
    search: String? = null,
): SupabaseResult<List<FileObject>>

• bucket — bucket to list.
• prefix — folder path to list within; empty lists the bucket root. Default "".
• limit — maximum entries to return. Default 100.
• offset — entries to skip, for paging. Default 0.
• sortBy — column to sort by; null leaves the server default ordering. Default null.
• sortOrder — ascending or descending, applied when sortBy is set. Default SortOrder.ASC.
• search — case-insensitive filter applied server-side to entry names. Default null.

Returns SupabaseResult<List<FileObject>> — Success with the entries, Failure on error.

val entries = storage.list(bucket = "avatars", prefix = "jane")

listV2

Cursor-paged object listing (POST /object/list-v2) returning an ObjectListV2Response that separates folders from objects and carries a nextCursor/hasNext for continuation. Prefer this over list for large buckets or delimiter-style folder navigation.

suspend fun listV2(
    bucket: String,
    prefix: String? = null,
    cursor: String? = null,
    limit: Int? = null,
    withDelimiter: Boolean? = null,
    sortBy: String? = null,
    sortOrder: SortOrder = SortOrder.ASC,
): SupabaseResult<ObjectListV2Response>

• bucket — bucket to list.
• prefix — folder path to list within; null lists the bucket root. Default null.
• cursor — continuation cursor from a previous result’s nextCursor. Default null.
• limit — maximum entries to return in this page. Default null.
• withDelimiter — when true, collapse nested keys into folder entries. Default null.
• sortBy — column to sort by; null leaves the server default. Default null.
• sortOrder — order applied when sortBy is set. Default SortOrder.ASC.

Returns SupabaseResult<ObjectListV2Response> — Success with the page, Failure on error.

var page = storage.listV2(bucket = "avatars", withDelimiter = true).getOrThrow()
while (page.hasNext) {
    page = storage.listV2(bucket = "avatars", cursor = page.nextCursor).getOrThrow()
}

listOrThrow

Extension form of list that returns the List<FileObject> directly and throws on failure — the exception-channel variant for paging or try/catch callers.

suspend fun StorageClient.listOrThrow(
    bucket: String,
    prefix: String = "",
    limit: Int = 100,
    offset: Int = 0,
    sortBy: String? = null,
    sortOrder: SortOrder = SortOrder.ASC,
    search: String? = null,
): List<FileObject>

• Parameters mirror list.

Returns List<FileObject> directly; throws on failure.

val entries = storage.listOrThrow(bucket = "avatars")

listPaginator

Extension that builds a demand-driven Paginator<FileObject> over the objects under prefix, fetching one offset-based page per loadNext via list. Nothing is fetched until loadNext is called; the accumulated entries and the loading/end/error state are exposed as StateFlows.

fun StorageClient.listPaginator(
    bucket: String,
    prefix: String = "",
    pageSize: Int = 100,
    sortBy: String? = null,
    sortOrder: SortOrder = SortOrder.ASC,
    search: String? = null,
): Paginator<FileObject>

• bucket — bucket to page over.
• prefix — folder path to list within. Default "".
• pageSize — entries per page; must be greater than 0. Default 100.
• sortBy / sortOrder / search — as in list.

Returns a Paginator<FileObject>; a failure surfaces via Paginator.error.

val paginator = storage.listPaginator(bucket = "avatars", pageSize = 50)
paginator.loadNext()

move

Moves (renames) the object at fromPath to toPath (POST /object/move), optionally across buckets. Unlike copy, the source no longer exists afterward.

suspend fun move(
    bucket: String,
    fromPath: String,
    toPath: String,
    destinationBucket: String? = null,
): SupabaseResult<Unit>

• bucket — source bucket.
• fromPath — object key to move.
• toPath — target object key.
• destinationBucket — target bucket when moving across buckets; null moves within bucket. Default null.

Returns SupabaseResult<Unit> — Success on success, Failure on error.

storage.move("avatars", "tmp/upload.png", "jane/profile.png")

copy

Copies the object at fromPath to toPath (POST /object/copy), optionally across buckets; the source is left in place (contrast move).

suspend fun copy(
    bucket: String,
    fromPath: String,
    toPath: String,
    destinationBucket: String? = null,
    copyMetadata: Boolean? = null,
): SupabaseResult<Unit>

• bucket — source bucket.
• fromPath — object key to copy.
• toPath — target object key.
• destinationBucket — target bucket when copying across buckets; null copies within bucket. Default null.
• copyMetadata — when true, also copy the object’s user metadata. Default null.

Returns SupabaseResult<Unit> — Success on success, Failure on error.

storage.copy("avatars", "jane/profile.png", "jane/profile-backup.png")

deleteObject

Deletes a single object at path in bucket. For batch deletes prefer deleteObjects.

suspend fun deleteObject(bucket: String, path: String): SupabaseResult<Unit>

• bucket / path — the object to delete.

Returns SupabaseResult<Unit> — Success on deletion, Failure on error.

storage.deleteObject("avatars", "jane/profile.png")

deleteObjects

Deletes multiple objects by paths in one request and returns the FileObject entries the server reports as removed. Callers that don’t need the removed set can ignore the value. A vararg extension overload is also provided.

suspend fun deleteObjects(bucket: String, paths: List<String>): SupabaseResult<List<FileObject>>
 
// extension
suspend fun StorageClient.deleteObjects(
    bucket: String,
    vararg paths: String,
): SupabaseResult<List<FileObject>>

• bucket — bucket to delete from.
• paths — object keys to remove.

Returns SupabaseResult<List<FileObject>> — Success with the removed entries, Failure on error.

storage.deleteObjects("avatars", "jane/old.png", "jane/older.png")

URLs

The URL builders compute a string locally and never hit the network. Signing operations (createSignedUrl, createSignedUploadUrl) are suspending and do call the server.

createSignedUrl

Creates a time-limited signed download URL for a private object (POST /object/sign), letting an unauthenticated client read it until the URL expires.

suspend fun createSignedUrl(
    bucket: String,
    path: String,
    expiresIn: Long,
    download: Boolean = false,
    fileName: String? = null,
    transform: ImageTransformOptions? = null,
): SupabaseResult<String>

• bucket / path — the object to sign.
• expiresIn — lifetime of the signed URL in seconds.
• download — when true, the URL carries the download param so the object is served as an attachment. Default false.
• fileName — suggested attachment file name. Default null.
• transform — optional image transform baked into the signed URL (render endpoint). Default null.

Returns SupabaseResult<String> — Success with the signed URL, Failure on error.

val url = storage.createSignedUrl("avatars", "jane/profile.png", expiresIn = 3600)

createSignedUrls

Batch variant of createSignedUrl: signs every path in one request and returns the URLs in the same order.

suspend fun createSignedUrls(
    bucket: String,
    paths: List<String>,
    expiresIn: Long,
    download: Boolean = false,
    fileName: String? = null,
): SupabaseResult<List<String>>

• bucket — bucket to sign within.
• paths — object keys to sign.
• expiresIn / download / fileName — as in createSignedUrl.

Returns SupabaseResult<List<String>> — Success with the URLs in order, Failure on error.

val urls = storage.createSignedUrls("avatars", listOf("a.png", "b.png"), expiresIn = 600)

createSignedDownloadUrl / createSignedDownloadUrls

Extension conveniences over createSignedUrl / createSignedUrls that always set download = true, so the object is served as an attachment.

suspend fun StorageClient.createSignedDownloadUrl(
    bucket: String, path: String, expiresIn: Long, fileName: String? = null,
): SupabaseResult<String>
 
suspend fun StorageClient.createSignedDownloadUrl(
    bucket: String, path: String, expiresIn: Long,
    fileName: String? = null, transform: ImageTransformOptions? = null,
): SupabaseResult<String>
 
suspend fun StorageClient.createSignedDownloadUrls(
    bucket: String, paths: List<String>, expiresIn: Long, fileName: String? = null,
): SupabaseResult<List<String>>
suspend fun StorageClient.createSignedDownloadUrls(
    bucket: String, expiresIn: Long, vararg paths: String,
): SupabaseResult<List<String>>
suspend fun StorageClient.createSignedDownloadUrls(
    bucket: String, expiresIn: Long, fileName: String?, vararg paths: String,
): SupabaseResult<List<String>>

• bucket / path / paths — object(s) to sign.
• expiresIn — URL lifetime in seconds.
• fileName — suggested attachment file name. Default null.
• transform — optional image transform (render endpoint). Default null.

Returns SupabaseResult<String> (single) or SupabaseResult<List<String>> (batch) — Success with attachment URL(s), Failure on error.

val url = storage.createSignedDownloadUrl("docs", "report.pdf", expiresIn = 3600)

createSignedDownloadUrlsByPath

Like createSignedDownloadUrls but returns a path-to-URL Map instead of a positional list.

suspend fun StorageClient.createSignedDownloadUrlsByPath(
    bucket: String, paths: List<String>, expiresIn: Long, fileName: String? = null,
): SupabaseResult<Map<String, String>>
suspend fun StorageClient.createSignedDownloadUrlsByPath(
    bucket: String, expiresIn: Long, vararg paths: String,
): SupabaseResult<Map<String, String>>
suspend fun StorageClient.createSignedDownloadUrlsByPath(
    bucket: String, expiresIn: Long, fileName: String?, vararg paths: String,
): SupabaseResult<Map<String, String>>

Returns SupabaseResult<Map<String, String>> — Success mapping each path to its signed URL, Failure on error.

val byPath = storage.createSignedDownloadUrlsByPath("docs", 600, "a.pdf", "b.pdf")

createSignedRenderUrl / createSignedRenderUrls

Extension conveniences that sign an inline (non-download) render URL applying an image transform. The batch form signs sequentially and short-circuits to Failure on the first failing path.

suspend fun StorageClient.createSignedRenderUrl(
    bucket: String, path: String, expiresIn: Long, transform: ImageTransformOptions,
): SupabaseResult<String>
 
suspend fun StorageClient.createSignedRenderUrls(
    bucket: String, paths: List<String>, expiresIn: Long, transform: ImageTransformOptions,
): SupabaseResult<List<String>>
suspend fun StorageClient.createSignedRenderUrls(
    bucket: String, expiresIn: Long, transform: ImageTransformOptions, vararg paths: String,
): SupabaseResult<List<String>>

Returns SupabaseResult<String> / SupabaseResult<List<String>> — Success with render URL(s), Failure on error.

val url = storage.createSignedRenderUrl(
    "avatars", "jane/profile.png", 600,
    ImageTransformOptions(width = 200, height = 200),
)

createSignedRenderUrlsByPath

Like createSignedRenderUrls but returns a path-to-URL Map.

suspend fun StorageClient.createSignedRenderUrlsByPath(
    bucket: String, paths: List<String>, expiresIn: Long, transform: ImageTransformOptions,
): SupabaseResult<Map<String, String>>
suspend fun StorageClient.createSignedRenderUrlsByPath(
    bucket: String, expiresIn: Long, transform: ImageTransformOptions, vararg paths: String,
): SupabaseResult<Map<String, String>>

Returns SupabaseResult<Map<String, String>> — Success mapping each path to its render URL, Failure on error.

createSignedUploadUrl

Creates a signed upload token (POST /object/upload/sign) so a client without storage credentials can later upload to path via uploadToSignedUrl. Returns just the token.

suspend fun createSignedUploadUrl(
    bucket: String,
    path: String,
    upsert: Boolean = false,
): SupabaseResult<String>

• bucket / path — the upload target.
• upsert — when true, the token permits overwriting an existing object. Default false.

Returns SupabaseResult<String> — Success with the token, Failure on error.

val token = storage.createSignedUploadUrl("avatars", "jane/profile.png")

createSignedUploadUrlWithPath

Like createSignedUploadUrl but returns the full UploadSignedUrl (absolute upload URL, token, and bound path) instead of only the token.

suspend fun createSignedUploadUrlWithPath(
    bucket: String,
    path: String,
    upsert: Boolean = false,
): SupabaseResult<UploadSignedUrl>

Returns SupabaseResult<UploadSignedUrl> — Success with the signed target, Failure on error.

val signed = storage.createSignedUploadUrlWithPath("avatars", "jane/profile.png")

getSignedDownloadUrl

Builds the signed download URL for a previously issued signed-URL token locally, without a network call.

fun getSignedDownloadUrl(
    bucket: String,
    path: String,
    token: String,
    download: Boolean = false,
    fileName: String? = null,
): String

• bucket / path — the object the token addresses.
• token — the signed-URL token.
• download — when true, append the download param. Default false.
• fileName — suggested attachment file name. Default null.

Returns the addressable String URL (no I/O, never fails).

val url = storage.getSignedDownloadUrl("avatars", "jane/profile.png", token)

getPublicUrl

Builds the public URL (/object/public) for path locally — no network call and no token. Only resolves for objects in a public bucket. Two overloads:

fun getPublicUrl(
    bucket: String,
    path: String,
    transform: ImageTransformOptions? = null,
): String
 
fun getPublicUrl(
    bucket: String,
    path: String,
    download: Boolean = false,
    fileName: String? = null,
    transform: ImageTransformOptions? = null,
): String

• bucket / path — the object to address.
• download — when true, append the download param. Default false.
• fileName — suggested attachment file name. Default null.
• transform — target the render endpoint with a server-side image transform. Default null.

Returns the String URL (no I/O, never fails).

val url = storage.getPublicUrl("public-images", "logo.png")

getAuthenticatedUrl

Builds the authenticated URL (/object/authenticated) for path locally. The URL still requires valid credentials when fetched; this only composes the address. Two overloads matching getPublicUrl.

fun getAuthenticatedUrl(
    bucket: String, path: String, transform: ImageTransformOptions? = null,
): String
 
fun getAuthenticatedUrl(
    bucket: String, path: String,
    download: Boolean = false, fileName: String? = null,
    transform: ImageTransformOptions? = null,
): String

Returns the String URL (no I/O, never fails).

val url = storage.getAuthenticatedUrl("avatars", "jane/profile.png")

getPublicRenderUrl

Builds the public render/transform URL (/render/image/public) for path locally, applying transform as query params.

fun getPublicRenderUrl(
    bucket: String,
    path: String,
    transform: ImageTransformOptions? = null,
): String

Returns the String render URL (no I/O, never fails).

val url = storage.getPublicRenderUrl(
    "public-images", "logo.png", ImageTransformOptions(width = 128),
)

getAuthenticatedRenderUrl

Builds the authenticated render/transform URL (/render/image/authenticated) for path locally. The URL still requires credentials when fetched.

fun getAuthenticatedRenderUrl(
    bucket: String,
    path: String,
    transform: ImageTransformOptions? = null,
): String

Returns the String render URL (no I/O, never fails).

val url = storage.getAuthenticatedRenderUrl(
    "avatars", "jane/profile.png", ImageTransformOptions(width = 128),
)

Bulk URL builders

Extension helpers build URLs for many paths at once. Each comes in a List<String> overload, a vararg overload, and a …ByPath variant returning a path-to-URL Map. All are purely local (no network call); the authenticated variants still require credentials when fetched.

// public object URLs
fun StorageClient.getPublicUrls(
    bucket: String, paths: List<String>,
    download: Boolean = false, fileName: String? = null,
    transform: ImageTransformOptions? = null,
): List<String>
fun StorageClient.getPublicUrls(bucket: String, vararg paths: String): List<String>
fun StorageClient.getPublicUrls(
    bucket: String, download: Boolean = false, fileName: String? = null,
    transform: ImageTransformOptions? = null, vararg paths: String,
): List<String>
fun StorageClient.getPublicUrlsByPath(/* same params */): Map<String, String>   // 3 overloads
 
// authenticated object URLs
fun StorageClient.getAuthenticatedUrls(/* same shape as getPublicUrls */): List<String>      // 3 overloads
fun StorageClient.getAuthenticatedUrlsByPath(/* … */): Map<String, String>                   // 3 overloads
 
// public render URLs
fun StorageClient.getPublicRenderUrls(
    bucket: String, paths: List<String>, transform: ImageTransformOptions? = null,
): List<String>
fun StorageClient.getPublicRenderUrls(
    bucket: String, transform: ImageTransformOptions? = null, vararg paths: String,
): List<String>
fun StorageClient.getPublicRenderUrlsByPath(/* … */): Map<String, String>                    // 2 overloads
 
// authenticated render URLs
fun StorageClient.getAuthenticatedRenderUrls(/* same shape as getPublicRenderUrls */): List<String>   // 2 overloads
fun StorageClient.getAuthenticatedRenderUrlsByPath(/* … */): Map<String, String>                      // 2 overloads

• bucket — bucket to address.
• paths — object keys to build URLs for (positional List or vararg).
• download / fileName — attachment control (object URL families only). Defaults false / null.
• transform — server-side image transform. Default null.

Returns List<String> in input order, or Map<String, String> keyed by path for the …ByPath variants.

val urls = storage.getPublicUrls("public-images", "a.png", "b.png")
val byPath = storage.getAuthenticatedUrlsByPath("avatars", "x.png", "y.png")

withCacheNonce

Appends a cache-busting query param to a previously built storage URL (public, authenticated, signed, or render). Useful to force a CDN/browser to re-fetch an object overwritten at the same path. Returns the URL unchanged when nonce is null/blank.

fun withCacheNonce(url: String, nonce: String?, name: String = "cacheNonce"): String

• url — the storage URL to annotate.
• nonce — the cache-busting value, appended verbatim (pass a URL-safe value); null/blank returns url unchanged.
• name — the query-param name. Default "cacheNonce".

Returns the annotated String URL.

val fresh = withCacheNonce(url, nonce = updatedAtTimestamp)

Analytics buckets

The analytics surface manages Apache-Iceberg-backed buckets and their catalog.

createAnalyticsBucket

Creates an analytics (Iceberg) bucket. Use analyticsCatalog afterward to manage its namespaces and tables.

suspend fun createAnalyticsBucket(name: String): SupabaseResult<AnalyticsBucket>

• name — the analytics bucket name.

Returns SupabaseResult<AnalyticsBucket> — Success with the bucket, Failure on error.

val bucket = storage.createAnalyticsBucket("warehouse")

listAnalyticsBuckets

Lists analytics (Iceberg) buckets. Mirrors listBuckets’s paging/sort/search semantics over the analytics-bucket endpoint.

suspend fun listAnalyticsBuckets(
    limit: Int? = null,
    offset: Int? = null,
    sortColumn: String? = null,
    sortOrder: SortOrder? = null,
    search: String? = null,
): SupabaseResult<List<AnalyticsBucket>>

• Parameters mirror listBuckets.

Returns SupabaseResult<List<AnalyticsBucket>> — Success with the buckets, Failure on error.

val buckets = storage.listAnalyticsBuckets()

deleteAnalyticsBucket

Deletes the analytics (Iceberg) bucket name.

suspend fun deleteAnalyticsBucket(name: String): SupabaseResult<Unit>

Returns SupabaseResult<Unit> — Success on deletion, Failure on error.

storage.deleteAnalyticsBucket("warehouse")

analyticsCatalog

Returns an AnalyticsCatalogClient scoped to the analytics bucket bucketName for managing its Iceberg namespaces and tables. Validates bucketName eagerly and throws IllegalArgumentException if it is blank or contains characters outside [A-Za-z0-9._-].

fun analyticsCatalog(bucketName: String): AnalyticsCatalogClient

• bucketName — the analytics bucket the catalog targets (fixed at creation).

Returns an AnalyticsCatalogClient.

val catalog = storage.analyticsCatalog("warehouse")

AnalyticsCatalogClient

An Apache Iceberg REST catalog client scoped to one analytics bucket, exposing the namespace and table operations the Supabase analytics endpoint (/storage/v1/iceberg) speaks. Obtain one via analyticsCatalog.

Most operations come in two flavours: a raw … variant returning the server’s JsonObject verbatim (forward-compatible with Iceberg fields not yet modeled) and a …Typed variant deserializing into a model. Prefer the typed variants unless you need a spec field not yet mapped. Namespaces are multi-level and modeled as List<String> (for example ["analytics", "sales"]). Every call returns a SupabaseResult.

getConfig / getConfigTyped

Loads the raw Iceberg catalog config (GET /v1/config) for this bucket. The config carries the defaults/overrides property maps, including the route prefix.

suspend fun getConfig(): SupabaseResult<JsonObject>
suspend fun getConfigTyped(): SupabaseResult<IcebergCatalogConfig>

Returns SupabaseResult<JsonObject> (raw) / SupabaseResult<IcebergCatalogConfig> (typed) — Success with the config, Failure on error.

val config = catalog.getConfigTyped()

listNamespaces / listNamespacesTyped

Lists namespaces under the catalog.

suspend fun listNamespaces(
    parent: List<String>? = null,
    pageToken: String? = null,
    pageSize: Int? = null,
): SupabaseResult<JsonObject>
suspend fun listNamespacesTyped(
    parent: List<String>? = null,
    pageToken: String? = null,
    pageSize: Int? = null,
): SupabaseResult<IcebergNamespaceListResponse>

• parent — restrict results to direct children of this namespace; null lists from the catalog root. Default null.
• pageToken — continuation token from a previous page. Default null.
• pageSize — maximum namespaces to return in this page. Default null.

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergNamespaceListResponse> — Success with the page, Failure on error.

val namespaces = catalog.listNamespacesTyped()

createNamespace / createNamespaceTyped

Creates a namespace with optional properties.

suspend fun createNamespace(
    namespace: List<String>,
    properties: Map<String, String> = emptyMap(),
): SupabaseResult<JsonObject>
suspend fun createNamespaceTyped(
    request: IcebergCreateNamespaceRequest,
): SupabaseResult<IcebergNamespaceMetadata>

• namespace — the multi-level namespace to create.
• properties — initial namespace properties; omitted from the body when empty. Default emptyMap().
• request — the typed request object (typed overload).

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergNamespaceMetadata> — Success on creation, Failure on error.

catalog.createNamespace(listOf("analytics", "sales"))

deleteNamespace

Drops a namespace from the catalog.

suspend fun deleteNamespace(namespace: List<String>): SupabaseResult<Unit>

• namespace — the namespace to drop.

Returns SupabaseResult<Unit> — Success on deletion, Failure if missing or still containing tables.

catalog.deleteNamespace(listOf("analytics", "sales"))

getNamespaceMetadata / getNamespaceMetadataTyped

Loads a namespace’s metadata (its property map).

suspend fun getNamespaceMetadata(namespace: List<String>): SupabaseResult<JsonObject>
suspend fun getNamespaceMetadataTyped(namespace: List<String>): SupabaseResult<IcebergNamespaceMetadata>

• namespace — the namespace to inspect.

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergNamespaceMetadata> — Success with the metadata, Failure on error.

val meta = catalog.getNamespaceMetadataTyped(listOf("analytics", "sales"))

updateNamespaceProperties / updateNamespacePropertiesTyped

Adds/updates and/or removes properties on a namespace in one call.

suspend fun updateNamespaceProperties(
    namespace: List<String>,
    removals: List<String>? = null,
    updates: Map<String, String>? = null,
): SupabaseResult<JsonObject>
suspend fun updateNamespacePropertiesTyped(
    namespace: List<String>,
    request: IcebergUpdateNamespacePropertiesRequest,
): SupabaseResult<IcebergUpdateNamespacePropertiesResponse>

• namespace — the namespace to mutate.
• removals — property keys to remove. Default null.
• updates — property keys to set or overwrite. Default null.
• request — the typed request object (typed overload).

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergUpdateNamespacePropertiesResponse> — Success reporting removed/updated/missing keys, Failure on error.

catalog.updateNamespaceProperties(
    listOf("analytics", "sales"), updates = mapOf("owner" to "data-team"),
)

listTables / listTablesTyped

Lists the tables in a namespace.

suspend fun listTables(
    namespace: List<String>,
    pageToken: String? = null,
    pageSize: Int? = null,
): SupabaseResult<JsonObject>
suspend fun listTablesTyped(
    namespace: List<String>,
    pageToken: String? = null,
    pageSize: Int? = null,
): SupabaseResult<IcebergTableListResponse>

• namespace — the namespace to list.
• pageToken — continuation token from a previous page. Default null.
• pageSize — maximum table identifiers to return. Default null.

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergTableListResponse> — Success with the page, Failure on error.

val tables = catalog.listTablesTyped(listOf("analytics", "sales"))

createTable / createTableTyped

Creates a table in a namespace.

suspend fun createTable(
    namespace: List<String>,
    request: JsonObject,
): SupabaseResult<JsonObject>
suspend fun createTableTyped(
    namespace: List<String>,
    request: IcebergTableCreateRequest,
): SupabaseResult<IcebergTableMetadataResponse>

• namespace — the target namespace.
• request — the create-table body (raw JsonObject, or typed IcebergTableCreateRequest).

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergTableMetadataResponse> — Success with the table metadata, Failure on error.

val table = catalog.createTableTyped(
    listOf("analytics", "sales"),
    IcebergTableCreateRequest(name = "orders", schema = schemaJson),
)

updateTable / updateTableTyped

Commits requirements/updates to a table (the Iceberg commit-table endpoint).

suspend fun updateTable(
    namespace: List<String>,
    name: String,
    request: JsonObject,
): SupabaseResult<JsonObject>
suspend fun updateTableTyped(
    namespace: List<String>,
    name: String,
    request: IcebergTableCommitRequest,
): SupabaseResult<IcebergTableMetadataResponse>

• namespace — the table’s namespace.
• name — the table name.
• request — the commit body (raw JsonObject, or typed IcebergTableCommitRequest of requirements + updates).

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergTableMetadataResponse> — Success with updated metadata, Failure on error.

catalog.updateTableTyped(listOf("analytics", "sales"), "orders", commitRequest)

deleteTable

Drops a table from a namespace.

suspend fun deleteTable(
    namespace: List<String>,
    name: String,
    purge: Boolean = false,
): SupabaseResult<Unit>

• namespace — the table’s namespace.
• name — the table to drop.
• purge — when true, ask the server to also delete the table’s underlying data files. Default false.

Returns SupabaseResult<Unit> — Success on deletion, Failure on error.

catalog.deleteTable(listOf("analytics", "sales"), "orders", purge = true)

getTable / getTableTyped

Loads a table’s current metadata.

suspend fun getTable(
    namespace: List<String>,
    name: String,
    snapshots: String? = null,
): SupabaseResult<JsonObject>
suspend fun getTableTyped(
    namespace: List<String>,
    name: String,
    snapshots: String? = null,
): SupabaseResult<IcebergTableMetadataResponse>

• namespace — the table’s namespace.
• name — the table name.
• snapshots — optional snapshot-loading mode passed through to the server. Default null.

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergTableMetadataResponse> — Success with the metadata, Failure on error.

val table = catalog.getTableTyped(listOf("analytics", "sales"), "orders")

registerTable / registerTableTyped

Registers an existing table (one whose metadata file already lives in storage) into a namespace.

suspend fun registerTable(
    namespace: List<String>,
    request: JsonObject,
): SupabaseResult<JsonObject>
suspend fun registerTableTyped(
    namespace: List<String>,
    request: IcebergTableRegisterRequest,
): SupabaseResult<IcebergTableMetadataResponse>

• namespace — the target namespace.
• request — the register body (raw JsonObject, or typed IcebergTableRegisterRequest of name + metadata location).

Returns SupabaseResult<JsonObject> / SupabaseResult<IcebergTableMetadataResponse> — Success with the table metadata, Failure on error.

catalog.registerTableTyped(
    listOf("analytics", "sales"),
    IcebergTableRegisterRequest(name = "orders", metadataLocation = location),
)

renameTable / renameTableTyped

Renames/moves a table, optionally across namespaces.

suspend fun renameTable(request: JsonObject): SupabaseResult<Unit>
suspend fun renameTableTyped(
    source: IcebergTableIdentifier,
    destination: IcebergTableIdentifier,
): SupabaseResult<Unit>

• request — raw body holding source/destination identifiers (raw overload).
• source — the table to move (typed overload).
• destination — the new identifier (may live in a different namespace).

Returns SupabaseResult<Unit> — Success on rename, Failure on error.

catalog.renameTableTyped(
    IcebergTableIdentifier(listOf("analytics", "sales"), "orders"),
    IcebergTableIdentifier(listOf("analytics", "sales"), "orders_v2"),
)

Vectors (S3-Vectors)

The S3-Vectors surface manages vector buckets, indexes, and the vectors within them.

createVectorBucket

Creates an S3-Vectors bucket.

suspend fun createVectorBucket(vectorBucketName: String): SupabaseResult<Unit>

• vectorBucketName — the bucket name.

Returns SupabaseResult<Unit> — Success on creation, Failure on error.

storage.createVectorBucket("embeddings")

getVectorBucket

Fetches an S3-Vectors bucket.

suspend fun getVectorBucket(vectorBucketName: String): SupabaseResult<VectorBucket>

Returns SupabaseResult<VectorBucket> — Success with the bucket, Failure if it does not exist.

val bucket = storage.getVectorBucket("embeddings")

listVectorBuckets

Lists S3-Vectors buckets.

suspend fun listVectorBuckets(
    prefix: String? = null,
    maxResults: Int? = null,
    nextToken: String? = null,
): SupabaseResult<VectorBucketListResponse>

• prefix — restrict results to bucket names starting with this prefix. Default null.
• maxResults — maximum buckets to return in this page. Default null.
• nextToken — continuation token from a previous response. Default null.

Returns SupabaseResult<VectorBucketListResponse> — Success with the page, Failure on error.

val buckets = storage.listVectorBuckets()

deleteVectorBucket

Deletes an S3-Vectors bucket.

suspend fun deleteVectorBucket(vectorBucketName: String): SupabaseResult<Unit>

Returns SupabaseResult<Unit> — Success on deletion, Failure on error.

storage.deleteVectorBucket("embeddings")

createVectorIndex

Creates a vector index inside a bucket.

suspend fun createVectorIndex(
    vectorBucketName: String,
    indexName: String,
    dataType: VectorDataType,
    dimension: Int,
    distanceMetric: VectorDistanceMetric,
    metadataConfiguration: VectorMetadataConfiguration? = null,
): SupabaseResult<Unit>

• vectorBucketName — the owning bucket.
• indexName — the index name.
• dataType — element type of stored vectors (see VectorDataType).
• dimension — fixed dimensionality every stored vector must match.
• distanceMetric — similarity metric used for queries (see VectorDistanceMetric).
• metadataConfiguration — optional declaration of non-filterable metadata keys. Default null.

Returns SupabaseResult<Unit> — Success on creation, Failure on error.

storage.createVectorIndex(
    "embeddings", "docs",
    dataType = VectorDataType.FLOAT32,
    dimension = 1536,
    distanceMetric = VectorDistanceMetric.COSINE,
)

getVectorIndex

Fetches a vector index, including its dimension and metric.

suspend fun getVectorIndex(
    vectorBucketName: String,
    indexName: String,
): SupabaseResult<VectorIndex>

Returns SupabaseResult<VectorIndex> — Success with the index, Failure on error.

val index = storage.getVectorIndex("embeddings", "docs")

listVectorIndexes

Lists the vector indexes in a bucket.

suspend fun listVectorIndexes(
    vectorBucketName: String,
    prefix: String? = null,
    maxResults: Int? = null,
    nextToken: String? = null,
): SupabaseResult<VectorIndexListResponse>

• vectorBucketName — the bucket to list.
• prefix — restrict results to index names starting with this prefix. Default null.
• maxResults — maximum indexes to return in this page. Default null.
• nextToken — continuation token from a previous response. Default null.

Returns SupabaseResult<VectorIndexListResponse> — Success with the page, Failure on error.

val indexes = storage.listVectorIndexes("embeddings")

deleteVectorIndex

Deletes a vector index from a bucket.

suspend fun deleteVectorIndex(
    vectorBucketName: String,
    indexName: String,
): SupabaseResult<Unit>

Returns SupabaseResult<Unit> — Success on deletion, Failure on error.

storage.deleteVectorIndex("embeddings", "docs")

putVectors

Inserts or overwrites vectors in an index. The batch must contain between 1 and 500 vectors; an out-of-range size throws IllegalArgumentException before any request is sent.

suspend fun putVectors(
    vectorBucketName: String,
    indexName: String,
    vectors: List<VectorObject>,
): SupabaseResult<Unit>

• vectorBucketName — the owning bucket.
• indexName — the target index.
• vectors — 1..500 VectorObject entries to store.

Returns SupabaseResult<Unit> — Success on write, Failure on error.

storage.putVectors(
    "embeddings", "docs",
    listOf(VectorObject(key = "doc-1", data = VectorData(floats))),
)

getVectors

Fetches vectors by key.

suspend fun getVectors(
    vectorBucketName: String,
    indexName: String,
    keys: List<String>,
    returnData: Boolean? = null,
    returnMetadata: Boolean? = null,
): SupabaseResult<List<VectorMatch>>

• vectorBucketName / indexName — the index to read from.
• keys — the vector keys to fetch.
• returnData — when true, include each vector’s raw data. Default null.
• returnMetadata — when true, include each vector’s metadata. Default null.

Returns SupabaseResult<List<VectorMatch>> — Success with the matches, Failure on error.

val vectors = storage.getVectors("embeddings", "docs", listOf("doc-1"), returnData = true)

listVectors

Lists vectors in an index, optionally sharded for parallel scans.

suspend fun listVectors(
    vectorBucketName: String,
    indexName: String,
    maxResults: Int? = null,
    nextToken: String? = null,
    returnData: Boolean? = null,
    returnMetadata: Boolean? = null,
    segmentCount: Int? = null,
    segmentIndex: Int? = null,
): SupabaseResult<VectorListResponse>

• vectorBucketName / indexName — the index to scan.
• maxResults — maximum vectors to return in this page. Default null.
• nextToken — continuation token from a previous response. Default null.
• returnData — include each vector’s raw data. Default null.
• returnMetadata — include each vector’s metadata. Default null.
• segmentCount — split the index into this many segments (1..16) for parallel listing; out-of-range values throw IllegalArgumentException. Default null.
• segmentIndex — which segment (0 until segmentCount) this call scans. Default null.

Returns SupabaseResult<VectorListResponse> — Success with the page, Failure on error.

val page = storage.listVectors("embeddings", "docs", maxResults = 100)

queryVectors

Runs a nearest-neighbor search against an index.

suspend fun queryVectors(
    vectorBucketName: String,
    indexName: String,
    queryVector: VectorData,
    topK: Int? = null,
    filter: JsonObject? = null,
    returnDistance: Boolean? = null,
    returnMetadata: Boolean? = null,
): SupabaseResult<VectorQueryResponse>

• vectorBucketName / indexName — the index to query.
• queryVector — the query VectorData.
• topK — number of closest matches to return. Default null.
• filter — optional metadata filter expression to restrict candidates. Default null.
• returnDistance — include each match’s distance score. Default null.
• returnMetadata — include each match’s metadata. Default null.

Returns SupabaseResult<VectorQueryResponse> — Success with ranked matches, Failure on error.

val results = storage.queryVectors(
    "embeddings", "docs", VectorData(queryFloats), topK = 5, returnDistance = true,
)

deleteVectors

Deletes vectors by key. The batch must contain between 1 and 500 keys; an out-of-range size throws IllegalArgumentException before any request is sent.

suspend fun deleteVectors(
    vectorBucketName: String,
    indexName: String,
    keys: List<String>,
): SupabaseResult<Unit>

• vectorBucketName / indexName — the index to delete from.
• keys — 1..500 vector keys to remove.

Returns SupabaseResult<Unit> — Success on deletion, Failure on error.

storage.deleteVectors("embeddings", "docs", listOf("doc-1"))

Resumable uploads

ResumableUpload

A resumable (TUS) upload handle returned by createResumableUpload. Uploads in chunks with server-side offset tracking, so an interrupted upload resumes from where it stopped. To pause, cancel the coroutine running await; to resume — even after an app restart — persist uploadUrl and create a new handle with createResumableUpload(..., uploadUrl = saved), then call await again.

interface ResumableUpload {
    val uploadUrl: String?
    val progress: StateFlow<ResumableUploadProgress>
    suspend fun await(): SupabaseResult<Unit>
}

• uploadUrl — the TUS upload URL once the upload has been created (null beforehand). Persist this to resume later.
• progress — a StateFlow of ResumableUploadProgress, updated after every chunk.
• await() — runs (or resumes) the upload to completion; cancellable. Returns SupabaseResult<Unit> — Success when complete, Failure on error.

val handle = storage.createResumableUpload("videos", "clip.mp4", videoBytes)
launch { handle.progress.collect { println(it.fraction) } }
handle.await()

ResumableUploadProgress

Progress of a ResumableUpload.

data class ResumableUploadProgress(
    val bytesUploaded: Long,
    val totalBytes: Long,
) {
    val fraction: Float       // completion in 0f..1f
    val isComplete: Boolean
}

• bytesUploaded — bytes uploaded so far.
• totalBytes — total bytes to upload.
• fraction — completion fraction in 0f..1f (0f when totalBytes <= 0).
• isComplete — true once bytesUploaded >= totalBytes (and totalBytes > 0).

RESUMABLE_DEFAULT_CHUNK_SIZE

The default and recommended chunk size for resumable uploads. Supabase requires 6 MiB chunks for every part except the last.

const val RESUMABLE_DEFAULT_CHUNK_SIZE: Int = 6 * 1024 * 1024

Models

Bucket

A storage bucket as returned by the bucket endpoints.

data class Bucket(
    val id: String,
    val name: String,
    val public: Boolean = false,
    val createdAt: String? = null,
    val updatedAt: String? = null,
    val fileSizeLimit: Long? = null,
    val allowedMimeTypes: List<String>? = null,
)

• id — the bucket’s stable identifier and URL segment.
• name — human-readable bucket name.
• public — whether objects are readable via the public endpoint without a token.
• createdAt / updatedAt — timestamps, when reported by the server.
• fileSizeLimit — per-object size cap in bytes, when set.
• allowedMimeTypes — whitelist of accepted content types, when set; null allows any.

FileObject

A file or folder entry returned by the storage server. For folders, every field except name is typically null. The trailing fields (size, contentType, etag, lastAccessedAt, cacheControl) are populated by object-info and v2 listing endpoints; older list responses omit them.

data class FileObject(
    val name: String,
    val id: String? = null,
    val bucketId: String? = null,
    val createdAt: String? = null,
    val updatedAt: String? = null,
    val metadata: JsonObject? = null,
    val size: Long? = null,
    val contentType: String? = null,
    val etag: String? = null,
    val lastAccessedAt: String? = null,
    val cacheControl: String? = null,
)

• name — the object name (or folder name).
• id — the object id, when present.
• bucketId — the id of the owning bucket, when present.
• createdAt / updatedAt / lastAccessedAt — timestamps, when present.
• metadata — free-form server metadata, when present.
• size — the object size in bytes, when reported.
• contentType — the stored MIME type, when reported.
• etag — the entity tag, when reported.
• cacheControl — the stored cache-control directive, when reported.

ObjectListV2Response

Result of a cursor-paged v2 listing (listV2), separating folders from objects and carrying continuation state.

data class ObjectListV2Response(
    val hasNext: Boolean,
    val folders: List<ObjectListV2Folder>,
    val objects: List<ObjectListV2Object>,
    val nextCursor: String? = null,
)

• hasNext — whether more pages remain.
• folders — the folder (common-prefix) entries in this page.
• objects — the object entries in this page.
• nextCursor — cursor to pass back for the next page, when hasNext.

ObjectListV2Object

A single object entry in a v2 listing.

data class ObjectListV2Object(
    val name: String,
    val key: String? = null,
    val id: String,
    val updatedAt: String? = null,
    val createdAt: String? = null,
    val lastAccessedAt: String? = null,
    val metadata: JsonObject? = null,
)

• name — the object name within its folder.
• key — the full object key, when reported.
• id — the object id.
• updatedAt / createdAt / lastAccessedAt — timestamps, when reported.
• metadata — free-form server metadata, when present.

ObjectListV2Folder

A folder (common-prefix) entry in a v2 listing.

data class ObjectListV2Folder(
    val name: String,
    val key: String? = null,
)

• name — the folder name.
• key — the full prefix, when reported.

AnalyticsBucket

An analytics (Iceberg) bucket.

data class AnalyticsBucket(
    val name: String,
    val type: String,
    val format: String,
    val createdAt: String? = null,
    val updatedAt: String? = null,
)

• name — the analytics bucket name.
• type — the server-reported bucket type.
• format — the table data format (e.g. Iceberg).
• createdAt / updatedAt — timestamps, when reported.

UploadSignedUrl

A signed upload target returned by createSignedUploadUrlWithPath.

data class UploadSignedUrl(
    val url: String,
    val token: String,
    val path: String? = null,
)

• url — the absolute URL to upload to.
• token — the signed token authorizing the upload.
• path — the object path the server bound to this token, when returned.

ImageTransformOptions

Server-side image transform options applied by the render endpoints and by signed/public render URLs. Each field maps to a render query param; null fields are omitted, leaving the server default.

data class ImageTransformOptions(
    val width: Int? = null,
    val height: Int? = null,
    val resize: ResizeMode? = null,
    val format: String? = null,
    val quality: Int? = null,
)

• width — target width in pixels.
• height — target height in pixels.
• resize — how the image is fitted to width/height (see ResizeMode).
• format — output format (e.g. origin, webp); server-defined values.
• quality — output quality, typically 1..100 for lossy formats.

ResizeMode

How a transformed image is fitted to the requested width/height. value is the literal sent to the render endpoint.

enum class ResizeMode(val value: String) {
    COVER("cover"),       // fill the box, cropping overflow (preserves aspect ratio)
    CONTAIN("contain"),   // fit within the box, letterboxing (preserves aspect ratio)
    FILL("fill"),         // stretch to the box, ignoring aspect ratio
}

SortOrder

Sort direction for listing operations. value is the literal sent to the storage API.

enum class SortOrder(val value: String) {
    ASC("asc"),
    DESC("desc"),
}

Iceberg catalog models

IcebergCatalogConfig

Iceberg catalog configuration (GET /v1/config). overrides take precedence over defaults; both may carry the route prefix the catalog client uses.

data class IcebergCatalogConfig(
    val defaults: Map<String, String> = emptyMap(),
    val overrides: Map<String, String> = emptyMap(),
)

• defaults — default catalog properties.
• overrides — overriding catalog properties (take precedence over defaults).

IcebergNamespaceListResponse

Response listing Iceberg namespaces, each a multi-level path.

data class IcebergNamespaceListResponse(
    val namespaces: List<List<String>> = emptyList(),
    val nextPageToken: String? = null,            // "next-page-token"
    val nextPageTokenCamelCase: String? = null,   // "nextPageToken"
) {
    val resolvedNextPageToken: String?
}