Work with storage objects

Upload files, download them, update their metadata, and delete them. The examples use a bucket with slug BUCKET_SLUG and a file at users/123/avatar.png.

REST requests go to TARUVI_SITE_URL/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/ and use an Authorization: Api-Key TARUVI_API_KEY header. File URLs must end with a trailing slash, for example .../objects/users/123/avatar.png/.

Upload a file

REST API

Upload to a path in the URL with PUT:

curl -sS -X PUT "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/users/123/avatar.png/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -F "[email protected]" \
  -F 'metadata={"user_id":"123"}'

Or POST to the collection with the path as a form field:

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -F "[email protected]" \
  -F "path=users/123/avatar.png" \
  -F 'metadata={"user_id":"123"}'

To send raw bytes instead of a form, use PUT with the path in the URL and pass metadata as X-Metadata-* headers:

curl -sS -X PUT "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/users/123/avatar.png/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: image/png" \
  -H "X-Metadata-User-Id: 123" \
  --data-binary @avatar.png

JavaScript SDK

import {Storage} from '@taruvi/sdk';

const input = document.querySelector<HTMLInputElement>('#avatar')!;
const file = input.files![0];

await new Storage(client)
  .from('BUCKET_SLUG')
  .upload({
    files: [file],
    paths: ['users/123/avatar.png'],
    metadatas: [{user_id: '123'}],
  })
  .execute();

client is the Client you configured in JavaScript SDK. upload accepts several files at once; each file needs a matching path.

Python SDK

with open("avatar.png", "rb") as file:
    client.storage.from_("BUCKET_SLUG").upload(
        files=[("avatar.png", file)],
        paths=["users/123/avatar.png"],
        metadatas=[{"user_id": "123"}],
    )

upload accepts several files at once; each file needs a matching path.

A new file returns 201 Created; uploading to an existing path replaces the file. The response includes the file's path, size, mimetype, metadata, and effective visibility.

Uploads are rejected with 400 when:

• the file is empty;
• the file is larger than the bucket's file size limit;
• the bucket restricts file types and this type isn't allowed (wildcards such as image/* are supported);
• the metadata is larger than 2 KB.

Download a file

REST API

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/users/123/avatar.png/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -o avatar.out.png

Add ?metadata=true to get the file's details as JSON instead of its content.

JavaScript SDK

const blob = await new Storage(client)
  .from('BUCKET_SLUG')
  .download('users/123/avatar.png')
  .execute<Blob>();

Python SDK

content = client.storage.from_("BUCKET_SLUG").download("users/123/avatar.png")

download returns the file's bytes.

Anyone can download a public file without a credential. A private file needs a caller whom the bucket's policy allows to read it; otherwise the request returns 403. A 404 means no file exists at that path — paths are case-sensitive.

Update metadata

REST API

curl -sS -X PATCH "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/users/123/avatar.png/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"status":"verified"}}'

Python SDK

client.storage.from_("BUCKET_SLUG").update(
    "users/123/avatar.png",
    metadata={"status": "verified"},
)

PATCH changes details only. To replace the file itself, upload to the same path again. A file's visibility always follows its bucket; to change it, update the bucket's visibility.

Delete a file

REST API

curl -sS -X DELETE "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/users/123/avatar.png/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

JavaScript SDK

await new Storage(client)
  .from('BUCKET_SLUG')
  .delete(['users/123/avatar.png'])
  .execute();

Python SDK

client.storage.from_("BUCKET_SLUG").delete(["users/123/avatar.png"])

File deletion is permanent

Deleting removes the file from TaruviBase and from the storage provider. There is no recycle bin. The caller needs a policy rule that allows delete — neither default bucket policy includes one. See Security and limits.

Related pages

• Organize files — list, browse, search, copy, and move
• Batch and SharePoint — batch operations and Office editing
• REST reference — every endpoint
• Filter reference — list query parameters