File and folder meta information

To request a file or folder meta information, specify the path to the resource on Yandex Disk. Meta information contains the properties of files and folders and the properties and contents of nested folders.

There's a separate request for meta information of public resources that don't belong to the user.

Request format

Use the GET method to send a request for meta information. The request URL is slightly different for resources located in Trash.

https://cloud-api.yandex.net/v1/disk/resources
 ? path=<resource path>
 & [fields=<properties to include in the response>]
 & [limit=<maximum number of returned resources>]
 & [offset=<offset from the top of the list>]
 & [preview_crop=<preview crop flag>]
 & [preview_size=<preview size>]
 & [sort=<sorting attribute>]

https://cloud-api.yandex.net/v1/disk/trash/resources
 ? path=<resource path>
 & [fields=<properties to include in the response>]
 & [limit=<maximum number of returned resources>]
 & [offset=<offset from the top of the list>]
 & [preview_crop=<preview crop flag>]
 & [preview_size=<preview size>]
 & [sort=<sorting attribute>]
path*

The path to the resource relative to the Yandex Disk root directory. The path to the resource in Trash should be relative to the Trash root directory.

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

fields

List of JSON properties to include in the response. Keys not specified in this list are omitted when generating a response. If the parameter isn't specified, the response is returned in full without omitting anything.

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

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.

offset

The number of resources in the folder that should be skipped in the response (for example, for paginated output). The list is sorted according to the sort parameter value.

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.

preview_crop

This parameter crops the preview to the size specified in the preview_size parameter.

Supported values:

  • false: the parameter is ignored (default value).
  • true: the preview is cropped as follows:

    • 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.
    • 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.
preview_size

The required size of the reduced image (file preview). Its link should be returned in the preview key.

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.

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.

sort

The attribute by which the list of resources should be sorted 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.

* Required parameter.

Response format

If the request is processed without errors, the API returns the 200 OK code and meta information about the requested resource within the Resource object in the response body.

If the request caused an error, the relevant response code is returned, and the response body contains an error description.

For non-empty folders, the response includes a ResourceList object (under the _embeddedname). 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.

Here's an example response for the published /foo folder that contains the /bar folder and the photo.png file:

{
  "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",
  "_embedded": {
    "sort": "",
    "path": "disk:/foo",
    "items": [
      {
        "path": "disk:/foo/bar",
        "type": "dir",
        "name": "bar",
        "modified": "2014-04-22T10:32:49+04:00",
        "created": "2014-04-22T10:32:49+04:00"
      },
      {
        "name": "photo.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/photo.png",
        "md5": "4334dc6379c8f95ddf11b9508cfea271",
        "type": "file",
        "mime_type": "image/png",
        "size": 34567
      }
    ],
    "limit": 20,
    "offset": 0
  },
  "name": "foo",
  "created": "2014-04-21T14:54:42+04:00",
  "custom_properties": {"foo":"1", "bar":"2"},
  "public_url": "https://yadi.sk/d/AaaBbb1122Ccc",
  "modified": "2014-04-22T10:32:49+04:00",
  "path": "disk:/foo",
  "type": "dir"
}

Here's an example response for the cat.png file that was deleted from the /foo folder:

{
  "preview": "https://downloader.disk.yandex.ru/preview/...",
  "name": "cat.png",
  "created": "2014-07-16T13:07:45+04:00",
  "custom_properties": {"foo":"1", "bar":"2"},
  "origin_path": "disk:/foo/cat.png",
  "modified": "2014-07-16T13:07:45+04:00",
  "path": "trash:/cat.png",
  "md5": "02bab05c02537e53dedd408261e0aadf",
  "type": "file",
  "mime_type": "image/png",
  "size": 903337
},

The fields parameter specifies which keys to include in the response (the other keys are not returned in this case). For example, the response for "name,_embedded.items.path" might look like this:

{
  "_embedded":
  {
    "items": [
    {
      "path":"disk:/foo/bar-2"
    },
    {
      "path":"disk:/foo/bar-3"
    }]
  },
  "name":"foo"
}

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 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 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 format.

modified

The date and time when the resource was modified, in 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.

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 is requested.

items

Array of resources (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, the attribute value is always "/".

total

The total number of resources in the folder.
Previous
Data about the user's Yandex Disk
Next
Flat list of all files
In this article: