API Features

This section covers several features of My Cloud Home APIs to help you increase your understanding and improve the performance of your application.

General Features

Some of the general features of My Cloud Home APIs are as follows:

Path and Version Formats

All My Cloud Home APIs are versioned, which means, all calls should include appropriate version information in the path.

Date Format

My Cloud Home uses ISO_8601 date format. All date formats returned by APIs have a combined date and time in UTC ("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").

Case Sensitivity

All items in My Cloud Home file system are case sensitive, which means file/folder named 'hello' and 'Hello' are considered different.


You can access various file metadata using API. Some commonly returned metadata items are Size, Mime Type, Extension, and Modified Time. Media metadata will also be returned if the selected file is a media file.


"size": 2644006,
"mimeType": "image/jpeg",
"mTime": "2015-06-01T23:31:31Z",
"cTime": "2017-02-06T19:21:33.296Z",
"extension": ".jpg",
"image": {
    "date": "2014:12:10 15:11:54",
    "width": 4128,
    "height": 2322,
    "cameraMake": "SAMSUNG",
    "cameraModel": "GT-I9500",
    "aperture": 2.2,
    "exposureTime": 0.03030303,
    "isoSpeed": 100,
    "focalLength": 4.2,
    "flashFired": false,
    "orientation": 1


My Cloud Home supports ETag revisions. ETag allows applications to determine whether the file got changed in My Cloud Home server. Client applications can use 'If-None-Match' header to pass ETag information to the server.



Optional Data

The APIs may add additional information to the JSON response data at any time to provide optional features or to enhance debugging. We suggest not validating JSON in its entirety but validating only the fields that are required.


Advanced Features

Optimized Network Selection

When a user tries to connect to the My Cloud Home Device from a client application, the connection must go all the way to user's home to reach the device. In this case, there are two scenarios:

Away network can be Port Forwarded or Proxy Relay.

Port Forwarded: When the device establishes a port forwarded connection, the client application can directly connect to the device to access content. The Port Forwarded route, if available gives enhanced performance when accessing content outside the home network. However, some network routers do not allow establishing a port forwarded connection. 

Proxy Relay: The relay route is always available, and the client application can access the device content through a proxy server.

  • Home network: When both the device and client application (for example, a mobile app) are in the same network, then the client application can use "internalDNSName" based on local IP address to reach the device.
  • Away network: When the user is away from home, the client application has to use away network URLs to reach the device.

You should use the network routes in the following order to get better performance.

  1. Home network ( "internalDNSName")
  2. Port forwarded ("portForwardURL")
  3. Proxy Relay ("proxyURL")

The My Cloud Home Device object returned will have all three routes (if accessible). You should use the complete URL in the network object. Here is an example of how the URLs will look like in My Cloud Home device object.

"network": {

  "internalDNSName": "",
  "proxyURL": "",
  "portForwardURL": ""}

Multi-User Management

Each user in the My Cloud Home device will have his/her private space that only they have access to on the device. Family and Friends can be invited using their email to set up their private space, or they can request space in My Cloud Home device if they are on the home network. Device owners use the mobile app or web app to create users or to invite others to use the My Cloud Home device. 


Check out the video for detailed information on adding users to the device.. 

If any user wants to share some content with the other user, he/she has to follow the same sharing mechanism as described in the video.

For more help on this or other topics, visit our learning center.

Error Codes

Response Code Message Description
400 Bad Request Indicates that the required parameter/s are not present.
Refer API documentation to make sure that the parameters are correctly passed in the request.
401 Unauthorized Indicates an invalid token.
All My Cloud Home endpoints expect 'Authorization: Bearer ' header. Missing token, invalid token or expired token can generate this error code.
403 Forbidden Not authorized to do the requested operation.
My Cloud Home understands the request, but the token associated with the request does not have the authority to do that. Refer to the documentation and make sure that your client is allowed to make this type of calls. If the issue persists, contact My Cloud Home team to resolve the app authorization issues.
404 Not Found Indicates that the requested resource was not found. For example, the requested User or the My Cloud Home Device.
Ensure that the requested item is valid.
405 Method Not Allowed Indicates that the request was recognized by the server, but the server has rejected that particular method for the requested resource.
Typically happens when wrong HTTP methods are being used. For example, using GET for a POST endpoint.
409 Resource Conflict Indicates a request conflict with the current state of the server.
Typically happens when creating a new resource. If the resource already exists, then My Cloud Home will return the 409 resource conflict.
500 Internal Server Indicates that the server is experiencing some issues. Please retry the request.

Do more with the
My Cloud Home Off-Device API

Click the buttons below to visit the My Cloud Home Off-Device Developer Home & Workflow pages



Get started, access the API, build your apps, & learn more

View Home


Register & submit your app for review and contact support

View Workflow