# WaMax S3 Cloud Object Storage - Developer & Admin API Documentation

## 1. Overview
**WaMax S3** is an enterprise-grade object storage proxy and API gateway. It provides an S3-style REST API and rich multi-tenant console backed by Telegram Private Channels as an unlimited data store.

### Key Capabilities
- **Invisible Storage Driver**: Telegram identifiers, message IDs, Bot Tokens, and channels are 100% hidden.
- **Super Admin Subsystem**: Super Admin can provision client accounts and enforce strict storage quotas (e.g. 1 GB, 10 GB, 50 GB, 1 TB).
- **100 GB Multipart Splitting**: Automatically divides massive files into 1.9 GB chunks, uploads them to the private channel, and streams them back seamlessly as a single object.
- **HTTP 206 Range Streaming**: Instant seek support for 4K/HD video and audio playback.
- **Virtual Directory Tree**: Full folder hierarchy support (`/projects/2026/videos`).
- **Developer API Keys**: Programmatic authentication via `X-API-Key: wmx_live_...`.

---

## 2. Authentication

### Method A: Bearer JWT Token (Web UI & REST)
Pass the token in the `Authorization` header:
```http
Authorization: Bearer <jwt_token>
```
Or as a query parameter (for `<video>` tags or browser downloads):
```
?token=<jwt_token>
```

### Method B: Secret API Key (Server-to-Server / SDKs)
Pass the API key in the `X-API-Key` header:
```http
X-API-Key: wmx_live_xxxxxxxxxxxxxxxxxxxxxxxx
```
Or as a query parameter:
```
?api_key=wmx_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

---

## 3. Super Admin Endpoints

### 3.1. Get Global Platform Metrics
```http
GET /api/v1/admin/stats
```
**Headers:** `Authorization: Bearer <super_admin_jwt>`

**Response:**
```json
{
  "success": true,
  "stats": {
    "total_clients": 12,
    "total_objects": 4821,
    "total_parts": 6390,
    "total_used_bytes": 107374182400,
    "total_used_human": "100.00 GB",
    "telegram_channel": -1001234567890,
    "telegram_status": true,
    "bot_api_url": "http://127.0.0.1:8081",
    "max_chunk_bytes": 1992294400,
    "max_chunk_human": "1.86 GB",
    "product": "WaMax S3 Cloud",
    "version": "4.0.0"
  }
}
```

---

### 3.2. List All Client Accounts
```http
GET /api/v1/admin/clients
```
**Response:**
```json
{
  "success": true,
  "clients": [
    {
      "id": "usr_77a90f12",
      "username": "client_alpha",
      "full_name": "Alpha Media Works",
      "role": "client",
      "quota_bytes": 10737418240,
      "quota_human": "10.00 GB",
      "used_bytes": 2147483648,
      "used_human": "2.00 GB",
      "usage_percentage": 20.0,
      "status": "active",
      "created_at": "2026-10-20T12:00:00Z"
    }
  ]
}
```

---

### 3.3. Create Client Account with Quota
```http
POST /api/v1/admin/clients
Content-Type: application/json
```
**Payload:**
```json
{
  "username": "studio_prime",
  "password": "SecurePassword123!",
  "full_name": "Studio Prime Productions",
  "email": "ops@studioprime.com",
  "quota_gb": 50
}
```
**Response:**
```json
{
  "success": true,
  "message": "Client created successfully with assigned quota",
  "client": {
    "id": "usr_99bf210",
    "username": "studio_prime",
    "quota_gb": 50,
    "quota_bytes": 53687091200,
    "quota_human": "50.00 GB",
    "status": "active"
  }
}
```

---

### 3.4. Update Client Quota or Status
```http
PATCH /api/v1/admin/clients/:id
Content-Type: application/json
```
**Payload:**
```json
{
  "quota_gb": 100,
  "status": "active",
  "password": "NewSecretPassword!"
}
```

---

### 3.5. Purge Client Account
```http
DELETE /api/v1/admin/clients/:id
```
Deletes the client account, purges all stored Telegram parts from the channel, and removes database records.

---

## 4. Client Storage & File Management Endpoints

### 4.1. List Directory & Files
```http
GET /api/v1/folders?folder_id=fld_xxxx
```
Leave `folder_id` blank to query the root directory.

**Response:**
```json
{
  "success": true,
  "current_folder": { "id": "fld_01", "name": "Videos", "full_path": "/Videos" },
  "folders": [
    { "id": "fld_02", "name": "4K Renders", "items_count": 8 }
  ],
  "files": [
    {
      "id": "obj_0a1b2c3d",
      "name": "cinematic_teaser.mp4",
      "size_bytes": 21474836480,
      "size_human": "20.00 GB",
      "mime_type": "video/mp4",
      "status": "ready",
      "download_url": "https://s3.wamax.in/api/v1/files/obj_0a1b2c3d/content",
      "stream_url": "https://s3.wamax.in/api/v1/files/obj_0a1b2c3d/stream",
      "created_at": "2026-10-20T12:30:00Z"
    }
  ]
}
```

---

### 4.2. Create Virtual Folder
```http
POST /api/v1/folders
Content-Type: application/json
```
**Payload:**
```json
{
  "parent_id": "fld_01",
  "name": "Soundtracks"
}
```

---

### 4.3. Standard File Upload (< 1.9 GB)
```http
POST /api/v1/objects/upload
Content-Type: multipart/form-data
```
**Form Fields:**
- `file`: binary content
- `folder_id`: (optional) parent folder ID

**Response:**
```json
{
  "success": true,
  "message": "File uploaded successfully to WaMax S3 Storage",
  "file": {
    "id": "obj_9921fa",
    "name": "contract.pdf",
    "size_bytes": 4829104,
    "size_human": "4.61 MB",
    "mime_type": "application/pdf",
    "download_url": "https://s3.wamax.in/api/v1/files/obj_9921fa/content",
    "stream_url": "https://s3.wamax.in/api/v1/files/obj_9921fa/stream"
  }
}
```

---

### 4.4. 100 GB Resumable Multipart Upload

#### Step 1: Initiate Multipart Session
```http
POST /api/v1/objects/multipart/init
Content-Type: application/json
```
**Payload:**
```json
{
  "file_name": "archive_100gb.tar",
  "total_size": 107374182400,
  "mime_type": "application/x-tar",
  "folder_id": ""
}
```
**Response:**
```json
{
  "success": true,
  "upload_id": "mp_90a1b82",
  "file_name": "archive_100gb.tar",
  "chunk_size": 1992294400,
  "total_parts": 54,
  "total_size": 107374182400
}
```

#### Step 2: Upload Chunk (Part 1 .. 54)
```http
PUT /api/v1/objects/multipart/:upload_id/parts/:part_number
Content-Type: multipart/form-data
```
**Form Fields:**
- `chunk`: binary chunk (up to 1.9 GB)

#### Step 3: Complete Multipart Assembly
```http
POST /api/v1/objects/multipart/:upload_id/complete
```
**Response:**
```json
{
  "success": true,
  "message": "Multipart upload assembled successfully",
  "file": {
    "id": "obj_complete_100gb",
    "name": "archive_100gb.tar",
    "size_bytes": 107374182400,
    "size_human": "100.00 GB",
    "download_url": "https://s3.wamax.in/api/v1/files/obj_complete_100gb/content",
    "stream_url": "https://s3.wamax.in/api/v1/files/obj_complete_100gb/stream"
  }
}
```

---

### 4.5. Video Streaming with Range Seeking (HTTP 206)
```http
GET /api/v1/files/:id/stream
Range: bytes=35000000000-36000000000
```
**Response:**
```http
HTTP/1.1 206 Partial Content
Content-Range: bytes 35000000000-36000000000/107374182400
Content-Type: video/mp4
Accept-Ranges: bytes
```
Allows native HTML5 `<video>` players to scrub, seek, and stream high-bitrate media without downloading the entire 50 GB or 100 GB object.