Docs
⌘K

JavaScript: Storage

Create buckets, upload and download files, list and move objects, and hand out public or signed URLs with @sovaria/sdk.

Updated Oct 16, 2026

sovaria.storage stores files in buckets. Each bucket has rules (who may read and write which paths), a size limit and allowed types; a public bucket's files have permanent URLs, a private bucket's files are read through the API or a time-limited signed URL.

import { createClient } from '@sovaria/sdk'

const sovaria = createClient('https://<project-ref>.sovaria.in', '<anon-key>')

const user = sovaria.auth.getSession()?.user
await sovaria.storage.upload('avatars', `${user.id}/avatar.png`, file, { upsert: true, contentType: 'image/png' })

// public bucket: a permanent URL
img.src = sovaria.storage.publicUrl('avatars', `${user.id}/avatar.png`)

// private bucket: a link that works for one hour
const { url } = await sovaria.storage.signDownload('invoices', `${user.id}/2026-10.pdf`, 3600)

sovaria.storage

sovaria.storage.request

Request.

sovaria.storage.request(
  method: string,
  path: string,
  options?: RequestOptions = {},
): Promise<JsonValue>

Parameters

methodstringrequired
pathstringrequired
optionsRequestOptionsoptionaldefault {}
Returns
Promise<JsonValue>

sovaria.storage.putJson

Put json.

sovaria.storage.putJson(path: string, payload: JsonObject): Promise<JsonValue>

Parameters

pathstringrequired
payloadJsonObjectrequired
Returns
Promise<JsonValue>
HTTP
POST /api/v1/store/{…}

sovaria.storage.get

Get.

sovaria.storage.get(
  path: string,
  query?: Record<string, string | number | boolean | null | undefined>,
): Promise<JsonValue>

Parameters

pathstringrequired
queryRecord<string, string | number | boolean | null | undefined>optional
Returns
Promise<JsonValue>
HTTP
GET /api/v1/store/{…}

sovaria.storage.delete

Delete.

sovaria.storage.delete(path: string): Promise<JsonValue>

Parameters

pathstringrequired
Returns
Promise<JsonValue>
HTTP
DELETE /api/v1/store/{…}

sovaria.storage.publicUrl

Public URL of an object in a public bucket (no token needed; safe to put in <img src>).

sovaria.storage.publicUrl(bucket: string, objectPath: string, projectId?: string): string

Parameters

bucketstringrequired
A public bucket.
objectPathstringrequired
Object path.
projectIdstringoptional
Only when the client has no project scope.
Returns
string — A permanent URL string. No network call.

sovaria.storage.listBuckets

List buckets.

sovaria.storage.listBuckets(): Promise<JsonValue>
Returns
Promise<JsonValue>
HTTP
GET /api/v1/store/buckets

sovaria.storage.createBucket

Create bucket.

sovaria.storage.createBucket(body: JsonObject): Promise<JsonObject>

Parameters

bodyJsonObjectrequired
name, public (boolean), optional file_size_limit (bytes) and allowed_mime_types.
Returns
Promise<JsonObject>
HTTP
POST /api/v1/store/buckets
await sovaria.storage.createBucket({ name: 'avatars', public: true, file_size_limit: 2_000_000, allowed_mime_types: ['image/png', 'image/jpeg'] })

sovaria.storage.getBucket

Get bucket.

sovaria.storage.getBucket(name: string): Promise<JsonObject>

Parameters

namestringrequired
Returns
Promise<JsonObject>
HTTP
GET /api/v1/store/buckets/{…}

sovaria.storage.updateBucket

Update bucket.

sovaria.storage.updateBucket(name: string, body: JsonObject): Promise<JsonObject>

Parameters

namestringrequired
bodyJsonObjectrequired
Returns
Promise<JsonObject>
HTTP
PATCH /api/v1/store/buckets/{…}

sovaria.storage.deleteBucket

Delete bucket.

sovaria.storage.deleteBucket(name: string): Promise<JsonObject>

Parameters

namestringrequired
Returns
Promise<JsonObject>
HTTP
DELETE /api/v1/store/buckets/{…}

sovaria.storage.listObjects

List objects.

sovaria.storage.listObjects(bucket: string, query?: { prefix?: string }): Promise<JsonValue>

Parameters

bucketstringrequired
query{ prefix?: string }optional
prefix: only objects under this folder.
Returns
Promise<JsonValue>
HTTP
GET /api/v1/store/objects/{…}

sovaria.storage.signDownload

Sign download.

sovaria.storage.signDownload(
  bucket: string,
  objectPath: string,
  expiresIn?: number = 3600,
): Promise<JsonObject>

Parameters

bucketstringrequired
objectPathstringrequired
expiresInnumberoptionaldefault 3600
Seconds the link stays valid.
Returns
Promise<JsonObject> — { url, expires_at }.
HTTP
POST /api/v1/store/objects/{…}/{…}/sign-download

sovaria.storage.signUpload

Sign upload.

sovaria.storage.signUpload(
  bucket: string,
  objectPath: string,
  expiresIn?: number = 3600,
): Promise<JsonObject>

Parameters

bucketstringrequired
objectPathstringrequired
expiresInnumberoptionaldefault 3600
Seconds the upload URL stays valid.
Returns
Promise<JsonObject> — A URL a browser can upload to directly, without your server in the middle.
HTTP
POST /api/v1/store/objects/{…}/{…}/sign-upload

sovaria.storage.moveObject

Move object.

sovaria.storage.moveObject(body: JsonObject): Promise<JsonObject>

Parameters

bodyJsonObjectrequired
Source and destination bucket/path.
Returns
Promise<JsonObject>
HTTP
POST /api/v1/store/objects/move

sovaria.storage.upload

Upload a file.

sovaria.storage.upload(
  bucket: string,
  objectPath: string,
  file: Blob,
  options?: { upsert?: boolean; contentType?: string } = {},
): Promise<JsonObject>

Bucket rules decide who may write where — e.g. with the "Own folder" rule a user writes to ${userId}/…. Pass upsert: true to replace an existing object.

Parameters

bucketstringrequired
Bucket name.
objectPathstringrequired
Path inside the bucket, e.g. <user-id>/avatar.png. Bucket rules often require the first folder to be the user's id.
fileBlobrequired
A Blob or File.
options{ upsert?: boolean; contentType?: string }optionaldefault {}
upsert: overwrite an existing object; contentType: MIME type stored with the object.
Returns
Promise<JsonObject>
HTTP
POST /api/v1/store/objects/{…}
  • Over the bucket's size limit or type list the server answers 413/415.

sovaria.storage.download

Download an object the caller may read, as a Blob.

sovaria.storage.download(bucket: string, objectPath: string): Promise<Blob>

Parameters

bucketstringrequired
objectPathstringrequired
Returns
Promise<Blob> — A Blob.
HTTP
GET /api/v1/store/objects/{…}
const blob = await sovaria.storage.download('invoices', path)
const href = URL.createObjectURL(blob)

sovaria.storage.remove

Delete an object.

sovaria.storage.remove(bucket: string, objectPath: string): Promise<JsonObject>

Parameters

bucketstringrequired
Bucket name.
objectPathstringrequired
Object path.
Returns
Promise<JsonObject>
HTTP
DELETE /api/v1/store/objects/{…}

Related

JavaScript SDKConnect your app
Something unclear or missing on this page?Tell us