# Tigris Object Operations

## When to use[​](#when-to-use "Direct link to When to use")

Use when working with objects in Tigris Storage - uploading, downloading, deleting, listing, getting metadata, or generating presigned URLs

## Install the skill[​](#install-the-skill "Direct link to Install the skill")

```
npx skills add tigrisdata/skills --skill tigris-object-operations
```

This page is generated from [`skills/tigris-object-operations/SKILL.md`](https://github.com/tigrisdata/skills/blob/main/skills/tigris-object-operations/SKILL.md) in the [tigrisdata/skills](https://github.com/tigrisdata/skills) repository.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

**Before doing anything else**, install the Tigris CLI if it's not already available:

```
tigris help || npm install -g @tigrisdata/cli
```

If you need to install it, tell the user: "I'm installing the Tigris CLI (`@tigrisdata/cli`) so we can work with Tigris object storage."

## Overview[​](#overview "Direct link to Overview")

Tigris Storage provides object operations: upload (put), download (get), delete (remove), list, metadata (head), and presigned URLs.

All methods return `TigrisStorageResponse<T, E>` - check `error` property first.

## Quick Reference[​](#quick-reference "Direct link to Quick Reference")

| Operation     | Function                         | Key Parameters                    |
| ------------- | -------------------------------- | --------------------------------- |
| Upload        | `put(path, body, options)`       | path, body, access, contentType   |
| Download      | `get(path, format, options)`     | path, format (string/file/stream) |
| Delete        | `remove(path, options)`          | path                              |
| List          | `list(options)`                  | prefix, limit, paginationToken    |
| Metadata      | `head(path, options)`            | path                              |
| Presigned URL | `getPresignedUrl(path, options)` | path, operation (get/put)         |

## Upload (put)[​](#upload-put "Direct link to Upload (put)")

```
import { put } from "@tigrisdata/storage";



// Simple upload

const result = await put("simple.txt", "Hello, World!");

if (result.error) {

  console.error("Error:", result.error);

} else {

  console.log("Uploaded:", result.data?.url);

}



// Large file with progress

const result = await put("large.mp4", fileStream, {

  multipart: true,

  onUploadProgress: ({ loaded, total, percentage }) => {

    console.log(`${loaded}/${total} bytes (${percentage}%)`);

  },

});



// Prevent overwrite

const result = await put("config.json", config, {

  allowOverwrite: false,

});
```

## Put Options[​](#put-options "Direct link to Put Options")

| Option             | Values            | Default  | Purpose                  |
| ------------------ | ----------------- | -------- | ------------------------ |
| access             | public/private    | -        | Object visibility        |
| addRandomSuffix    | boolean           | false    | Avoid naming collisions  |
| allowOverwrite     | boolean           | true     | Allow replacing existing |
| contentType        | string            | inferred | MIME type                |
| contentDisposition | inline/attachment | inline   | Download behavior        |
| multipart          | boolean           | false    | Enable for large files   |
| onUploadProgress   | callback          | -        | Track upload progress    |

## Download (get)[​](#download-get "Direct link to Download (get)")

```
import { get } from "@tigrisdata/storage";



// Get as string

const result = await get("object.txt", "string");

if (result.error) {

  console.error("Error:", result.error);

} else {

  console.log("Content:", result.data);

}



// Get as file (triggers download in browser)

const result = await get("object.pdf", "file", {

  contentDisposition: "attachment",

});



// Get as stream

const result = await get("video.mp4", "stream");

const reader = result.data?.getReader();

// Process stream...
```

## Get Options[​](#get-options "Direct link to Get Options")

| Option             | Values            | Default     | Purpose            |
| ------------------ | ----------------- | ----------- | ------------------ |
| contentDisposition | inline/attachment | inline      | Download behavior  |
| contentType        | string            | from upload | MIME type          |
| encoding           | string            | utf-8       | Text encoding      |
| snapshotVersion    | string            | -           | Read from snapshot |

## Delete (remove)[​](#delete-remove "Direct link to Delete (remove)")

```
import { remove } from "@tigrisdata/storage";



const result = await remove("object.txt");

if (result.error) {

  console.error("Error:", result.error);

} else {

  console.log("Deleted successfully");

}
```

## List Objects[​](#list-objects "Direct link to List Objects")

```
import { list } from "@tigrisdata/storage";



// List all objects

const result = await list();

console.log("Objects:", result.data?.items);



// List with prefix (folders)

const result = await list({ prefix: "images/" });



// List with pagination

const allFiles = [];

let currentPage = await list({ limit: 10 });

allFiles.push(...currentPage.data?.items);



while (currentPage.data?.hasMore) {

  currentPage = await list({

    limit: 10,

    paginationToken: currentPage.data?.paginationToken,

  });

  allFiles.push(...currentPage.data?.items);

}
```

## List Options[​](#list-options "Direct link to List Options")

| Option          | Purpose                              |
| --------------- | ------------------------------------ |
| prefix          | Filter keys starting with prefix     |
| delimiter       | Group keys (e.g., '/' for folders)   |
| limit           | Max objects to return (default: 100) |
| paginationToken | Continue from previous list          |
| snapshotVersion | List from snapshot                   |

## Object Metadata (head)[​](#object-metadata-head "Direct link to Object Metadata (head)")

```
import { head } from "@tigrisdata/storage";



const result = await head("object.txt");

if (result.error) {

  console.error("Error:", result.error);

} else {

  console.log("Metadata:", result.data);

  // { path, size, contentType, modified, url, contentDisposition }

}
```

## Presigned URLs[​](#presigned-urls "Direct link to Presigned URLs")

```
import { getPresignedUrl } from "@tigrisdata/storage";



// Presigned URL for GET (temporary access)

const result = await getPresignedUrl("object.txt", {

  operation: "get",

  expiresIn: 3600, // 1 hour

});

console.log("URL:", result.data?.url);



// Presigned URL for PUT (allow client upload)

const result = await getPresignedUrl("upload.txt", {

  operation: "put",

  expiresIn: 600, // 10 minutes

});
```

## Presigned URL Options[​](#presigned-url-options "Direct link to Presigned URL Options")

| Option      | Values  | Default | Purpose         |
| ----------- | ------- | ------- | --------------- |
| operation   | get/put | -       | URL purpose     |
| expiresIn   | seconds | 3600    | URL expiration  |
| contentType | string  | -       | Require for PUT |

## Common Mistakes[​](#common-mistakes "Direct link to Common Mistakes")

| Mistake                      | Fix                                                   |
| ---------------------------- | ----------------------------------------------------- |
| Not checking `error` first   | Always check `if (result.error)` before `result.data` |
| Wrong format in `get()`      | Use 'string', 'file', or 'stream'                     |
| Forgetting `multipart: true` | Enable for files >100MB                               |
| Ignoring pagination          | Use `hasMore` and `paginationToken`                   |

## Client-Side Uploads[​](#client-side-uploads "Direct link to Client-Side Uploads")

For browser uploads, use the client package to upload directly to Tigris:

```
import { upload } from "@tigrisdata/storage/client";



const result = await upload(file.name, file, {

  url: "/api/upload", // Your backend endpoint

  onUploadProgress: ({ percentage }) => {

    console.log(`${percentage}%`);

  },

});
```

For initial setup, see **file-storage**.
