Buckets API

Create, list, update, and delete buckets.

Buckets API

Buckets are top-level namespaces for your files. Every file belongs to exactly one bucket.

Base URL: https://api.superfiles.montr.online/v1/buckets

List buckets

GET /v1/buckets

Returns all buckets accessible by the authenticated API key’s team.

Response 200:

{
  "buckets": [
    {
      "id": "bkt_01h...",
      "slug": "my-media",
      "name": "My Media",
      "public": false,
      "cdnEnabled": true,
      "storageUsed": 104857600,
      "objectCount": 412,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Create a bucket

POST /v1/buckets

Body:

{
  "name": "my-media",
  "public": false,
  "cdnEnabled": true
}

Field	Type	Required	Description
`name`	string	Yes	Human-readable name. URL-safe slug is derived automatically.
`public`	boolean	No	Default: `false`. Public buckets serve objects without auth.
`cdnEnabled`	boolean	No	Default: `true`. Enables CDN transform URLs.

Response 201: The created bucket object.

Get a bucket

GET /v1/buckets/:slug

Response 200: The bucket object.

Update a bucket

PATCH /v1/buckets/:slug

Body (all fields optional):

{
  "name": "Renamed Bucket",
  "public": true,
  "cdnEnabled": false
}

Response 200: The updated bucket object.

Delete a bucket

DELETE /v1/buckets/:slug

Permanently deletes the bucket and all its objects. This is irreversible.

Response 204: No content.

Error codes

Code	HTTP	Description
`buckets.not_found`	404	Bucket slug not found
`buckets.slug_conflict`	409	A bucket with this slug already exists in the team
`buckets.not_empty`	409	Cannot delete a bucket that still contains objects (pass `?force=true`)