Adding metainformation for a resource

You can set additional custom attributes for any writable file or folder. These attributes will be returned in response to all requests for resource metainformation (list of all files, last uploaded, and so on).

Request format

Use the PATCH method to send a request to add metainformation.

https://cloud-api.yandex.net/v1/disk/resources/
 ? path=<resource path>
 & [fields=<properties to include in the response>]
Query parameters
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: name, _embedded. items. path.

*  Required

Request body

The added attributes should be passed in the request body, in the custom_properties object (you can pass any parts of the Resource object, but everything except for custom_properties will be ignored). Attributes can only be name:value properties, so you can't use arrays or parent objects.

Restriction. The limit on the length of the custom_properties object (the names and values of embedded keys, along with syntactic symbols) is 1024 characters.

Attributes passed are added to the existing ones. For example, let's take the following object with the attributes foo and bar:

"custom_properties": {"foo":"1", "bar":"2"}

If the custom_properties object did not exist in the resource metainformation before this, the API simply adds the passed object to it.

If this object already exists (for example, "custom_properties": {"oof":"3", "bar":"0"}), the Yandex.Disk API updates the keys with the same names and adds the new ones. In the resource metainformation, you can see the object:

"custom_properties": {"oof": "3", "bar":"0", "foo":"1"}

To delete an attribute, pass it with the null value, for example:

"custom_properties": {"foo": null}

Response format

If the request was processed without errors, the Yandex.Disk API responds with the 200 OK code and returns metainformation about the requested resource in the Resource object in the response body. 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.

{  "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/2AEJCiNTZGiYX",  "modified": "2014-04-22T10:32:49+04:00",  "path": "disk:/foo",  "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.