Storage REST and filter reference
Every Storage endpoint belongs to one app and lives under TARUVI_SITE_URL/api/apps/APP_SLUG/storage/. Paths end with a trailing slash.
Authentication#
Send an API key (Authorization: Api-Key TARUVI_API_KEY), a user session token (X-Session-Token), or a JWT. See Authentication and authorization. Only downloading a public file, or listing the public files in a public bucket, works without a credential. Creating, updating, and deleting buckets requires an organization owner or admin, or another cloud user with access to the site.
Response envelope#
Successful responses include status, message, data, and total on lists. Errors return status: "error" with code and optional detail or field errors.
Bucket endpoints#
Base: /api/apps/APP_SLUG/storage/buckets/
| Method | Path | Purpose | Notes |
|---|---|---|---|
| GET | / | List buckets | Paginated; bucket list filters on the Filter grammar page |
| POST | / | Create bucket | app_category required; storage_provider can't change later |
| GET | /{slug}/ | Retrieve bucket | Includes usage and quota summary fields |
| PATCH | /{slug}/ | Update bucket | PUT isn't supported; provider can't change |
| DELETE | /{slug}/ | Delete bucket | Removes every file and the bucket's access policy |
| GET | /{slug}/usage/ | Quota and usage | Usage as of the last periodic recalculation |
Create and update fields (name, visibility, file_size_limit, allowed_mime_types, app_category, storage_provider, tags, max_size_bytes, max_objects) are described in Manage buckets. Examples are in Manage buckets.
Object endpoints#
Base: /api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/
| Method | Path | Purpose | Notes |
|---|---|---|---|
| GET | / | List objects | Paginated; object filters on Filter grammar |
| POST | / | Upload | Multipart form with file and path; see Work with objects |
| PUT | /{key}/ | Upload or replace | Multipart form or raw bytes |
| GET | /{key}/ | Download or metadata | ?metadata=true returns JSON instead of bytes |
| PATCH | /{key}/ | Update metadata | No file bytes on PATCH; visibility follows the bucket |
| DELETE | /{key}/ | Delete object | Needs a policy rule that allows delete |
Advanced actions (same base path):
| Method | Path | Purpose |
|---|---|---|
| GET | /browse/ | One-level folder listing |
| POST | /search/ | JSON search body |
| POST | /copy/ | Copy within the app |
| POST | /move/ | Rename or move; cross-provider move rejected |
| POST | /batch-upload/ | Up to 100 files, 800 MB total per request |
| POST | /batch-delete/ | Up to 100 paths per request |
| GET | /{key}/view/ | SharePoint view grant |
| GET | /{key}/edit/ | SharePoint edit grant (authenticated only) |
Batch and SharePoint flows are walkthroughs in Batch upload and SharePoint. Browse, search, and list filter parameters are fully documented under Filter grammar.
{key} is the file's path in the bucket and may contain slashes, for example /users/123/avatar.png/.
Status codes#
| Code | Typical cause |
|---|---|
| 200 | Success; batch operations when every item succeeded |
| 201 | New bucket or new object |
| 207 | Partial success on batch upload or batch delete |
| 400 | Validation (size, MIME, metadata, batch limits) |
| 401 | Missing, invalid, or expired credential |
| 403 | The caller isn't allowed to perform the action |
| 404 | Missing bucket or object |
| 409 | Move destination already exists |
| 402 | account_suspended: the organization's account isn't active |
| 429 | product_suspended: the plan's Storage usage for this period is used up. Uploads and copies are refused; reads, deletes, and moves still work |
| 503 | gate_unavailable: billing status couldn't be read; retry shortly |
Billing refusals carry detail, code, and module instead of the usual
envelope, and the SDKs raise BillingError.
Limits and security#
Size and batch limits are on Configured limits. Access layers, destructive actions, and tenancy boundaries are on Security and limits. Symptom tables are on Troubleshooting.