Vestra API Reference
REST endpoints for all six storage providers, GCS, AWS / S3-Compatible, Azure Blob, Alibaba OSS, Huawei OBS, and Google Drive, plus auth, transfers, jobs and more
REST API Port 8080 6 Providers Back to Vestra DocsOn this page
Vestra DocsOverview
The Anveesa Vestra backend exposes a REST API on port 8080. All endpoints accept and return application/json, except uploads which use multipart/form-data. CORS is enabled for all origins by default.
Authentication is enabled by default. Most endpoints require an Authorization: Bearer <token> header obtained from POST /api/auth/login. Set AUTH_ENABLED=false to disable for local or trusted-network deployments.
Provider Prefixes
| Provider | Base Prefix | Protocol |
|---|---|---|
| Google Cloud Storage | /api/gcp/ | Native GCS client |
| Amazon S3 / S3-Compatible | /api/aws/ | AWS SDK v2 |
| Azure Blob Storage | /api/azure/ | Azure Blob SDK |
| Alibaba Cloud OSS | /api/alibaba/ | S3-compatible (path-style) |
| Huawei OBS | /api/huawei/ | S3-compatible (virtual-hosted) |
| Google Drive | /api/gdrive/ | Drive v3 API via service account |
Common Endpoint Pattern
Each provider exposes the same set of operations. The table below shows the pattern: replace {prefix} with gcp, aws, azure, alibaba, huawei, or gdrive.
| Method | Path | Description |
|---|---|---|
GET | /api/{prefix}/connections | List saved connections |
POST | /api/{prefix}/connection | Create connection |
PUT | /api/{prefix}/connection/{id} | Update connection |
DELETE | /api/{prefix}/connection/{id} | Delete connection |
POST | /api/{prefix}/test | Test credentials without saving |
POST | /api/{prefix}/bucket/browse | Browse objects: paginated, hierarchical |
POST | /api/{prefix}/bucket/upload | Upload file (multipart/form-data) |
POST | /api/{prefix}/bucket/download | Get time-limited download URL |
POST | /api/{prefix}/bucket/delete | Delete object |
POST | /api/{prefix}/bucket/copy | Copy or rename object |
POST | /api/{prefix}/bucket/stats | Bucket/container statistics |
POST | /api/{prefix}/bucket/metadata | Get object metadata |
POST | /api/{prefix}/bucket/metadata/update | Update object metadata |
Authentication Endpoints
JWT-based auth endpoints. Login returns a bearer token used in the Authorization header for all protected routes. Auth endpoints are always public (no token required).
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/auth/register | Public | Create the owner account (only works once) |
POST | /api/auth/login | Public | Authenticate with username + password, returns JWT |
GET | /api/auth/me | Required | Return current user info from the JWT |
GET | /api/auth/setup-status | Public | Returns setup_required and auth_enabled flags |
Login Request / Response
POST /api/auth/login: request{
"username" : "admin" ,
"password" : "your-password"
}
Response
"token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ,
"user_id" : 1 ,
"role" : "admin"
GCS Endpoints
Google Cloud Storage endpoints use the native GCS client library. Download URLs are signed URLs valid for 15 minutes. Credentials must be a full service account JSON key object.
| Method | Path | Description |
|---|---|---|
GET | /api/gcp/connections | List saved GCS connections |
POST | /api/gcp/connection | Create GCS connection |
PUT | /api/gcp/connection/{id} | Update GCS connection |
DELETE | /api/gcp/connection/{id} | Delete GCS connection |
POST | /api/gcp/test | Test credentials without saving |
POST | /api/gcp/bucket/browse | Browse objects (paginated) |
POST | /api/gcp/bucket/upload | Upload file (multipart form) |
POST | /api/gcp/bucket/download | Get signed download URL (15 min) |
POST | /api/gcp/bucket/delete | Delete object |
POST | /api/gcp/bucket/copy | Copy or rename object |
POST | /api/gcp/bucket/stats | Bucket statistics (samples up to 10,000 objects) |
POST | /api/gcp/bucket/metadata | Get object metadata |
POST | /api/gcp/bucket/metadata/update | Update object metadata |
Browse Request
POST /api/gcp/bucket/browse "bucket" : "my-bucket" , "credentials" : "{ ...service account JSON... }" , "prefix" : "folder/subfolder/" , "page_token" : "" "entries" : [ { "type" : "dir" , "name" : "folder/subfolder/images/" , "display" : "images" }, { "type" : "file" , "name" : "folder/subfolder/file.txt" , "display" : "file.txt" , "size" : 1024, "updated" : "2025-01-01T00:00:00Z" } ], "next_page_token" : ""Upload Request
Upload uses multipart/form-data with the following fields:
| Field | Type | Description |
|---|---|---|
bucket | string | Bucket name |
credentials | string (JSON) | Provider credentials as a JSON string |
prefix | string | Destination folder prefix (e.g. images/) |
file | file | The file to upload |
AWS / S3-Compatible Endpoints
AWS endpoints are under /api/aws/ and mirror the GCS endpoints exactly. The same prefix also handles Cloudflare R2 and MinIO when an endpoint is set in the credentials. Download URLs are presigned GET URLs valid for 15 minutes.
| Method | Path | Description |
|---|---|---|
GET | /api/aws/connections | List saved AWS connections |
POST | /api/aws/connection | Create AWS connection |
PUT | /api/aws/connection/{id} | Update AWS connection |
DELETE | /api/aws/connection/{id} | Delete AWS connection |
POST | /api/aws/test | Test credentials without saving |
POST | /api/aws/bucket/browse | Browse objects (paginated) |
POST | /api/aws/bucket/upload | Upload file (multipart form) |
POST | /api/aws/bucket/download | Get presigned download URL (15 min) |
POST | /api/aws/bucket/delete | Delete object |
POST | /api/aws/bucket/copy | Copy or rename object |
POST | /api/aws/bucket/stats | Bucket statistics (up to 10,000 objects) |
POST | /api/aws/bucket/metadata | Get object metadata |
POST | /api/aws/bucket/metadata/update | Update object metadata |
Credentials Format
json: AWS / S3-compatible credential object "access_key_id" : "AKIAIOSFODNN7EXAMPLE" , "secret_access_key" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" , "region" : "us-east-1" , "endpoint" : "https://<ACCOUNT_ID>.r2.cloudflarestorage.com" , "session_token" : "optional-sts-token"Omit endpoint for standard AWS S3. Set endpoint to your Cloudflare R2 or MinIO URL for S3-compatible services. region defaults to us-east-1 if omitted.
Azure Blob Storage Endpoints
Azure endpoints are under /api/azure/. The bucket field maps to a Blob container name. Download URLs are Azure SAS tokens valid for 15 minutes. Azure uses its own SDK, not S3-compatible.
| Method | Path | Description |
|---|---|---|
GET | /api/azure/connections | List saved Azure connections |
POST | /api/azure/connection | Create Azure connection |
PUT | /api/azure/connection/{id} | Update Azure connection |
DELETE | /api/azure/connection/{id} | Delete Azure connection |
POST | /api/azure/test | Test credentials without saving |
POST | /api/azure/bucket/browse | Browse blobs (paginated, hierarchy) |
POST | /api/azure/bucket/upload | Upload blob (multipart form) |
POST | /api/azure/bucket/download | Get SAS download URL (15 min) |
POST | /api/azure/bucket/delete | Delete blob |
POST | /api/azure/bucket/copy | Copy or rename blob |
POST | /api/azure/bucket/stats | Container statistics (up to 10,000 blobs) |
POST | /api/azure/bucket/metadata | Get blob metadata & HTTP headers |
POST | /api/azure/bucket/metadata/update | Update blob metadata & HTTP headers |
Unlike other providers, Azure metadata updates do not require a copy-to-self: HTTP headers (Content-Type, Cache-Control) and custom metadata are patched in-place via separate API calls.
Alibaba Cloud OSS Endpoints
Alibaba OSS endpoints are under /api/alibaba/. They use the S3-compatible API with path-style addressing. An endpoint key is required in the credentials. Download URLs are presigned GET URLs valid for 15 minutes.
| Method | Path | Description |
|---|---|---|
GET | /api/alibaba/connections | List saved Alibaba OSS connections |
POST | /api/alibaba/connection | Create Alibaba OSS connection |
PUT | /api/alibaba/connection/{id} | Update Alibaba OSS connection |
DELETE | /api/alibaba/connection/{id} | Delete Alibaba OSS connection |
POST | /api/alibaba/test | Test credentials without saving |
POST | /api/alibaba/bucket/browse | Browse objects (paginated) |
POST | /api/alibaba/bucket/upload | Upload file (multipart form) |
POST | /api/alibaba/bucket/download | Get presigned download URL (15 min) |
POST | /api/alibaba/bucket/delete | Delete object |
POST | /api/alibaba/bucket/copy | Copy or rename object |
POST | /api/alibaba/bucket/stats | Bucket statistics (up to 10,000 objects) |
POST | /api/alibaba/bucket/metadata | Get object metadata |
POST | /api/alibaba/bucket/metadata/update | Update object metadata (copy-to-self) |
The endpoint field is required and must match the region of your bucket (e.g. https://oss-cn-hangzhou.aliyuncs.com). region defaults to cn-hangzhou if omitted. OSS uses path-style addressing.
Huawei OBS Endpoints
Huawei OBS endpoints are under /api/huawei/. They use the S3-compatible API with virtual-hosted-style addressing. An endpoint key is required in the credentials. Download URLs are presigned GET URLs valid for 15 minutes.
| Method | Path | Description |
|---|---|---|
GET | /api/huawei/connections | List saved Huawei OBS connections |
POST | /api/huawei/connection | Create Huawei OBS connection |
PUT | /api/huawei/connection/{id} | Update Huawei OBS connection |
DELETE | /api/huawei/connection/{id} | Delete Huawei OBS connection |
POST | /api/huawei/test | Test credentials without saving |
POST | /api/huawei/bucket/browse | Browse objects (paginated) |
POST | /api/huawei/bucket/upload | Upload file (multipart form) |
POST | /api/huawei/bucket/download | Get presigned download URL (15 min) |
POST | /api/huawei/bucket/delete | Delete object |
POST | /api/huawei/bucket/copy | Copy or rename object |
POST | /api/huawei/bucket/stats | Bucket statistics (up to 10,000 objects) |
POST | /api/huawei/bucket/metadata | Get object metadata |
POST | /api/huawei/bucket/metadata/update | Update object metadata (copy-to-self) |
The endpoint field is required. OBS uses virtual-hosted-style addressing: https://<bucket>.obs.<region>.myhuaweicloud.com. The connection test uses ListObjectsV2, which requires the obs:ListBucket IAM permission.
Google Drive Endpoints
Google Drive endpoints are under /api/gdrive/. The bucket field maps to the root Folder ID. Files are identified by their Drive file ID. Google Workspace documents (Docs, Sheets, Slides) are exported as PDF on download. Stats are not supported (returns zeros).
| Method | Path | Description |
|---|---|---|
GET | /api/gdrive/connections | List saved Google Drive connections |
POST | /api/gdrive/connection | Create Google Drive connection |
PUT | /api/gdrive/connection/{id} | Update Google Drive connection |
DELETE | /api/gdrive/connection/{id} | Delete Google Drive connection |
POST | /api/gdrive/test | Test service account access to the folder |
POST | /api/gdrive/bucket/browse | Browse files & folders (paginated, 200 per page) |
POST | /api/gdrive/bucket/upload | Upload file (multipart form) |
POST | /api/gdrive/bucket/download | Get direct download or export URL |
POST | /api/gdrive/bucket/delete | Permanently delete a file |
POST | /api/gdrive/bucket/copy | Rename (delete_source: true) or copy a file |
POST | /api/gdrive/bucket/stats | Returns zeros (not supported by Drive API) |
POST | /api/gdrive/bucket/metadata | Get file metadata (name, MIME type, size, MD5) |
POST | /api/gdrive/bucket/metadata/update | Update MIME type and description |
The bucket field is the Drive Folder ID (not a bucket name). File objects are identified internally as {prefix}/{fileID}. The service account must be shared on the root folder with at least Viewer access.
Utility Endpoints
Cross-provider operations and platform features. All require authentication unless marked Public.
| Method | Path | Description |
|---|---|---|
POST | /api/transfer | Stream a single file from one provider/connection to another |
POST | /api/transfer/bulk | Batch-transfer multiple objects across providers |
POST | /api/zip | Stream multiple objects as a ZIP archive |
GET/POST | /api/jobs | List or create background jobs |
GET | /api/jobs/{id} | Get status of a specific background job |
GET | /api/connections/export | Export all connections to JSON |
POST | /api/connections/import | Import connections from a JSON export file |
GET | /api/proxy/download | Server-side proxy download (avoids CORS for in-browser preview) |
GET | /api/metrics | Prometheus-compatible metrics: Public |
GET | /api/health | Health check: Public |
Transfer Request
POST /api/transfer "src_provider" : "gcp" , "src_connection_id" : 1 , "src_object" : "path/to/file.jpg" , "dst_provider" : "aws" , "dst_connection_id" : 2 , "dst_prefix" : "archive/"Error Responses
All error responses return a JSON object with a single error key containing a descriptive message from the provider SDK or from validation.
{ "error" : "descriptive error message" }
| HTTP Status | Meaning |
|---|---|
400 | Bad request: missing required fields, invalid JSON, or credential validation failure |
401 | Unauthorized: missing or invalid JWT token |
404 | Connection ID or object not found |
405 | Method not allowed |
429 | Rate limit exceeded (20 requests per 60-second window) |
500 | Unexpected server error (provider SDK failure, I/O error) |
Use POST /api/{prefix}/test to validate credentials before creating a connection. This performs a live head/list against the bucket and surfaces provider-specific errors without persisting anything to the local database.