Маршруты API

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

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

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

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)

{
  "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})

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

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})

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

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

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

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

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

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

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

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

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

{
  "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).