Home / Vestra Docs / API Reference

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 Docs

On this page

Vestra Docs

Overview

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

ProviderBase PrefixProtocol
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.

MethodPathDescription
GET/api/{prefix}/connectionsList saved connections
POST/api/{prefix}/connectionCreate connection
PUT/api/{prefix}/connection/{id}Update connection
DELETE/api/{prefix}/connection/{id}Delete connection
POST/api/{prefix}/testTest credentials without saving
POST/api/{prefix}/bucket/browseBrowse objects: paginated, hierarchical
POST/api/{prefix}/bucket/uploadUpload file (multipart/form-data)
POST/api/{prefix}/bucket/downloadGet time-limited download URL
POST/api/{prefix}/bucket/deleteDelete object
POST/api/{prefix}/bucket/copyCopy or rename object
POST/api/{prefix}/bucket/statsBucket/container statistics
POST/api/{prefix}/bucket/metadataGet object metadata
POST/api/{prefix}/bucket/metadata/updateUpdate 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).

MethodPathAuthDescription
POST/api/auth/registerPublicCreate the owner account (only works once)
POST/api/auth/loginPublicAuthenticate with username + password, returns JWT
GET/api/auth/meRequiredReturn current user info from the JWT
GET/api/auth/setup-statusPublicReturns 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.

MethodPathDescription
GET/api/gcp/connectionsList saved GCS connections
POST/api/gcp/connectionCreate GCS connection
PUT/api/gcp/connection/{id}Update GCS connection
DELETE/api/gcp/connection/{id}Delete GCS connection
POST/api/gcp/testTest credentials without saving
POST/api/gcp/bucket/browseBrowse objects (paginated)
POST/api/gcp/bucket/uploadUpload file (multipart form)
POST/api/gcp/bucket/downloadGet signed download URL (15 min)
POST/api/gcp/bucket/deleteDelete object
POST/api/gcp/bucket/copyCopy or rename object
POST/api/gcp/bucket/statsBucket statistics (samples up to 10,000 objects)
POST/api/gcp/bucket/metadataGet object metadata
POST/api/gcp/bucket/metadata/updateUpdate 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:

FieldTypeDescription
bucketstringBucket name
credentialsstring (JSON)Provider credentials as a JSON string
prefixstringDestination folder prefix (e.g. images/)
filefileThe 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.

MethodPathDescription
GET/api/aws/connectionsList saved AWS connections
POST/api/aws/connectionCreate AWS connection
PUT/api/aws/connection/{id}Update AWS connection
DELETE/api/aws/connection/{id}Delete AWS connection
POST/api/aws/testTest credentials without saving
POST/api/aws/bucket/browseBrowse objects (paginated)
POST/api/aws/bucket/uploadUpload file (multipart form)
POST/api/aws/bucket/downloadGet presigned download URL (15 min)
POST/api/aws/bucket/deleteDelete object
POST/api/aws/bucket/copyCopy or rename object
POST/api/aws/bucket/statsBucket statistics (up to 10,000 objects)
POST/api/aws/bucket/metadataGet object metadata
POST/api/aws/bucket/metadata/updateUpdate 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.

MethodPathDescription
GET/api/azure/connectionsList saved Azure connections
POST/api/azure/connectionCreate Azure connection
PUT/api/azure/connection/{id}Update Azure connection
DELETE/api/azure/connection/{id}Delete Azure connection
POST/api/azure/testTest credentials without saving
POST/api/azure/bucket/browseBrowse blobs (paginated, hierarchy)
POST/api/azure/bucket/uploadUpload blob (multipart form)
POST/api/azure/bucket/downloadGet SAS download URL (15 min)
POST/api/azure/bucket/deleteDelete blob
POST/api/azure/bucket/copyCopy or rename blob
POST/api/azure/bucket/statsContainer statistics (up to 10,000 blobs)
POST/api/azure/bucket/metadataGet blob metadata & HTTP headers
POST/api/azure/bucket/metadata/updateUpdate blob metadata & HTTP headers
json: Azure credential object "account_name" : "mystorageaccount" , "account_key" : "base64-encoded-account-key=="

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.

MethodPathDescription
GET/api/alibaba/connectionsList saved Alibaba OSS connections
POST/api/alibaba/connectionCreate Alibaba OSS connection
PUT/api/alibaba/connection/{id}Update Alibaba OSS connection
DELETE/api/alibaba/connection/{id}Delete Alibaba OSS connection
POST/api/alibaba/testTest credentials without saving
POST/api/alibaba/bucket/browseBrowse objects (paginated)
POST/api/alibaba/bucket/uploadUpload file (multipart form)
POST/api/alibaba/bucket/downloadGet presigned download URL (15 min)
POST/api/alibaba/bucket/deleteDelete object
POST/api/alibaba/bucket/copyCopy or rename object
POST/api/alibaba/bucket/statsBucket statistics (up to 10,000 objects)
POST/api/alibaba/bucket/metadataGet object metadata
POST/api/alibaba/bucket/metadata/updateUpdate object metadata (copy-to-self)
json: Alibaba OSS credential object "access_key_id" : "your-alibaba-access-key-id" , "secret_access_key" : "your-alibaba-access-key-secret" , "endpoint" : "https://oss-cn-hangzhou.aliyuncs.com" , "region" : "cn-hangzhou"

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.

MethodPathDescription
GET/api/huawei/connectionsList saved Huawei OBS connections
POST/api/huawei/connectionCreate Huawei OBS connection
PUT/api/huawei/connection/{id}Update Huawei OBS connection
DELETE/api/huawei/connection/{id}Delete Huawei OBS connection
POST/api/huawei/testTest credentials without saving
POST/api/huawei/bucket/browseBrowse objects (paginated)
POST/api/huawei/bucket/uploadUpload file (multipart form)
POST/api/huawei/bucket/downloadGet presigned download URL (15 min)
POST/api/huawei/bucket/deleteDelete object
POST/api/huawei/bucket/copyCopy or rename object
POST/api/huawei/bucket/statsBucket statistics (up to 10,000 objects)
POST/api/huawei/bucket/metadataGet object metadata
POST/api/huawei/bucket/metadata/updateUpdate object metadata (copy-to-self)
json: Huawei OBS credential object "access_key_id" : "your-huawei-access-key-id" , "secret_access_key" : "your-huawei-secret-access-key" , "endpoint" : "https://obs.cn-north-4.myhuaweicloud.com" , "region" : "cn-north-4"

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).

MethodPathDescription
GET/api/gdrive/connectionsList saved Google Drive connections
POST/api/gdrive/connectionCreate Google Drive connection
PUT/api/gdrive/connection/{id}Update Google Drive connection
DELETE/api/gdrive/connection/{id}Delete Google Drive connection
POST/api/gdrive/testTest service account access to the folder
POST/api/gdrive/bucket/browseBrowse files & folders (paginated, 200 per page)
POST/api/gdrive/bucket/uploadUpload file (multipart form)
POST/api/gdrive/bucket/downloadGet direct download or export URL
POST/api/gdrive/bucket/deletePermanently delete a file
POST/api/gdrive/bucket/copyRename (delete_source: true) or copy a file
POST/api/gdrive/bucket/statsReturns zeros (not supported by Drive API)
POST/api/gdrive/bucket/metadataGet file metadata (name, MIME type, size, MD5)
POST/api/gdrive/bucket/metadata/updateUpdate MIME type and description
json: Google Drive credential (service account JSON) "type" : "service_account" , "project_id" : "my-project" , "private_key_id" : "key-id" , "private_key" : "-----BEGIN RSA PRIVATE KEY-----\n..." , "client_email" : "my-sa@my-project.iam.gserviceaccount.com" , "client_id" : "123456789" , "auth_uri" : "https://accounts.google.com/o/oauth2/auth" , "token_uri" : "https://oauth2.googleapis.com/token"

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.

MethodPathDescription
POST/api/transferStream a single file from one provider/connection to another
POST/api/transfer/bulkBatch-transfer multiple objects across providers
POST/api/zipStream multiple objects as a ZIP archive
GET/POST/api/jobsList or create background jobs
GET/api/jobs/{id}Get status of a specific background job
GET/api/connections/exportExport all connections to JSON
POST/api/connections/importImport connections from a JSON export file
GET/api/proxy/downloadServer-side proxy download (avoids CORS for in-browser preview)
GET/api/metricsPrometheus-compatible metrics: Public
GET/api/healthHealth 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.

json: error body
{ "error" : "descriptive error message" }
HTTP StatusMeaning
400Bad request: missing required fields, invalid JSON, or credential validation failure
401Unauthorized: missing or invalid JWT token
404Connection ID or object not found
405Method not allowed
429Rate limit exceeded (20 requests per 60-second window)
500Unexpected 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.