List of published resources

The API returns a list of resources published on the user's Disk. Resources in the list are sorted in order of publishing, from latest to earliest.

The list can be filtered by resource type to get only files or only folders.

Request format

Use the GET method to send a request for the list of published resources.

https://cloud-api.yandex.net/v1/disk/resources/public
 ? [limit=<number of files in the list>]
 & [offset=<offset from the top of the list>]
 & [type=<type of requested files>]
 & [fields=<properties to include in the response>]
 & [preview_size=<preview size>]
limit

The number of published files that should be described in the response (for example, for paginated output).

The default value is 20.

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 there are three published files on user's Disk. If we request a list of them with the offset=1 parameter, the Yandex.Disk API returns only the descriptions of the second and third files.

type

Type of resource. Acceptable values:

  • "dir" — Folder.

  • "file" — File.

fields

List of JSON keys to include in the response. Keys that are not included in this list will be discarded when forming the response. If the parameter is omitted, the response is returned in full, without discarding anything.

Key names should be comma-separated, and embedded keys should be separated by dots. For example: name, _embedded. items. path.

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.

limit

The number of published files that should be described in the response (for example, for paginated output).

The default value is 20.

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 there are three published files on user's Disk. If we request a list of them with the offset=1 parameter, the Yandex.Disk API returns only the descriptions of the second and third files.

type

Type of resource. Acceptable values:

  • "dir" — Folder.

  • "file" — File.

fields

List of JSON keys to include in the response. Keys that are not included in this list will be discarded when forming the response. If the parameter is omitted, the response is returned in full, without discarding anything.

Key names should be comma-separated, and embedded keys should be separated by dots. For example: name, _embedded. items. path.

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.

Response format

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

Sample response:

{   "items": [      {        "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",        "name": "photo2.png",        "preview": "https://downloader.disk.yandex.ru/preview/...",        "created": "2014-04-22T14:57:13+04:00",        "modified": "2014-04-22T14:57:14+04:00",        "path": "disk:/foo/photo2.png",        "md5": "53f4dc6379c8f95ddf11b9508cfea271",        "type": "file",        "mime_type": "image/png",        "size": 54321      },      {        "public_key": "kLsmHRoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",        "name": "photo1.png",        "preview": "https://downloader.disk.yandex.ru/preview/...",        "created": "2014-04-21T14:57:13+04:00",        "modified": "2014-04-21T14:57:14+04:00",        "path": "disk:/foo/photo1.png",        "md5": "4334dc6379c8f95ddf11b9508cfea271",        "type": "file",        "mime_type": "image/png",        "size": 34567      }    ],    "type": "file",    "limit": 20,    "offset": 0  }
Response elements
Element Description
items Array of recently uploaded files ( Resource ).
limit

The maximum number of items in the items array; set in the request.
type

Resource type:

  • “dir” — folder
  • “file” — file
offset

How much to offset the beginning of the list from the first resource in the folder.
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.
Response elements
Element Description
items Array of recently uploaded files ( Resource ).
limit

The maximum number of items in the items array; set in the request.
type

Resource type:

  • “dir” — folder
  • “file” — file
offset

How much to offset the beginning of the list from the first resource in the folder.
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.