---
metadata:
  - name: generator
    content: Diplodoc Platform v5.44.0
alternate:
  - https://yandex.ru/dev/disk-api/doc/en/reference/public.md
  - https://yandex.ru/dev/disk-api/doc/ru/reference/public.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/disk-api/doc/en/llms.txt

# Actions with public files and folders

{% note alert %}

The meta information about the requested resource is unavailable if the owner of the link to the file or folder has [disabled downloads](https://yandex.com/support/disk/share/sharing-to-me.html#restriction).

{% endnote %}

Resources published by other users can be downloaded or copied to the Downloads folder. You can also request their meta information.

Each request to other users' published resources must contain the public key that Yandex Disk returns when [publishing the file](https://yandex.ru/dev/disk-api/doc/en/reference/publish.md). You don't have to specify the OAuth token (or the `Authorization` header) in such requests.

## Meta information of public resources {#meta}

If you know the key or public link to the resource, you can request meta information of this resource (the file properties or the folder properties and contents).

### Request format {#meta-request}

Use the GET method to send a request for meta information.
```
https://cloud-api.yandex.net/v1/disk/public/resources
 ? [public_key](*popup-public_key_1)=<key of a published resource>
 & [[path](*popup-path_1)=<resource path>]
 & [[sort](*popup-sort)=<sorting attribute>]
 & [[limit](*popup-limit)=<maximum number of returned resources>]
 & [[preview_size](*popup-preview_size)=<preview size>]
 & [[preview_crop](*popup-preview_crop)=<preview crop flag>]
 & [[offset](*popup-offset)=<offset from the top of the list>]
```

public_key[*](*popup-a)
: The key of a published resource or a public link to a resource. <br>
The parameter value should be encoded in URL format.


path
: Relative path to the resource in the public folder. By specifying the key of the published folder in the `public_key` parameter, you can request meta information for any resource in the folder. For example, to receive the properties of the `/foo` folder nested in the published folder, pass the `path=%2Ffoo` parameter. <br>
  
  <!-- source: en/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->
  The path in the parameter value should be encoded in URL format.
  <!-- endsource: en/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->


sort
: The attribute by which the list of resources should be sorted in the folder. The following properties of the [Resource](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#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. <br>
  
  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). <br>
  
  <!-- source: en/_includes/reference/parameters-warehouse/id-format/limit-default.md -->
  The default value is 20.
  <!-- endsource: en/_includes/reference/parameters-warehouse/id-format/limit-default.md -->


preview_size
: The required size of the reduced image (file preview). Its link should be returned in the `preview` key. <br>
You can specify the exact preview dimensions or the length of one side. The resulting image can be cropped to a square using the `preview_crop` parameter. <br>
  
  {% cut "Possible values" %}
    
  - Predefined length of the longest side.
    
    The image is reduced to the specified size along its larger dimension while preserving the aspect ratio of the original image. 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.
    
  - Exact width (for example, `"120"` or `"120x"`) or exact height (for example, `"x145"`).
    
    The image is reduced to the specified width or height while preserving the aspect ratio of the original image.
    
    If the `preview_crop` parameter is passed, a square with the specified side length is cropped out of the center of the reduced image.
    
  - Exact size (in the `<width>x<height>` format, for example, `"120x240"`).
    
    The image is reduced to the smallest of the specified dimensions while preserving the aspect ratio of the original image.
    
    If the `preview_crop` is passed, a section of maximum size with the specified aspect ratio (in the example: 1 to 2) is cropped out of the center of the original image. Then the cropped section is scaled to the specified dimensions.
    
  {% endcut %}


preview_crop
: This parameter crops the preview to the size specified in the `preview_size` parameter. <br>
Supported values:
- `false`: the parameter is ignored (default value).
- `true`: the preview is cropped as follows: <br><br>
  * If only the width or height is passed, the image is reduced to this size with the same aspect ratio. Then a square with the specified side length is cropped out of the center of the reduced image. <br>
  * If the exact size is passed (for example, "120x240"), a section of maximum size with the specified aspect ratio is cropped out of the center of the source image. Then the cropped section is scaled to the specified dimensions.


offset
: <!-- source: en/_includes/reference/parameters-warehouse/id-format/offset-desc.md -->
  The number of resources starting from the top of the list that should be skipped in the response (for example, for paginated output).
  <!-- endsource: en/_includes/reference/parameters-warehouse/id-format/offset-desc.md -->
  
  <!-- source: en/_includes/reference/parameters-warehouse/id-format/offset-ex.md -->
  Let's say the `/foo` folder contains three files. If you request the folder meta information with the offset parameter set to 1 (`offset=1`), the Yandex Disk API returns only the second and third file information.
  <!-- endsource: en/_includes/reference/parameters-warehouse/id-format/offset-ex.md -->


\*  Required parameter.

### Response format {#meta-response}

<!-- source: en/_includes/reference/meta/id-response/response-code.md -->
If the request is processed without errors, the API returns the `200 OK` code and meta information about the requested resource within the [Resource](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#resource) object in the response body.
<!-- endsource: en/_includes/reference/meta/id-response/response-code.md -->

<!-- source: en/_includes/reference/response-error.md -->
If the request caused an error, the relevant response code is returned, and the response body contains an [error description](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#error).
<!-- endsource: en/_includes/reference/response-error.md -->

For non-empty folders, the response includes a [ResourceList](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#resourcelist) object (under the `_embedded`name). Each resource in the folder is an element of the `items` array. Regardless of the requested sort, resources in the array are ordered by type: nested folders go first, followed by folder files.

The published folder's meta information should include all paths relative to the folder.

<!-- source: en/_includes/reference/meta/id-response/response-ex.md -->
Here's an example response for the published `/foo` folder that contains the `/bar` folder and the `photo.png` file:
<!-- endsource: en/_includes/reference/meta/id-response/response-ex.md -->


```json
{
  "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"
}
```


<!-- source: en/_includes/reference/response-objects/id-link/resource-table.md -->


#|
|| **Element** | **Description** ||
||`public_key` | Key of a published resource.

It's included in the response only if the specified file or folder is published.||
||`public_url` | Link to a published resource.

It's included in the response only if the specified file or folder is published.||
||`_embedded` | The resources in the folder (contains the [ResourceList](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#resourcelist) object).

It's included in the response only when the folder meta information is requested.||
||`preview` | Link to a preview image of the file. It's included in the response only for supported image formats.

The preview can only be requested with the OAuth token of a user who has access to the file.||
||`name` | Resource name.||
||`custom_properties` | The object contains all attributes specified by the [Adding resource meta information](https://yandex.ru/dev/disk-api/doc/en/reference/meta-add.md) request. Contains only keys of the `name:value` type (can't contain objects or arrays).||
||`created` | The date and time when the resource was created, in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format.||
||`modified` | The date and time when the resource was modified, in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format.||
||`path` | Full path to the resource on Yandex Disk.

The meta information of the published folder indicates paths relative to the folder. For published files, the key value is always "/".

For a resource in Trash, this attribute may have a unique ID added to it (for example, `trash:/foo_1408546879`). This ID differentiates it from other deleted resources with the same name.||
||`origin_path` | Path to the resource before it was moved to Trash.

Only included in the response to a meta information request related to a resource in 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.||
   |#
<!-- endsource: en/_includes/reference/response-objects/id-link/resource-table.md -->

<!-- source: en/_includes/reference/response-objects/id-link/resourcelist-table.md -->


#|
|| **Element** | **Description** ||
||`sort` | The field by which the list is sorted.||
||`public_key` | The key of the published folder that contains resources from this list.

It's included in the response only if a [public folder's meta information](https://yandex.ru/dev/disk-api/doc/en/reference/public.md#meta) is requested.||
||`items` | Array of resources ([Resource](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#resource)) located in the folder.

Regardless of the requested sort, resources in the array are ordered by type: nested folders go first, followed by folder files.||
||`limit` | The maximum number of items in the `items` array set in the request.||
||`offset` | The offset from the first resource in the folder to the top of the list.||
||`path` | The path to the folder whose contents are described in the `ResourceList` object.

For a [public folder](https://yandex.ru/dev/disk-api/doc/en/reference/public.md#meta), the attribute value is always "/".||
||`total` | The total number of resources in the folder.||
|#
<!-- endsource: en/_includes/reference/response-objects/id-link/resourcelist-table.md -->


## Downloading a public file or folder {#download}

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

### Request format {#download-request}

Use the GET method to send a request for downloading a file.
```
https://cloud-api.yandex.net/v1/disk/public/resources/download
 ? [public_key](*popup-public_key_2)=<key of a published resource>
 & [[path](*popup-path_2)=<resource path>]
```

public_key[*](*popup-a)
: The key of a public file or folder. <br>
The parameter value should be encoded in URL format.


path
: The path to the file in the public folder. Specify it if the`public_key` parameter contains the key of the public folder where the file is located. <br>
  
  <!-- source: en/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->
  The path in the parameter value should be encoded in URL format.
  <!-- endsource: en/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->


\* Required parameter.


### Response format {#download-response}

<!-- source: en/_includes/reference/content/id-url-request/response-200.md -->
If the request is processed without errors, the API returns the `200 OK` code. The response body includes a [Link](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#link) object with the generated URL for downloading the file.
<!-- endsource: en/_includes/reference/content/id-url-request/response-200.md -->

<!-- source: en/_includes/reference/response-error.md -->
If the request caused an error, the relevant response code is returned, and the response body contains an [error description](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#error).
<!-- endsource: en/_includes/reference/response-error.md -->

Sample response:

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

<!-- source: en/_includes/reference/response-objects/id-link/link-table.md -->


#|
|| **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](http://tools.ietf.org/html/rfc6570). Possible values:

- "true" — URL template. To send a request to this address, replace the placeholder values in the curly brackets with the parameter values.
- "false" — The URL can be requested without changes.||
   |#
<!-- endsource: en/_includes/reference/response-objects/id-link/link-table.md -->


<!-- source: en/_includes/reference/content/id-response-upload/zaberun-intro.md -->
Use the GET method to download the file:
<!-- endsource: en/_includes/reference/content/id-response-upload/zaberun-intro.md -->


```no-highlight
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
```

<!-- source: en/_includes/reference/content/id-response-upload/zaberun-ok.md -->
If the request is processed without errors, the API returns the `200 OK` code.
<!-- endsource: en/_includes/reference/content/id-response-upload/zaberun-ok.md -->



## Saving a public file to the Downloads folder {#save}

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

### Request format {#save-request}

Use the POST method to send a request for saving a file.
```
https://cloud-api.yandex.net/v1/disk/public/resources/save-to-disk
 ? [public_key](*popup-public_key_3)=<key of a published resource>
 & [[path](*popup-path_3)=<resource path>]
 & [[name](*popup-name)=<name of the saved file>]
```

public_key[*](*popup-a)
: The key of the resource to save. <br>
The parameter value should be encoded in URL format.



path
: The path in the public folder. Specify it if the`public_key` parameter contains the key of the public folder where the file is located. <br>
  
  <!-- source: en/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->
  The path in the parameter value should be encoded in URL format.
  <!-- endsource: en/_includes/reference/parameters-warehouse/id-format/path-encoding.md -->


name
: The name for saving the file in the Downloads folder.

\* Required parameter.


### Response format {#save-response}

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


{% list tabs %}

- Operation completed


   If the request is processed without errors, the API returns the `201 Created` code. The [Link](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#link) object in the response body contains the link to the saved file.

   Sample response:

   ```json
   {
     "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
   }
   ```

   {% include [link-table](../_includes/reference/response-objects/id-link/link-table.md) %}



- Operation in progress


   If saving has started but not completed yet, Yandex Disk returns the `202 Accepted` code.

   Apps must track the [status of requested operations](https://yandex.ru/dev/disk-api/doc/en/reference/operations.md). Yandex Disk returns a link to the status of the requested operation within the [Link](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#link) object in the response body.

   Sample response:

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

   {% include [link-table](../_includes/reference/response-objects/id-link/link-table.md) %}


- Error

   <!-- source: en/_includes/reference/response-error.md -->
   If the request caused an error, the relevant response code is returned, and the response body contains an [error description](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#error).
   <!-- endsource: en/_includes/reference/response-error.md -->

{% endlist %}

[*popup-public_key_1]: The key of a published resource or a public link to a resource. <br>
The parameter value should be encoded in URL format.

[*popup-path_1]: Relative path to the resource in the public folder. By specifying the key of the published folder in the `public_key` parameter, you can request meta information for any resource in the folder. For example, to receive the properties of the `/foo` folder nested in the published folder, pass the `path=%2Ffoo` parameter. <br>
  
  
The path in the parameter value should be encoded in URL format.

[*popup-sort]: The attribute by which the list of resources should be sorted in the folder. The following properties of the [Resource](https://yandex.ru/dev/disk-api/doc/en/reference/response-objects.md#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. <br>
  
  To sort in reverse order, add a hyphen to the parameter value. For example: `sort=-name`.

[*popup-limit]: The number of resources in the folder that should be described in the response (for example, for paginated output). <br>
  
  
The default value is 20.

[*popup-preview_size]: The required size of the reduced image (file preview). Its link should be returned in the `preview` key. <br>
You can specify the exact preview dimensions or the length of one side. The resulting image can be cropped to a square using the `preview_crop` parameter. <br>
  
  {% cut "Possible values" %}
    
  - Predefined length of the longest side.
    
    The image is reduced to the specified size along its larger dimension while preserving the aspect ratio of the original image. 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.
    
  - Exact width (for example, `"120"` or `"120x"`) or exact height (for example, `"x145"`).
    
    The image is reduced to the specified width or height while preserving the aspect ratio of the original image.
    
    If the `preview_crop` parameter is passed, a square with the specified side length is cropped out of the center of the reduced image.
    
  - Exact size (in the `<width>x<height>` format, for example, `"120x240"`).
    
    The image is reduced to the smallest of the specified dimensions while preserving the aspect ratio of the original image.
    
    If the `preview_crop` is passed, a section of maximum size with the specified aspect ratio (in the example: 1 to 2) is cropped out of the center of the original image. Then the cropped section is scaled to the specified dimensions.
    
  {% endcut %}

[*popup-preview_crop]: This parameter crops the preview to the size specified in the `preview_size` parameter. <br>
Supported values:
- `false`: the parameter is ignored (default value).
- `true`: the preview is cropped as follows: <br><br>
  * If only the width or height is passed, the image is reduced to this size with the same aspect ratio. Then a square with the specified side length is cropped out of the center of the reduced image. <br>
  * If the exact size is passed (for example, "120x240"), a section of maximum size with the specified aspect ratio is cropped out of the center of the source image. Then the cropped section is scaled to the specified dimensions.

[*popup-offset]: 
The number of resources starting from the top of the list that should be skipped in the response (for example, for paginated output).

  
  
Let's say the `/foo` folder contains three files. If you request the folder meta information with the offset parameter set to 1 (`offset=1`), the Yandex Disk API returns only the second and third file information.

[*popup-public_key_2]: The key of a public file or folder. <br>
The parameter value should be encoded in URL format.

[*popup-path_2]: The path to the file in the public folder. Specify it if the`public_key` parameter contains the key of the public folder where the file is located. <br>
  
  
The path in the parameter value should be encoded in URL format.

[*popup-public_key_3]: The key of the resource to save. <br>
The parameter value should be encoded in URL format.

[*popup-path_3]: The path in the public folder. Specify it if the`public_key` parameter contains the key of the public folder where the file is located. <br>
  
  
The path in the parameter value should be encoded in URL format.

[*popup-name]: The name for saving the file in the Downloads folder.

[*popup-a]: Required parameter.
{% included (../_includes/reference/response-objects/id-link/link-table.md) %}



#|
|| **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](http://tools.ietf.org/html/rfc6570). Possible values:

- "true" — URL template. To send a request to this address, replace the placeholder values in the curly brackets with the parameter values.
- "false" — The URL can be requested without changes.||
   |#


{% endincluded %}