API: Buckets

Endpoints

Method	Path	Description
POST	`/v1/buckets`	Create a bucket
GET	`/v1/buckets`	List all buckets
GET	`/v1/buckets/{id}`	Get bucket details
DELETE	`/v1/buckets/{id}`	Delete a bucket

## Create Bucket

POST /v1/buckets

Request Body

{
  "metadata": {
    "name": "production-assets",
    "labels": {"team": "frontend"}
  },
  "spec": {
    "region": "fsn1",
    "versioning": true,
    "lifecycle_rules": [
      {"prefix": "logs/", "expiration_days": 30},
      {"prefix": "tmp/", "expiration_days": 7}
    ]
  }
}

Response (201)

{
  "id": "bkt-a1b2c3",
  "metadata": {
    "name": "production-assets",
    "labels": {"team": "frontend"},
    "created_at": "2025-01-15T10:30:00Z"
  },
  "spec": {
    "region": "fsn1",
    "versioning": true,
    "lifecycle_rules": [
      {"prefix": "logs/", "expiration_days": 30},
      {"prefix": "tmp/", "expiration_days": 7}
    ]
  },
  "status": {
    "state": "active",
    "endpoint": "https://production-assets.s3.fsn1.agentmetal.dev",
    "size_bytes": 0,
    "object_count": 0
  }
}

BucketSpec Fields

Field	Type	Required	Description
`region`	string	Yes	Storage region identifier
`versioning`	bool	No	Enable object version history (default: false)
`lifecycle_rules`	array	No	List of expiration rules with prefix and days

## List Buckets

GET /v1/buckets

{
  "items": [
    {
      "id": "bkt-a1b2c3",
      "metadata": {"name": "production-assets"},
      "spec": {"region": "fsn1", "versioning": true},
      "status": {"state": "active", "size_bytes": 1048576, "object_count": 42}
    }
  ]
}

Delete Bucket

DELETE /v1/buckets/bkt-a1b2c3

Returns 202. The bucket must be empty unless the force parameter is set.