Storage API

REST API reference for uploading, downloading, and managing files.

Storage API

The Storage API handles all file operations: upload, download, list, copy, move, delete, and presigned URLs.

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

All requests require an Authorization: Bearer sf_live_... header (or ?token= for presigned URLs).

Upload an object

PUT /v1/storage/:bucket/:key

Upload a file to a bucket. The :key is the object path within the bucket (e.g. images/avatar.jpg).

Headers:

Response 200:

{
  "key": "images/avatar.jpg",
  "bucket": "my-media",
  "size": 45231,
  "contentType": "image/jpeg",
  "hash": "sha256:abc123...",
  "url": "https://cdn.superfiles.montr.online/my-media/images/avatar.jpg",
  "createdAt": "2025-08-07T12:34:56.000Z",
  "updatedAt": "2025-08-07T12:34:56.000Z"
}

url is null for private buckets. Use a presigned download URL for private access.

Download an object

GET /v1/storage/:bucket/:key

Stream the object contents. Returns the raw file with appropriate Content-Type and Content-Length headers.

Private bucket objects require the Authorization header or a ?token= presigned token.

Get object metadata

HEAD /v1/storage/:bucket/:key

Returns the same headers as GET without the body. Use to check ETag, Content-Type, and Content-Length without downloading.

Delete an object

DELETE /v1/storage/:bucket/:key

Soft-deletes the object (moves to trash). The blob is not immediately removed; its reference count is decremented and the blob is garbage-collected when it reaches zero.

Response 204: No content.

List objects

GET /v1/storage/:bucket

Query parameters:

Response 200:

{
  "items": [
    {
      "key": "images/avatar.jpg",
      "size": 45231,
      "contentType": "image/jpeg",
      "url": "https://cdn.superfiles.montr.online/...",
      "updatedAt": "2025-08-07T12:34:56.000Z"
    }
  ],
  "prefixes": ["images/avatars/", "images/banners/"],
  "nextCursor": "eyJrZXkiOiJpbWFnZXMvYXZhdGFyLmpwZyJ9"
}

prefixes is populated when delimiter is set — these are the “virtual folders” under the given prefix.

Copy an object

POST /v1/storage/:bucket/:key/copy

Body:

{
  "destBucket": "my-backups",
  "destKey": "2025-08/avatar.jpg"
}

Response 200: The new object record.

Move an object

POST /v1/storage/:bucket/:key/move

Body:

{
  "destBucket": "my-media",
  "destKey": "images/profile.jpg"
}

Renames or moves the object. The source key is deleted after the move.

Presigned upload URL

POST /v1/storage/:bucket/:key/presign-upload

Generate a URL that a client can PUT to directly, without exposing the API key.

Body:

{
  "contentType": "image/jpeg",
  "expiresIn": 300
}

Response 200:

{
  "url": "https://api.superfiles.montr.online/v1/storage/my-media/images/avatar.jpg?token=..."
}

The presigned URL expires after expiresIn seconds (max: 86400).

Presigned download URL

POST /v1/storage/:bucket/:key/presign

Body:

{
  "expiresIn": 3600
}

Response 200:

{
  "url": "https://api.superfiles.montr.online/v1/storage/my-media/images/avatar.jpg?token=..."
}

Error codes