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 or viewing a public file 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 |
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.