JSON objects in responses

Each response from the Yandex.Disk API consists of objects with a specific structure. This section describes all the objects that can be found in responses.

Link

The object contains the URL for requesting resource metadata.

Sample object:

{
  "href": "https://cloud-api.yandex.net/v1/disk/resources?path=disk%3A%2Ffoo%2Fphoto.png",
  "method": "GET",
  "templated": false
}

Resource

Resource description or metainformation about a file or folder. Included in the response to the request for metainformation.

{  "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmoktUCIo8=",  "_embedded": { /* ResourceList  object*/ },  "name": "photo.png",  "created": "2014-04-21T14:57:13+04:00",  "custom_properties": {"foo": "1", "bar": "2"},  "public_url": "https://yadi.sk/d/AaaBbb1122Ccc",  "origin_path": "disk:/foo/photo.png",  "modified": "2014-04-21T14:57:14+04:00",  "path": "disk:/foo/photo.png",  "md5": "4334dc6379c8f95ddf11b8508cfea271",  "type": "file",  "mime_type": "application/x-www-form-urlencoded",  "size": 34567}
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.
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.

ResourceList

The list of resources in the folder. Contains Resource objects and list properties.

{  "sort": "",  "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmoktUCIo8=",  "items": [ /* array of Resource objects*/ ],  "path": "disk:/foo",  "limit": 20,  "offset": 0,  "total": 3}
Response elements
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.

Response elements
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.

FilesResourceList

Flat list of all files on Yandex.Disk in alphabetical order.

{  "items": [ /* array of Resource objects*/ ],  "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.

offset

How much to offset the beginning of the list from the first resource in the folder.

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.

offset

How much to offset the beginning of the list from the first resource in the folder.

LastUploadedResourceList

A list of files recently added to Yandex.Disk, sorted by upload date (from later to earlier).

{  "items": [ /* array of Resource objects */ ],  "limit": 20}
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.

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.

PublicResourcesList

List of files published on Yandex.Disk.

{  "items": [ /* array of Resource objects */ ],  "type": "dir",  "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.

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.

Disk

Data about free and used space on Yandex.Disk

Sample response with this data:

{  "trash_size": 4631577437,  "total_space": 319975063552,  "used_space": 26157681270,  "system_folders":  {    "applications": "disk:/Applications",    "downloads": "disk:/Downloads/"  }}
Response elements
Element Description
trash_size

The cumulative size of the files in the Trash, in bytes.

total_space

The total space available to the user on Yandex.Disk, in bytes.

used_space

The cumulative size of the files already stored on Yandex.Disk, in bytes.

system_folders

Absolute addresses of Yandex.Disk system folders. Folder names depend on the user interface language that was in use when the user's personal Disk was created. For example, the Downloads folder is created for an English-speaking user, Загрузки for a Russian-speaking user, and so on.

The following folders are currently supported:

  • applications — folder for application files
  • downloads — folder for files downloaded from the internet (not from the user's device)
Response elements
Element Description
trash_size

The cumulative size of the files in the Trash, in bytes.

total_space

The total space available to the user on Yandex.Disk, in bytes.

used_space

The cumulative size of the files already stored on Yandex.Disk, in bytes.

system_folders

Absolute addresses of Yandex.Disk system folders. Folder names depend on the user interface language that was in use when the user's personal Disk was created. For example, the Downloads folder is created for an English-speaking user, Загрузки for a Russian-speaking user, and so on.

The following folders are currently supported:

  • applications — folder for application files
  • downloads — folder for files downloaded from the internet (not from the user's device)

Operation

The status of the operation. Operations are launched when you copy, move, or delete non-empty folders. The URL for requesting status is returned in response to these types of requests.

Example response with the operation status:

{  "status":"success"}
Response elements
Element Description
status

The status of the operation. Possible values:

  • success — Operation completed successfully.
  • failure — Operation failed; try repeating the initial request to copy, move or delete.
  • in-progress — Operation started but not yet completed.
Response elements
Element Description
status

The status of the operation. Possible values:

  • success — Operation completed successfully.
  • failure — Operation failed; try repeating the initial request to copy, move or delete.
  • in-progress — Operation started but not yet completed.

Error processing request

An error can occur if the request was formed incorrectly, the specified resource doesn't exist on the server, the server is not working, and so on. All errors are returned with HTTP response codes. All the possible response codes and explanations are given in Polygon (to see them, expand the desired request and click Show next to the Response messages heading).

Errors are additionally described by a JSON object, for example:

{  "description": "resource already exists",  "error": "PlatformResourceAlreadyExists"}
Response elements
Element Description
description

Detailed error description to help the developer.

error

Error ID for programmatic processing.

Response elements
Element Description
description

Detailed error description to help the developer.

error

Error ID for programmatic processing.