Metainformation about a file or folder
To request metainformation about files and folders, specify the path to the corresponding resource on Yandex.Disk. Metainformation includes the properties of files and folders, and the properties and contents of subfolders.
For metainformation about a public resource that does not belong to the user, there is a separate request.
Request format
Use the GET method to send a request for metainformation. The request URL is slightly different for requesting resources located in the 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=<whether to crop the preview>]
& [preview_size=<preview size>]
& [sort=<sorting attribute>]
path * | The path to the desired resource is relative to the Yandex.Disk root directory. The path to a resource in the Trash should be relative to the Trash root directory. The path in the parameter value should be URL-encoded. |
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: |
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 (use for paginated output). The list is sorted according to the Let's say the /foo folder contains three files. For a folder metainformation request with the |
preview_crop | This parameter crops the preview to the size specified in the Acceptable values:
|
preview_size | The desired size of the thumbnail (preview) file. The thumbnail link is returned in the 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
Possible values |
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:
To sort in reverse order, add a hyphen to the parameter value, for example: |
path * | The path to the desired resource is relative to the Yandex.Disk root directory. The path to a resource in the Trash should be relative to the Trash root directory. The path in the parameter value should be URL-encoded. |
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: |
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 (use for paginated output). The list is sorted according to the Let's say the /foo folder contains three files. For a folder metainformation request with the |
preview_crop | This parameter crops the preview to the size specified in the Acceptable values:
|
preview_size | The desired size of the thumbnail (preview) file. The thumbnail link is returned in the 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
Possible values |
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:
To sort in reverse order, add a hyphen to the parameter value, for example: |
* Required
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=<whether to crop the preview>]
& [preview_size=<preview size>]
& [sort=<sorting attribute>]
path * | The path to the desired resource is relative to the Yandex.Disk root directory. The path to a resource in the Trash should be relative to the Trash root directory. The path in the parameter value should be URL-encoded. |
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: |
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 (use for paginated output). The list is sorted according to the Let's say the /foo folder contains three files. For a folder metainformation request with the |
preview_crop | This parameter crops the preview to the size specified in the Acceptable values:
|
preview_size | The desired size of the thumbnail (preview) file. The thumbnail link is returned in the 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
Possible values |
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:
To sort in reverse order, add a hyphen to the parameter value, for example: |
path * | The path to the desired resource is relative to the Yandex.Disk root directory. The path to a resource in the Trash should be relative to the Trash root directory. The path in the parameter value should be URL-encoded. |
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: |
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 (use for paginated output). The list is sorted according to the Let's say the /foo folder contains three files. For a folder metainformation request with the |
preview_crop | This parameter crops the preview to the size specified in the Acceptable values:
|
preview_size | The desired size of the thumbnail (preview) file. The thumbnail link is returned in the 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
Possible values |
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:
To sort in reverse order, add a hyphen to the parameter value, for example: |
* 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.
An example response is shown for the published folder /foo, which contains the folder /bar and the file photo.png:
{ "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"}
An example response is shown for the file cat.png, which 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, for "name,_embedded.items.path" the response 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 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, |
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:
|
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 |
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 For a public folder, the value of the attribute is always "/". |
total | The total number of resources 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, |
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:
|
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 |
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 For a public folder, the value of the attribute is always "/". |
total | The total number of resources in the folder. |