Actions with public files and folders

Resources published by other users can be downloaded or copied to the “Downloads” folder. You can also request their metainformation.

In each request to other people's published resources, you must specify the public key that Yandex.Disk returns when publishing the file. You do not need to specify the OAuth token (or the Authorization header) in such requests.

Metainformation about a public resource

If you know the key for a public resource or the public link to it, you can request metainformation about this resource (the file properties or properties of the folder contents).

Request format

Use the GET method to send a request for metainformation.

https://cloud-api.yandex.net/v1/disk/public/resources
 ? public_key=<key of a published resource>
 & [path=<resource path>]
 & [sort=<sorting attribute>]
 & [limit=<maximum number of returned resources>]
 & [preview_size=<preview size>]
 & [preview_crop=<whether to crop the preview>]
 & [offset=<offset from the top of the list>]

`public_key` *	Key to a public resource, or the public link to a resource. The parameter value should be URL-encoded.
`path`	Relative path to a resource in a public folder. By specifying the key of the published folder in `public_key`, you can request metainformation for any resource in the folder. For example, to receive the properties of the `/foo` folder nested in a published folder, pass the `path=%2Ffoo` parameter. The path in the parameter value should be URL-encoded.
`sort`	The attribute used to sort the list of resources in the folder. The following properties of the Resource object can be used as a value: `name` (resource name) `path` (path to the resource on Yandex.Disk) `created` (date the resource was created) `modified` (date the resource was modified) `size` (file size) To sort in reverse order, add a hyphen to the parameter value, for example: `sort=-name`.
`limit`	The number of resources in the folder that should be described in the response (for example, for paginated output). The default value is 20.
`preview_size`	The desired size of the thumbnail (preview) file. The thumbnail link is returned in the `preview` key. You can define the exact size of the preview, or the length of one of the sides. The resulting image can be cropped to a square using the `preview_crop` parameter. Possible values Predefined length of the longest side. The image is reduced to the specified length of the longest side, and the proportions of the source image are preserved. For example, for the "S" size and a 120×200 image, a 90×150 preview is generated. For a 300×100 image, the preview is 150×50. Supported values: `"S"` — 150 pixels. `"M"` — 300 pixels. `"L"` — 500 pixels. `"XL"` — 800 pixels. `"XXL"` — 1024 pixels. `"XXXL"` — 1280 pixels. The exact width (for example, `"120"` or `"120x"`) or the exact height (for example, `"x145"`). The image is reduced to the specified width or height, and the proportions of the source image are preserved. If the `preview_crop` parameter is passed, a square with the set side length is cut out of the center of the reduced image. The exact size (in the `<width>x<height>` format, for example `"120x240"`). The image is reduced to the smallest of the specified dimensions, and the proportions of the source image are preserved. If the `preview_crop` parameter is passed, a section is cut from the center of the source image with the maximum size in the set proportions of width to height (in the example, this is 1 to 2). Then the cropped section is scaled to the specified dimensions.
`preview_crop`	This parameter crops the preview to the size specified in the `preview_size` parameter. Acceptable values: `false` — The parameter is ignored (default value). `true` — Crop the preview as follows: If only the width or height is passed, the image is reduced to this size with the proportions preserved. Then a square with the specified length of side is cut out of the center of the reduced image. If the exact size is passed (for example, `"120x240"`), a section is cut from the center of the source image with the maximum size in the set proportions of width to height. Then the cropped section is scaled to the specified dimensions.
`offset`	The number of resources from the top of the list that should be skipped in the response (used for paginated output). Let's say the /foo folder contains three files. For a folder metainformation request with the `offset=1` parameter, the Yandex.Disk API returns only the second and third file descriptions.

^* Required

Response format

If the request was processed without errors, the Yandex.Disk API responds with the code 200 OK and returns the metainformation about the requested resource in the response body, in the Resource object. If the request caused an error, the relevant response code is returned, and the response body contains the error description.

For non-empty folders, the response includes the ResourceList object (under the _embedded name). Each resource in the folder is an element of the items array. Regardless of the requested sorting, resources in the array are ordered by type: first all the subfolders are listed, then all the files.

In the metainformation for a published folder, all paths are relative to the folder itself.

An example response is shown for the published folder /foo, which contains the folder /bar and the file photo.png:

{  "public_key": "aSsmHLoeyBlJw8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",  "_embedded":  {    "sort": "",    "public_key": "kLsmHRoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",    "items": [    {      "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",      "name": "bar-1",      "created": "2014-05-22T14:30:16+04:00",      "modified": "2014-05-22T14:30:16+04:00",      "path": "/bar-1",      "type": "dir"    },    {      "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",      "preview": "https://downloader.disk.yandex.ru/preview/...",      "name": "photo.png",      "created": "2014-08-08T12:36:23+04:00",      "modified": "2014-08-08T12:36:23+04:00",      "path": "/photo.png",      "md5": "dc27c182eda45002d641b68937029301",      "type": "file",      "mime_type": "image/png",       "size": 29293    }    ],    "limit": 20,    "offset": 0,    "path": "/",    "total": 4  },  "name": "foo",  "created": "2014-05-22T14:30:09+04:00",  "public_url": "https://yadi.sk/d/AaaBbb1122Ccc",  "modified": "2014-05-22T14:30:09+04:00",  "path": "/",  "type": "dir"}

Response elements
Element	Description
`public_key`	Key of a published resource. It is included in the response only if the specified file or folder is published.
`public_url`	Link to a published resource. It is included in the response only if the specified file or folder is published.
`_embedded`	The resources located in the folder (contains the ResourceList object). It is included in the response only when folder metainformation is requested.
`preview`	Link to a small image (preview) for the file. It is included in the response only for files that support graphic formats. The preview can only be requested using the OAuth token of a user who has access to the file itself.
`name`	Resource name.
`custom_properties`	An object with all attributes set with the Adding metainformation for a resource request. Contains only keys in the `name:value` format (cannot contain objects or arrays).
`created`	The date and time when the resource was created, in ISO 8601 format.
`modified`	The date and time when the resource was modified, in ISO 8601 format.
`path`	Full path to the resource on Yandex.Disk. In metainformation for a published folder, paths are relative to the folder itself. For published files, the value of the key is always "/". For a resource located in the Trash, this attribute may have a unique ID appended to it (for example, `trash:/foo_1408546879`). Use this ID to differentiate the resource from other deleted resources with the same name.
`origin_path`	Path to the resource before it was moved to the Trash. Included in the response only for a request for metainformation about a resource in the Trash.
`md5`	MD5 hash of the file.
`type`	Resource type: “dir” — folder “file” — file
`mime_type`	The MIME type of the file.
`size`	File size.
Element	Description
`sort`	The field used for sorting the list.
`public_key`	The key of a published folder that contains resources from this list. It is included in the response only if metainformation about a public folder is requested.
`items`	Array of resources (Resource) contained in the folder. Regardless of the requested sorting, resources in the array are ordered by type: first all the subfolders are listed, then all the files.
`limit`	The maximum number of items in the `items` array; set in the request.
`offset`	How much to offset the beginning of the list from the first resource in the folder.
`path`	The path to the folder whose contents are described in this `ResourceList` object. For a public folder, the value of the attribute is always "/".
`total`	The total number of resources in the folder.

Response elements
Element	Description
`public_key`	Key of a published resource. It is included in the response only if the specified file or folder is published.
`public_url`	Link to a published resource. It is included in the response only if the specified file or folder is published.
`_embedded`	The resources located in the folder (contains the ResourceList object). It is included in the response only when folder metainformation is requested.
`preview`	Link to a small image (preview) for the file. It is included in the response only for files that support graphic formats. The preview can only be requested using the OAuth token of a user who has access to the file itself.
`name`	Resource name.
`custom_properties`	An object with all attributes set with the Adding metainformation for a resource request. Contains only keys in the `name:value` format (cannot contain objects or arrays).
`created`	The date and time when the resource was created, in ISO 8601 format.
`modified`	The date and time when the resource was modified, in ISO 8601 format.
`path`	Full path to the resource on Yandex.Disk. In metainformation for a published folder, paths are relative to the folder itself. For published files, the value of the key is always "/". For a resource located in the Trash, this attribute may have a unique ID appended to it (for example, `trash:/foo_1408546879`). Use this ID to differentiate the resource from other deleted resources with the same name.
`origin_path`	Path to the resource before it was moved to the Trash. Included in the response only for a request for metainformation about a resource in the Trash.
`md5`	MD5 hash of the file.
`type`	Resource type: “dir” — folder “file” — file
`mime_type`	The MIME type of the file.
`size`	File size.
Element	Description
`sort`	The field used for sorting the list.
`public_key`	The key of a published folder that contains resources from this list. It is included in the response only if metainformation about a public folder is requested.
`items`	Array of resources (Resource) contained in the folder. Regardless of the requested sorting, resources in the array are ordered by type: first all the subfolders are listed, then all the files.
`limit`	The maximum number of items in the `items` array; set in the request.
`offset`	How much to offset the beginning of the list from the first resource in the folder.
`path`	The path to the folder whose contents are described in this `ResourceList` object. For a public folder, the value of the attribute is always "/".
`total`	The total number of resources in the folder.

Downloading a public file or folder

You can download a resource published on Yandex.Disk if you know the key or public link to it. You can also use this operation to download individual files from public folders.

Request format

Use the GET method to send the request to download a file.

https://cloud-api.yandex.net/v1/disk/resources/download
 ? public_key=<key of a published resource>
 & [path=<resource path>]

public_key *

The public file or folder key.

The parameter value should be URL-encoded.

path

The path to the file within the public folder. Specify it if the public_key parameter contains the key of the public folder where the file is located.

The path in the parameter value should be URL-encoded.

^* Required

Response format

If the request was processed without errors, the API responds with the code 200 OK. The Link object in the response body returns the generated URL for downloading the file.

If the request caused an error, a relevant response code is returned, with the response body featuring the error description.

Sample response:

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

Response elements
Element	Description
`href`	URL. It may be a URL template; see the `templated` key.
`method`	The HTTP method for requesting the URL from the `href` key.
`templated`	Indicates a URL template according to RFC 6570. Possible values: “true” — URL template. Before sending a request to this address, put the desired parameter values in place of the values in curly brackets. “false” — The URL can be requested without changes.

Response elements
Element	Description
`href`	URL. It may be a URL template; see the `templated` key.
`method`	The HTTP method for requesting the URL from the `href` key.
`templated`	Indicates a URL template according to RFC 6570. Possible values: “true” — URL template. Before sending a request to this address, put the desired parameter values in place of the values in curly brackets. “false” — The URL can be requested without changes.

Use the GET method to download a file:

https://downloader.dst.yandex.ru/disk/53139aa0et584d3bac7eeab405d3574b/535320b4/YyjTJtEHob8R5WbpojJbiiUuU2HC_2JSTU0gW9qE0NHGW2uncmBjM_-IXun3Msyij96FTHQGSX-fDL-XwokDvA%3D%3D?uid=202727674&filename=photo.png&disposition=attachment&hash=&limit=0&content_type=application%2Fx-www-form-urlencoded&fsize=34524&hid=93528043563b8r55723a253f4730290a&media_type=document

If the request was processed without errors, the API responds with a file with the code 200 OK.

Saving a public file in "Downloads"

A file published on Yandex.Disk can be copied to the “Dowloads” folder on the user's Disk. To do this, you need to know the key to the file or the public link to it. If you know the public folder key, you can also copy individual files from it.

Request format

Use the POST method to send the request to save a file.

https://cloud-api.yandex.net/v1/disk/resources/download
 ? public_key=<key of a published resource>
 & [path=<resource path>]
 & [name=<name of the saved file>]

public_key *

Key for a stored resource.

The parameter value should be URL-encoded.

path

The path within the public folder. Specify it if the public_key parameter contains the key of the public folder where the file is located.

The path in the parameter value should be URL-encoded.

name

The name for saving the file in the “Downloads” folder.

^* Required

Response format

Saving a public file to a user's Disk may take some time. Depending on the operation status, the Yandex.Disk server returns one of these responses:

If the request was completed without errors by the time of the response, the API responds with the code 201 Created and returns the link to the saved file in the response body (in the Link object).

Sample response:

{
  "href": "https://cloud-api.yandex.net/v1/disk/resources?path=disk%3A%2F%D0%97%D0%B0%D0%B3%D1%80%D1%83%D0%B7%D0%BA%D0%B8%photo.png",
  "method": "GET",
  "templated": false
}

Response elements
Element	Description
`href`	URL. It may be a URL template; see the `templated` key.
`method`	The HTTP method for requesting the URL from the `href` key.
`templated`	Indicates a URL template according to RFC 6570. Possible values: “true” — URL template. Before sending a request to this address, put the desired parameter values in place of the values in curly brackets. “false” — The URL can be requested without changes.

Response elements
Element	Description
`href`	URL. It may be a URL template; see the `templated` key.
`method`	The HTTP method for requesting the URL from the `href` key.
`templated`	Indicates a URL template according to RFC 6570. Possible values: “true” — URL template. Before sending a request to this address, put the desired parameter values in place of the values in curly brackets. “false” — The URL can be requested without changes.

If the save operation was started but has not yet finished, Yandex.Disk responds with the code 202 Accepted.

Applications must track the status of requested operations. Yandex.Disk returns the link to the status of the operation launched by the request. The link is included in the Link object in the response body.

Sample response:

{  "href": "https://cloud-api.yandex.net/v1/disk/operations/33ca7d03ab21ct41b4a40182e78d828a3f8b72cdb5f4c0e94cc4b1449a63a2fe",  "method": "GET",  "templated": false}

Response elements
Element	Description
`href`	URL. It may be a URL template; see the `templated` key.
`method`	The HTTP method for requesting the URL from the `href` key.
`templated`	Indicates a URL template according to RFC 6570. Possible values: “true” — URL template. Before sending a request to this address, put the desired parameter values in place of the values in curly brackets. “false” — The URL can be requested without changes.

Response elements
Element	Description
`href`	URL. It may be a URL template; see the `templated` key.
`method`	The HTTP method for requesting the URL from the `href` key.
`templated`	Indicates a URL template according to RFC 6570. Possible values: “true” — URL template. Before sending a request to this address, put the desired parameter values in place of the values in curly brackets. “false” — The URL can be requested without changes.

If the request caused an error, a relevant response code is returned, with the response body featuring the error description.