---
slug: "yandex-disk"
name: "Яндекс Диск REST API"
vendor: "Яндекс"
industry: "cloud"
docsUrl: "https://yandex.ru/dev/disk-api/doc/ru/"
version: 2
updatedAt: "2026-10-24"
---

# Яндекс Диск REST 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 — файл слишком большой.

```bash
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.

```bash
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.

```bash
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 — это тоже длительная операция.

```bash
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: объём Корзины, общий и занятый объём, пути системных папок.

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

```json
{
  "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 | нет | Ключи ответа |

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

```json
{
  "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 | да | Идентификатор операции из ответа длительного запроса |

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

```json
{
  "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](https://yandex.ru/dev/disk-api/doc/ru/)
- [Доступ к API](https://yandex.ru/dev/disk-api/doc/ru/concepts/quickstart)
- [Данные о Диске](https://yandex.ru/dev/disk-api/doc/ru/reference/capacity)
- [Метаинформация](https://yandex.ru/dev/disk-api/doc/ru/reference/meta)
- [Загрузка файла](https://yandex.ru/dev/disk-api/doc/ru/reference/upload)
- [Загрузка из интернета](https://yandex.ru/dev/disk-api/doc/ru/reference/upload-ext)
- [Скачивание](https://yandex.ru/dev/disk-api/doc/ru/reference/content)
- [Создание папки](https://yandex.ru/dev/disk-api/doc/ru/reference/create-folder)
- [Копирование](https://yandex.ru/dev/disk-api/doc/ru/reference/copy)
- [Перемещение](https://yandex.ru/dev/disk-api/doc/ru/reference/move)
- [Удаление](https://yandex.ru/dev/disk-api/doc/ru/reference/delete)
- [Публикация](https://yandex.ru/dev/disk-api/doc/ru/reference/publish)
- [Статус операции](https://yandex.ru/dev/disk-api/doc/ru/reference/operations)
- [JSON-объекты в ответах](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects)

---

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