# MyCloud API v1

Bu hujjat boshqa server yoki AI agent MyCloud xizmatiga ulanishi uchun yetarli bo‘lgan to‘liq kontraktdir.

## Asosiy manzil

```text
https://SIZNING-DOMENINGIZ/mycloud/api.php
```

Endpointlar `action` query parametri orqali tanlanadi. Himoyalangan so‘rovlarda token quyidagicha yuboriladi:

```http
Authorization: Bearer mc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Token API orqali hisob yaratilganda yoki qayta login qilinganda qaytariladi. Web kabinetda token ochiq ko‘rsatilmaydi: uni faqat **Nusxalash** tugmasi bilan clipboard’ga olish yoki **Qayta yaratish** mumkin. Qayta yaratish va API login eski tokenni darhol bekor qiladi. Tokenni URL query parametrida yubormang.

## Javob formati

Muvaffaqiyatli JSON javob:

```json
{"ok": true, "data": {}}
```

Xatolik:

```json
{"ok": false, "error": {"code": "invalid_token", "message": "Token yaroqsiz."}}
```

Download endpointi JSON emas, fayl oqimini qaytaradi.

## Endpointlar

### Status

`GET api.php?action=status` — autentifikatsiyasiz xizmat holatini tekshiradi.

### Hisob yaratish

`POST api.php?action=register`

JSON body:

```json
{"username":"example_user","password":"mustahkam-parol"}
```

Login 3–32 belgili, faqat `a-z`, `0-9`, `_`. Parol kamida 8 belgi. Javobdagi `data.token`ni xavfsiz saqlang.

### Login va tokenni yangilash

`POST api.php?action=login`

```json
{"username":"example_user","password":"mustahkam-parol"}
```

Har muvaffaqiyatli API login yangi token yaratadi va avvalgisini bekor qiladi.

### Profil va kvota

`GET api.php?action=me` — foydalanuvchi ID, login, umumiy/ishlatilgan/qolgan baytlarni qaytaradi.

### Fayllar ro‘yxati

`GET api.php?action=files&limit=50&offset=0`

- `limit`: 1–100, standart 50.
- `offset`: 0 yoki undan katta.
- Har elementda `id`, `original_name`, `file_size`, `sha256`, `created_at`, `updated_at` bor.

### Fayl yuklash

`POST api.php?action=upload`, `multipart/form-data`, maydon nomi `file`. Maksimal hajm 10 MB; hisobning standart kvotasi 200 MB.

```bash
curl -X POST "https://SIZNING-DOMENINGIZ/mycloud/api.php?action=upload" \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@/path/report.pdf"
```

### Faylni yuklab olish

`GET api.php?action=download&id=123`

```bash
curl -L "https://SIZNING-DOMENINGIZ/mycloud/api.php?action=download&id=123" \
  -H "Authorization: Bearer TOKEN" \
  -o report.pdf
```

### Qayta nomlash

`PATCH` yoki `POST api.php?action=rename&id=123`

```json
{"name":"yangi-nom.pdf"}
```

### O‘chirish

`DELETE` yoki `POST api.php?action=delete&id=123`. Metadata va fizik fayl o‘chiriladi.

## PHP server-to-server misoli

```php
<?php
$base = 'https://SIZNING-DOMENINGIZ/mycloud/api.php';
$token = getenv('MYCLOUD_TOKEN');

$ch = curl_init($base . '?action=files&limit=20&offset=0');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException('MyCloud API xatosi: ' . $response);
}
$files = json_decode($response, true, flags: JSON_THROW_ON_ERROR);
```

## HTTP statuslar

- `200` — muvaffaqiyat.
- `201` — hisob yoki fayl yaratildi.
- `401` — token/login noto‘g‘ri.
- `404` — fayl yoki action topilmadi.
- `405` — HTTP method noto‘g‘ri.
- `409` — login band.
- `413` — fayl yoki kvota limiti oshgan.
- `422` — kiruvchi ma’lumot noto‘g‘ri.
- `500/503` — server yoki SQLite muammosi.

## Boshqa AI chat uchun qisqa topshiriq

Quyidagini boshqa chatga berish mumkin:

> MyCloud API v1 bilan integratsiya qil. Base URL: `https://DOMEN/mycloud/api.php`. Bearer token `MYCLOUD_TOKEN` environment variable’da. API kontrakti: `GET ?action=me`, `GET ?action=files&limit=&offset=`, multipart `POST ?action=upload` (`file` field), `GET ?action=download&id=`, JSON `PATCH ?action=rename&id=` (`name`), `DELETE ?action=delete&id=`. Har JSON javob `ok` booleaniga ega. Tokenni log yoki URLga yozma, timeout va HTTP statuslarni tekshir.