ss-tools/specs/014-file-storage-ui/contracts/api.md

API Contracts: File Storage Management & UI

Endpoints

GET /api/storage/files

List all files in the storage system.

Query Parameters:

• category (optional): Filter by category (backup or repository).

Response:

• 200 OK: List of StoredFile objects.

[
  {
    "name": "dashboard_backup_20260124.zip",
    "path": "backups/dashboard_backup_20260124.zip",
    "size": 102400,
    "created_at": "2026-01-24T12:00:00Z",
    "category": "backup",
    "mime_type": "application/zip"
  }
]

POST /api/storage/upload

Upload a file to the storage system.

Form Data:

• file: The file content.
• category: Target category (backup or repository).

Response:

• 201 Created: The uploaded StoredFile object.
• 400 Bad Request: Invalid category or file.

DELETE /api/storage/files/{category}/{filename}

Delete a file from storage.

Path Parameters:

• category: backup or repository.
• filename: Name of the file to delete.

Response:

• 204 No Content: File deleted successfully.
• 404 Not Found: File does not exist.

GET /api/storage/download/{category}/{filename}

Download a file.

Path Parameters:

• category: backup or repository.
• filename: Name of the file to download.

Response:

• 200 OK: File stream.
• 404 Not Found: File does not exist.

GET /api/settings/storage

Get current storage configuration.

Response:

• 200 OK: StorageConfig object.

PUT /api/settings/storage

Update storage configuration.

Body:

• StorageConfig object.

Response:

• 200 OK: Updated StorageConfig.
• 400 Bad Request: Invalid path or not writable.