# Маршруты API

> Эндпоинты для получения списка файлов, чтения метаданных, удаления и проверки квоты.

Раздел содержит детальное описание маршрутов REST API для работы с объектами и квотой хранилища.

## Список файлов (GET /files)

Возвращает список файлов текущего аккаунта, отсортированных в порядке убывания даты создания:

```http
GET /files HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>
```

Требуемое право: `files:read`.

### Параметры строки запроса

| Параметр | Тип | Описание |
| :--- | :--- | :--- |
| `limit` | целое число | Количество возвращаемых записей от 1 до 200. По умолчанию 50. |
| `cursor` | строка | Непрозрачный токен пагинации для получения следующей страницы. |
| `search` | строка | Фильтрация по подстроке имени файла без учета регистра. До 256 символов. |
| `kind` | строка | Фильтр по расширению или типу файла. До 64 символов. |
| `is_media` | строка | Фильтр по признаку медиафайла (`true` или `false`). |

### Пример ответа (200 OK)

```json
{
  "items": [
    {
      "id": "file_01h8abc123def456",
      "name": "annual-report.pdf",
      "kind": "pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "size_bytes": 1048576,
      "status": "ready",
      "created_at": "2026-10-15T12:00:00Z",
      "updated_at": "2026-10-15T12:00:05Z",
      "deleted_at": null,
      "is_media": false,
      "taken_at": null,
      "agent_sync_enabled": false
    }
  ],
  "next_cursor": "eyJhbGciOiJIUzI1NiJ9..."
}
```

## Метаданные файла (GET /files/\{file_id\})

Возвращает метаданные указанного файла и текущий статус обработки:

```http
GET /files/file_01h8abc123def456 HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>
```

Требуемое право: `files:read`.

Возможные значения поля `status`:
- `uploaded`: файл принят сервером загрузки.
- `processing`: файл находится в процессе валидации или сборки.
- `ready`: файл успешно сохранен и доступен для скачивания.
- `failed`: в процессе обработки произошла ошибка.

## Удаление файла (DELETE /files/\{file_id\})

Выполняет мягкое удаление файла из хранилища:

```http
DELETE /files/file_01h8abc123def456 HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>
```

Требуемое право: `files:delete`.

Удаление освобождает место в дисковой квоте. Повторный вызов метода для уже удаленного файла является идемпотентным и безопасным.

## Проверка квоты (GET /quota)

Возвращает текущие метрики использования дискового пространства аккаунта:

```http
GET /quota HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>
```

Требуемое право: `quota:read` или `files:read`.

### Пример ответа (200 OK)

```json
{
  "used_bytes": 107374182400,
  "reserved_bytes": 0,
  "total_quota_bytes": 1099511627776,
  "free_bytes": 992137445376,
  "unlimited": false,
  "is_read_only": false
}
```

Поля ответа:
- `used_bytes`: объем занятого дискового пространства в байтах.
- `reserved_bytes`: объем незавершенных составных загрузок в байтах.
- `total_quota_bytes`: общий объем квоты тарифного плана в байтах.
- `free_bytes`: доступное свободное место в байтах.
- `unlimited`: признак безлимитного тарифа (`true` или `false`).
- `is_read_only`: флаг блокировки записи при приостановке подписки (`true` или `false`).