Storage APIs
Version: aju17f20mq
Use the reference below for request and response fields and operation-specific requirements.
Overview
Manage files and folders, issue signed upload/download URLs, and inspect tracked storage usage.
Authentication
User-facing calls act for the authenticated beneficiary. A backend sk_… key uses an authorized X-On-Behalf-Of selection with users:impersonate; a client pk_… key accompanies that user’s JWT from the configured issuer. Never expose a secret key in a client. Raw identity headers and recipient IDs are not authentication. See Authentication.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
Signed URLs are bearer credentials and can be reused until their expiry. An upload URL is followed by direct upload and registration; issuing the URL neither registers the file nor reserves quota. Registration checks the stored object’s size. Its MIME metadata is not content validation.
Related guide: Files and storage
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
Folders
Folder management — create and delete directory containers. See the Storage guide.
Uploads & Downloads
File upload (inline and pre-signed) and pre-signed download URLs. See the Storage guide for both inline and large-file patterns.
- Generate a pre-signed upload URL
- Register a file uploaded via pre-signed URL
- Generate a pre-signed download URL
- Generate pre-signed download URLs for multiple files
Files
File listing, search, move, and delete. See the Storage guide.
- List files and folders in a directory
- Upload a file (deprecated)
- Delete a file
- Move or rename a file
- Search files
Metadata
File metadata and tag management. See the Storage guide.
Quota & State
Storage quota usage and account state. See the Storage guide.
Server 1
Travila API
X-API-Key
Project/service API key. Use pk_… only with a verified end-user JWT; backend sk_… calls that require a user use authorized on-behalf-of context. Management operations can have different requirements; consult the operation and authentication guide.
X-On-Behalf-Of
The end user this call acts for. Required with an sk_… key, because a secret key identifies your tenant and not a user; omitting it returns 401 authenticated user_id is required. The key needs the users:impersonate scope or the call fails with 403 insufficient_scope.
Authorization: Bearer
The end user's own JWT, issued by the OIDC provider configured on the publishable key. Required alongside a pk_… key, and supplies the user identity in place of X-On-Behalf-Of.
Authentication credentials
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: bearerAuth
| Setting | Value |
|---|---|
| Security scheme type | apiKey |
| header parameter name | X-API-Key |
| Setting | Value |
|---|---|
| Security scheme type | apiKey |
| header parameter name | X-On-Behalf-Of |
| Setting | Value |
|---|---|
| Security scheme type | http |
| Scheme | bearer |
Operations
- Create a new folder —
POST /api/v1/storage/create-folder - Delete a folder —
POST /api/v1/storage/delete-folder - List files and folders in a directory —
POST /api/v1/storage/list-files - Upload a file (deprecated) —
POST /api/v1/storage/upload-file - Delete a file —
POST /api/v1/storage/delete-file - Move or rename a file —
POST /api/v1/storage/move-file - Get file metadata —
POST /api/v1/storage/get-file-metadata - Update file metadata —
POST /api/v1/storage/update-file-metadata - Get storage usage and quota —
POST /api/v1/storage/get-storage-quota - Search files —
POST /api/v1/storage/search-files - Generate a pre-signed upload URL —
POST /api/v1/storage/generate-upload-url - Register a file uploaded via pre-signed URL —
POST /api/v1/storage/register-uploaded-file - Generate a pre-signed download URL —
POST /api/v1/storage/generate-download-url - Generate pre-signed download URLs for multiple files —
POST /api/v1/storage/batch-generate-download-urls - Get storage state —
POST /api/v1/storage/get-state
Document ID: DOC-API-storage-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-API-storage-overview#overview |
| Authentication | DOC-API-storage-overview#authentication |
| JSON conventions | DOC-API-storage-overview#json-conventions |
| Folders | DOC-API-storage-overview#reference-group-1 |
| Uploads & Downloads | DOC-API-storage-overview#reference-group-2 |
| Files | DOC-API-storage-overview#reference-group-3 |
| Metadata | DOC-API-storage-overview#reference-group-4 |
| Quota & State | DOC-API-storage-overview#reference-group-5 |
| Server 1 | DOC-API-storage-overview#reference-server-1 |
| X-API-Key | DOC-API-storage-overview#authentication-apiKeyAuth |
| X-On-Behalf-Of | DOC-API-storage-overview#authentication-onBehalfOf |
| Authorization: Bearer | DOC-API-storage-overview#authentication-bearerAuth |