Яндекс Диск REST API API

Отрасль: Облака и хостинг. Актуально на 2026-10-24.

REST API Яндекс Диска: данные о Диске пользователя, метаинформация о файлах и папках, загрузка и скачивание, создание папок, копирование, перемещение, удаление, публикация и статус длительных операций. Приложение получает OAuth-токен с нужными правами и работает с Диском одного пользователя. Запросы и ответы — JSON.

Сценарии

Загрузить файл на Диск

Бэкапы, отчёты, сканы документов — автоматически в папку на Яндекс Диске.

1. Зарегистрируй OAuth-приложение с правами Диска (например, cloud_api:disk.write) и получи токен пользователя. Передавай его в заголовке Authorization: OAuth <токен>.
2. Получи ссылку для загрузки: GET /v1/disk/resources/upload с path — путём на Диске в URL-кодировке (например, disk:/Backups/db-2026-10-24.sql.gz) и overwrite = true, если файл можно перезаписать.
3. Загрузи файл методом PUT на href из ответа в течение 30 минут — без OAuth-токена. 201 — файл на Диске, 202 — принят и скоро появится.
4. Нужной папки нет — создай её заранее: PUT /v1/disk/resources с path (ответ 201; 409 — папка уже есть).
5. Ошибка 507 — на Диске не хватает места, 413 — файл слишком большой.

H="Authorization: OAuth $YADISK_TOKEN"
curl -X PUT -G https://cloud-api.yandex.net/v1/disk/resources -H "$H" --data-urlencode 'path=disk:/Backups'

HREF=$(curl -s -G https://cloud-api.yandex.net/v1/disk/resources/upload -H "$H" \
  --data-urlencode 'path=disk:/Backups/db-2026-10-24.sql.gz' -d overwrite=true | jq -r .href)
curl -T db-2026-10-24.sql.gz "$HREF"

Скачать файл с Диска

Забрать файл, который пользователь положил в папку, — для обработки на сервере.

1. Получи ссылку: GET /v1/disk/resources/download с path к файлу.
2. Скачай файл по href из ответа обычным GET-запросом. Ссылка действует ограниченное время — запрашивай новую перед каждым скачиванием.
3. Чтобы найти файлы в папке, запроси её содержимое: GET /v1/disk/resources с path, limit, offset и sort (например, -modified — сначала новые). Список — в _embedded.items.

curl -s -G https://cloud-api.yandex.net/v1/disk/resources -H "$H" \
  --data-urlencode 'path=disk:/Входящие' -d limit=20 -d sort=-modified -d 'fields=_embedded.items.name,_embedded.items.path'

HREF=$(curl -s -G https://cloud-api.yandex.net/v1/disk/resources/download -H "$H" \
  --data-urlencode 'path=disk:/Входящие/scan-001.pdf' | jq -r .href)
curl -L -o scan-001.pdf "$HREF"

Поделиться файлом по публичной ссылке

Отправить клиенту ссылку на документ или архив на Диске.

1. Опубликуй ресурс: PUT /v1/disk/resources/publish с path. Ответ 200 — объект Link на метаинформацию.
2. Публичная ссылка — в поле public_url: получи её через GET /v1/disk/resources с path и fields = public_url.
3. Чтобы закрыть доступ, сними публикацию — метод /v1/disk/resources/unpublish с тем же path.

curl -X PUT -G https://cloud-api.yandex.net/v1/disk/resources/publish -H "$H" --data-urlencode 'path=disk:/Договоры/договор-1042.pdf'
curl -s -G https://cloud-api.yandex.net/v1/disk/resources -H "$H" \
  --data-urlencode 'path=disk:/Договоры/договор-1042.pdf' -d fields=public_url | jq -r .public_url

Скопировать, переместить или удалить папку

Разложить файлы по папкам, архивировать старое, очистить место.

1. Скопируй: POST /v1/disk/resources/copy с from и path. Перемести: POST /v1/disk/resources/move с теми же параметрами. Удали: DELETE /v1/disk/resources с path (permanently = true — без Корзины).
2. Файл или пустая папка обрабатываются сразу (201 или 204). Для непустой папки придёт 202 и ссылка на операцию.
3. Проверяй статус: GET /v1/disk/operations/{operation_id} — success, in-progress или failed (тогда повтори исходный запрос).
4. Загрузить файл прямо из интернета на Диск можно через POST /v1/disk/resources/upload с url и path — это тоже длительная операция.

OP=$(curl -s -X POST -G https://cloud-api.yandex.net/v1/disk/resources/move -H "$H" \
  --data-urlencode 'from=disk:/Отчёты/2025' --data-urlencode 'path=disk:/Архив/Отчёты 2025' | jq -r .href)
curl -s "$OP" -H "$H"   # {"status": "in-progress"} → {"status": "success"}

Базовые URL

• Боевой: https://cloud-api.yandex.net
• Загрузка и скачивание файлов идут через отдельные адреса, которые API возвращает в поле .: href

Авторизация

Тип: OAuth 2.0

OAuth-токен Яндекс ID передаётся в заголовке Authorization с типом токена перед значением. Для получения токена создают OAuth-приложение с правами Диска (cloud_api:disk.write, cloud_api:disk.read, cloud_api:disk.app_folder, cloud_api:disk.info) и открывают https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>.

Заголовки Accept и Content-Type — только application/json.

Authorization: OAuth 0c4181a7c2cf4521964a72ff57a34a07

Методы

GET /v1/disk/ — Данные о Диске

Возвращает объект Disk: объём Корзины, общий и занятый объём, пути системных папок.

Пример ответа:

{
  "trash_size": 4631577437,
  "total_space": 319975063552,
  "used_space": 26157681270,
  "system_folders":
  {
    "applications": "disk:/Приложения",
    "downloads": "disk:/Загрузки/"
  }
}

GET /v1/disk/resources — Метаинформация о файле или папке

Для ресурса в Корзине — GET /v1/disk/trash/resources.

Параметр	Где	Тип	Обяз.	Описание
path	query	string	да	Путь к ресурсу, в URL-кодировке
fields	query	string	нет	Ключи ответа через запятую, вложенные — через точку
limit	query	integer	нет	Число вложенных ресурсов, по умолчанию 20
offset	query	integer	нет	Сколько вложенных ресурсов пропустить
preview_crop	query	boolean	нет	Обрезать превью до квадрата, по умолчанию false
preview_size	query	string	нет	Размер превью: S–XXXL, ширина, высота или ШxВ
sort	query	string	нет	name, path, created, modified, size; дефис — обратный порядок

GET /v1/disk/resources/upload — URL для загрузки файла

Возвращает ссылку для загрузки; файл затем отправляется методом PUT на href в течение 30 минут, без OAuth-токена. Успешная загрузка — 201 Created, 202 Accepted — файл принят, но ещё не перенесён на Диск.

Пример ответа (сокращён):

Параметр	Где	Тип	Обяз.	Описание
path	query	string	да	Путь к файлу, в URL-кодировке; имя до 255 символов, путь до 32760
overwrite	query	boolean	нет	Перезаписать существующий файл, по умолчанию false
fields	query	string	нет	Ключи ответа

Пример запроса:

{
  "operation_id": "cbb77e87...",
  "href": "https://uploader1d.dst.yandex.net:443/upload-target/...",
  "method": "PUT",
  "templated": false
}

POST /v1/disk/resources/upload — Загрузка файла из интернета

Асинхронно скачивает файл по URL на Диск; ответ 202 Accepted со ссылкой на статус операции.

Параметр	Где	Тип	Обяз.	Описание
url	query	string	да	Адрес файла, в URL-кодировке
path	query	string	да	Путь на Диске, в URL-кодировке
fields	query	string	нет	Ключи ответа
disable_redirects	query	boolean	нет	Запретить переход по редиректу, по умолчанию false

GET /v1/disk/resources/download — Ссылка на скачивание файла

Параметр	Где	Тип	Обяз.	Описание
path	query	string	да	Путь к файлу, в URL-кодировке
fields	query	string	нет	Ключи ответа

Пример ответа:

{
  "href": "https://downloader.dst.yandex.ru/disk/...",
  "method": "GET",
  "templated": false
}

PUT /v1/disk/resources — Создание папки

Успех — 201 Created и объект Link на метаинформацию папки.

Параметр	Где	Тип	Обяз.	Описание
path	query	string	да	Путь к папке, например %2FMusic
fields	query	string	нет	Ключи ответа

POST /v1/disk/resources/copy — Копирование

Файл или пустая папка — синхронно (201 Created); непустая папка — асинхронно (202 Accepted, ссылка на статус операции).

Параметр	Где	Тип	Обяз.	Описание
from	query	string	да	Путь к копируемому ресурсу
path	query	string	да	Путь к копии, до 32760 символов
overwrite	query	boolean	нет	Перезаписать ресурсы с совпадающими именами, по умолчанию false
force_async	query	boolean	нет	Выполнить асинхронно
fields	query	string	нет	Ключи ответа

POST /v1/disk/resources/move — Перемещение

Ответы такие же, как у копирования.

Параметр	Где	Тип	Обяз.	Описание
from	query	string	да	Текущий путь к ресурсу
path	query	string	да	Новый путь, до 32760 символов
overwrite	query	boolean	нет	Перезаписать, по умолчанию false
force_async	query	boolean	нет	Выполнить асинхронно
fields	query	string	нет	Ключи ответа

DELETE /v1/disk/resources — Удаление

Файл или пустая папка — 204 No Content; непустая папка — 202 Accepted со ссылкой на статус операции.

Параметр	Где	Тип	Обяз.	Описание
path	query	string	да	Путь к ресурсу
permanently	query	boolean	нет	Удалить без Корзины, по умолчанию false
md5	query	string	нет	MD5 файла для проверки, что удаляется нужный файл
force_async	query	boolean	нет	Выполнить асинхронно
fields	query	string	нет	Ключи ответа

PUT /v1/disk/resources/publish — Публикация ресурса

Успех — 200 OK и объект Link. Настройки доступа передаются в теле в объекте public_settings.

Параметр	Где	Тип	Обяз.	Описание
path	query	string	да	Путь к публикуемому ресурсу
allow_address_access	query	boolean	нет	Признак формата запроса, по умолчанию false
public_settings	body	object	нет	Настройки публичного доступа

GET /v1/disk/operations/{operation_id} — Статус операции

Статусы: success, failed (повторите исходный запрос), in-progress.

Параметр	Где	Тип	Обяз.	Описание
operation_id	path	string	да	Идентификатор операции из ответа длительного запроса

Пример ответа:

{
  "status":"success"
}

Нюансы

• Пути передаются в URL-кодировке; disk:/foo и /foo — одна и та же папка.
• Длительные операции (копирование, перемещение, удаление непустых папок, загрузка из интернета) возвращают 202 Accepted и объект Link на статус — статус нужно опрашивать самостоятельно.
• Объект Link: href (URL), method (HTTP-метод для него), templated (нужна ли подстановка параметров по RFC 6570).
• Ссылки на загрузку действуют 30 минут, ссылки на скачивание — ограниченное время.
• Один токен даёт одному приложению доступ к Диску одного пользователя; потерянный токен в кабинете не найти — запросите новый.

Ошибки

Код	Описание
400	Некорректные данные
401	Не авторизован
403	API недоступно или недостаточно прав (например, файлы занимают больше места, чем доступно)
404	Ресурс не найден
406	Ресурс нельзя представить в запрошенном формате
409	Ресурс уже существует
413	Файл слишком большой (UPLOAD_FILE_SIZE_LIMIT_EXCEEDED)
423	Технические работы или превышен лимит загрузки (UPLOAD_TRAFFIC_LIMIT_EXCEEDED)
429	Слишком много запросов
503	Сервис временно недоступен
507	Недостаточно свободного места

Источники

• Яндекс Диск — REST API
• Доступ к API
• Данные о Диске
• Метаинформация
• Загрузка файла
• Загрузка из интернета
• Скачивание
• Создание папки
• Копирование
• Перемещение
• Удаление
• Публикация
• Статус операции
• JSON-объекты в ответах

---

Если этого недостаточно — официальная документация: https://yandex.ru/dev/disk-api/doc/ru/ JSON: https://mcp-everything.ru/api/integrations/yandex-disk. MCP: https://mcp-everything.ru/mcp