Storage

📦 File Storage System

Routes

POST   /v1/storage/buckets                  # Create a bucket
GET    /v1/storage/buckets                  # List buckets
GET    /v1/storage/buckets/:name            # Get bucket info
DELETE /v1/storage/buckets/:name            # Delete a bucket
POST   /v1/storage/object/:bucket/*path     # Upload a file
GET    /v1/storage/object/:bucket/*path     # Download a file
DELETE /v1/storage/object/:bucket/*path     # Delete a file
GET    /v1/storage/list/:bucket             # List objects in a bucket (?prefix=&limit=&offset=)

Creating Buckets

The bucket name goes in the JSON body, not the URL path:

# Public bucket (files accessible via URL)
curl -X POST http://localhost:3000/v1/storage/buckets \
  -H "Content-Type: application/json" \
  -d '{"name": "public", "public": true}'

# Private bucket (requires auth)
curl -X POST http://localhost:3000/v1/storage/buckets \
  -H "Content-Type: application/json" \
  -d '{"name": "private", "public": false}'

Uploading Files

curl -X POST http://localhost:3000/v1/storage/object/public/document.pdf \
  -F "file=@document.pdf"

Downloading Files

# Public file
curl http://localhost:3000/v1/storage/object/public/document.pdf -O

# Private file (requires auth)
curl http://localhost:3000/v1/storage/object/private/secret.pdf \
  -H "Authorization: Bearer <token>" -O

Listing Files

curl http://localhost:3000/v1/storage/list/public

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "bucket_name": "public",
      "path": "document.pdf",
      "size": 1024000,
      "mime_type": "application/pdf",
      "created_at": "2026-08-18T12:00:00Z",
      "updated_at": "2026-08-18T12:00:00Z",
      "owner_id": null
    }
  ]
}

Deleting Files

curl -X DELETE http://localhost:3000/v1/storage/object/public/document.pdf

Next: Replication