Skip to main content

Store your first file with TaruviBase Storage

Create a test bucket, upload a file, download it, and clean up. Choose an interface at each step.

Before you start#

You need:

  • A TaruviBase app. Create one if needed.
  • An API key from an organization owner or admin. In the Console, open your app's Settings → Connect, select Generate API Key, and copy the values from the Environment tab. Creating and deleting buckets requires this level of access.
  • For SDK examples, a configured JavaScript client or synchronous Python client.
  • For Refine examples, the named storage provider. Initialize hooks inside a React component or custom hook under <Refine> with a signed-in user session.
  • For REST examples, curl. Keep API keys in your shell or server code; browser JavaScript and Refine examples use the signed-in user session.

Set these in your shell for the REST examples:

export TARUVI_SITE_URL="https://YOUR_SITE_HOST"
export TARUVI_APP_SLUG="APP_SLUG"
printf 'TaruviBase API key: ' && read -rs TARUVI_API_KEY && export TARUVI_API_KEY && printf '\n'

Step 1: Create a bucket#

client.storage.create_bucket(
    "Quickstart scratch", visibility="private", app_category="attachments",
)

app_category is required. An attachments bucket lets signed-in users read, upload, and update files, which is enough for this tutorial.

Either way, the bucket gets a slug derived from its name — here quickstart-scratch. The API response includes it. Save it for the next steps:

export BUCKET_SLUG="quickstart-scratch"

The SDK and Refine examples below use quickstart-scratch. Substitute the slug returned for your bucket if it differs.

Checkpoint: GET .../storage/buckets/${BUCKET_SLUG}/ returns 200 with "visibility": "private" and "storage_provider": "s3". Python can read the same details with client.storage.get_bucket("quickstart-scratch").

Step 2: Upload a file#

Use a small text file named hello.txt.

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

await new Storage(client).from('quickstart-scratch').upload({
  files: [file], paths: ['hello.txt'], metadatas: [{purpose: 'quickstart'}],
}).execute<StorageUploadBatchResponse>();

file is your text file as a browser File. Check the response’s data.failed list for per-file errors.

The supplied path (hello.txt) becomes the file's path in the bucket.

Checkpoint: REST returns 201 Created for a new file. SDK uploads use the batch endpoint, which returns 200 or 207; confirm the failed list is empty. The stored object's details include file_path (hello.txt), size, mimetype (text/plain), and your metadata.

Step 3: Download the file#

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

await new Storage(client).from('quickstart-scratch')
  .download('hello.txt').execute<Blob>();

The method returns a Blob. Compare its bytes with the file you uploaded.

To read only the file's details, add ?metadata=true:

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

await new Storage(client).from('quickstart-scratch')
  .metadata('hello.txt').execute<StorageResponse>();

The response’s data.metadata contains the saved metadata.

Checkpoint: the downloaded bytes match, and the details include "purpose": "quickstart" and "visibility": "private" (a file's visibility always follows its bucket).

Step 4: Clean up#

Deleting a bucket removes every file in it

Deleting a bucket is permanent. This tutorial bucket should contain only hello.txt.

Delete the bucket, which also deletes hello.txt:

client.storage.delete_bucket("quickstart-scratch")

Deleting a single file instead requires a policy rule that allows delete, which no default bucket policy includes. See Security and limits.

Checkpoint: GET .../storage/buckets/${BUCKET_SLUG}/ now returns 404.

If you followed the REST path, remove the two local test files:

rm hello.txt hello.out.txt

What's next#