Transport & REST API HTTP REST endpoints for object storage, uploads, buckets, CAS, and admin operations.
The Trove extension exposes a full REST API for object storage operations. All endpoints are registered under the configured base path (default: /trove/v1).
Method Path Description POST/bucketsCreate a bucket GET/bucketsList all buckets GET/buckets/:bucketGet bucket info DELETE/buckets/:bucketDelete a bucket
Method Path Description PUT/buckets/:bucket/objects/*keyUpload an object GET/buckets/:bucket/objects/*keyDownload an object DELETE/buckets/:bucket/objects/*keyDelete an object HEAD/buckets/:bucket/objects/*keyGet object metadata GET/buckets/:bucket/objectsList objects in a bucket
Method Path Description POST/buckets/:bucket/uploadsInitiate multipart upload PUT/buckets/:bucket/uploads/:id/parts/:partNumUpload a part POST/buckets/:bucket/uploads/:id/completeComplete upload DELETE/buckets/:bucket/uploads/:idAbort upload GET/buckets/:bucket/uploads/:idGet upload status
Method Path Description PUT/casStore content by hash GET/cas/:hashRetrieve content by hash HEAD/cas/:hashCheck if hash exists
Method Path Description GET/admin/statsStorage statistics
curl -X PUT \ http://localhost:8080/trove/v1/buckets/uploads/objects/photos/cat.jpg \ -H "Content-Type: image/jpeg" \ --data-binary @cat.jpg { "bucket" : "uploads" , "key" : "photos/cat.jpg" , "size" : 204800 , "content_type" : "image/jpeg" , "etag" : " \" d41d8cd98f00b204e9800998ecf8427e \" " , "last_modified" : "2025-01-15T10:30:00Z" } curl http://localhost:8080/trove/v1/buckets/uploads/objects/photos/cat.jpg \ -o cat.jpg The response streams the object body with appropriate Content-Type, Content-Length, and ETag headers.
curl "http://localhost:8080/trove/v1/buckets/uploads/objects?prefix=photos/&limit=100" { "objects" : [ { "key" : "photos/cat.jpg" , "size" : 204800 , "last_modified" : "2025-01-15T10:30:00Z" } ], "truncated" : false } curl -X PUT \ http://localhost:8080/trove/v1/cas \ -H "Content-Type: application/octet-stream" \ --data-binary @data.bin { "hash" : "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" , "size" : 1024 , "deduplicated" : false } Header Description Content-TypeMIME type for uploads Content-LengthObject size (optional, enables size validation) X-Trove-ChecksumExpected checksum for integrity verification X-Subject-IDSubject identifier for authorization (set by auth middleware)
Header Description ETagObject entity tag Content-TypeObject MIME type Content-LengthObject size in bytes Last-ModifiedObject modification timestamp X-Trove-ChecksumServer-computed checksum
All errors follow a consistent JSON format:
{ "error" : "object not found" , "code" : 404 } Code Meaning 400Bad request (missing bucket, invalid key) 403Forbidden (Warden denied access) 404Object, bucket, or upload not found 409Conflict (bucket already exists) 413Payload too large (quota exceeded) 500Internal server error