API Version 1.0.0.14

This document attempts to capture the API details necessary to write applications that leverage the Cloud Engines connect service to gain access to devices and services exposed by the user from their home. This is a growing and changing document that will be added to over time, so if things are unclear, please don't hesitate to send comments, questions, or requests to info@pogoplug.com.

API protocol support

All API methods support HTTP (and HTTPS) protocol transport mechanisms. The API has been designed to transparently support both REST style and SOAP style HTTP calling conventions. All responses to API call requests are either raw data responses or structured responses depending on the API call in question. Structured responses are provided in either SOAP, Simple XML, or JSON format depending on the arguments used to invoke the API call.

API method calls are all supported through a base URL which should be easily changable in your application's configuration. The current base URL that can be used for testing is:

Invoking methods are performed with URLs constructed by the following pattern:

Where format is optional response format (e.g. soap, xml, json) and methodName is the name of the method to be invoked. As such, invoking the method getVersion would be performed on any of the following URLs:

The argument calling convention is implied by the HTTP request type. An HTTP GET request to the URL will imply a REST style call with arguments passed on the query string in standard browser form query string encoding. Thus, for example, invoking loginUser can be performed with a REST style call by performing ant HTTP GET on the following URL:

Similarly, an HTTP POST request to the URL will imply a SOAP style call with arguments encoded inside a SOAP XML envelope passed as the request body of the HTTP request. Thus, for example, invoking loginUser can be performed with a SOAP style call by performing ant HTTP POST as follows:

The response format is implied based on the calling convention or specified specifically in the URL. The implied response for REST style requests is JSON, and the implied response for SOAP style requests is SOAP. An example of a JSON response to the loginUser method above is:

The same response as a SOAP/xml formated response would be:

Exceptions can be returned from any API call rather than the structured response that was expected. Exceptions will always be of the same form and encode some level of useful information for converting to a user presentation error message. If in JSON context, exceptions will be of the following form:

If in SOAP context, exceptions will be of the following form:

Currently the only difference between the SOAP and the xml context is that in the SOAP context, exceptions will be returned with HTTP 500 level response codes in the HTTP header where as XML context will return all exceptions with HTTP 200 level response codes. Some client HTTP client libraries do not allow access to the response body unless a successful HTTP response occurs, and thus the XML context is a way to indcate this behaviour.

Structured API

The structured API provides an object oriented API to the follow object classes within the system:

Object Class	Description
User	Represents concrete users of the system. Users are owners of accounts and the primary method of relationship management. Users have multiple email addresses associated which can allow for identity managmeent by email address but allowing the same user to manage multiple keyed identity as many users already do (e.g. work email and home email) with different relationships having some subset of the total email set.
Device	Represents a physical device that can be identified by a user. Physical devices may or may not provide any files or services.
Service	Represents an addressable software endpoint providing some data representation which can be further quried. The type of the service defines how the data represented by this service can be further queried. Most devices provide at least a "foldershare" type service as this allows for a heirarchical namespace view of files and folders contained by this service.
File	For "foldershare" type services, files represent the folder or directory and file nodes within the service namespace. They allow for iteration and structural changes of this namespace.
Share	Share's represent folders that have been shared from a particular "foldershare" service. They have their own unique identifiers, and remember the device and service they are shared from.

Summary of Structured API methods

Quick summary of all supported Structured API methods.

Global Features
API Method	First Version	User Auth	App Auth
getVersion	0.9.0	no	no
User Features
API Method	First Version	User Auth	App Auth
loginUser	0.9.0	no	no
getUser	0.9.0	yes	no
Device Features
API Method	First Version	User Auth	App Auth
listDevices	0.9.0	yes	no
Service Features
API Method	First Version	User Auth	App Auth
listServices	0.9.0	yes	no
File Features
API Method	First Version	User Auth	App Auth
listFiles	0.9.0	yes	no
searchFiles	1.0.0.15	yes	no
getFile	0.9.0	yes	no
createFile	0.9.0	yes	yes
removeFile	0.9.0	yes	yes
copyFile	1.0.0.14	yes	yes
transferProgress	1.0.0.14	yes	yes
Sharing Features
API Method	First Version	User Auth	App Auth
listShares	1.0.0.14	yes	no
createShare	1.0.0.14	yes	no
deleteShare	1.0.0.14	yes	no
listSharedUsers	1.0.0.14	yes	no
addSharedUser	1.0.0.14	yes	no
removeSharedUser	1.0.0.14	yes	no

Summary of Structured API Exceptions

Quick summary of all API exception codes.

Code	Name	Description
400	CLIENT_ERROR	Unspecified client error
500	SERVER_ERROR	Unspecified server error
600	INVALID_ARGUMENT	Invalid argument format or missing required argument
601	OUT_OF_RANGE	Index into list out of range (e.g. page offset)
602	NOT_IMPLEMENTED	The request cannot be fullfilled because it is not implemented
606	NOT_AUTHORIZED	The valtoken is not valid or has expired
800	NO_SUCH_USER	User does not exist
801	NO_SUCH_DEVICE	The referenced device does not exist
802	NO_SUCH_SERVICE	The referenced service does not exist
803	NO_SUCH_SPACE	The referenced space does not exist
804	NO_SUCH_FILE	The referenced file does not exist
805	INSUFFICIENT_PERMISSIONS	The user represented by that valtoken does not have permission to do this
806	NOT_AVAILABLE	Generic unavailable error response

Data Stream API

The structured API is primarily designed to give access to the metadata and operations that can be performed on the objects in the system, but the raw data is designed to be access via standard HTTP verbs including HEAD GET and PUT on deterministic URLs. Once fileid for a file is retrieved from the structured API (e.g. by listFiles), then the file itself can be accessed via a local URL reference from the service url (see listServices) of the form:

valtoken, deviceid, serviceid, fileid uniquely identify the file to perform the opeartion on.flags is one of: "dl", "stream", or "rss". The "dl" flag indicates that the file is to be downloaded, the Content-Disposion header is set to "attachment; filename=<filename for fileid>" and the Content-Type header is set to "application/octet-stream". If flags is set to "rss" and the fileid is a directory, the contents of the directory are returned as a Media RSS feed. If flags are unset or are set to "strm" The file content is returned with the actual mime type of the file, suitable for handling by a browser or other user agent. arbitraryname.ext bit has different meanings based on the HTTP verb used as follows:

HTTP Verb	arbitraryname	Description
HEAD	ignored	Provides HTTP header details the same as GET without the request body.
GET	ignored	Provides full streamed access to the file identified by fileid including support for the following standard HTTP/1.1 headers: If-Modified-Since Range The arbitraryname.ext is purposefully ignored to support broken user-agents that don't always correctly handle Content-Type header in the response and incorrectly assume behaviour based on the filename and extension at the end of the URL. If using one of these user agents, for example, a JPEG file could be appended with /foo.jpg to force these user agents to do something more expected without changing the behaviour of the server.
PUT	ignored (if fileid references file type)	Replaces the contents of the file at the specified fileid (or block if Range). Provides full streamed access to the file identified by fileid including support for the following standard HTTP/1.1 headers: Range
PUT	new file name (if fileid references directory type)	Creates a new file with the specified name within the parent specified by fileid. Provides full streamed access to the file identified by fileid including support for the following standard HTTP/1.1 headers: Range

Structured API Method Details

getVersion

Input Arguments
Name	Req?	Type	Description
---none---

Output Arguments
Name	Child	Type	Description
version		string	Current version string of service

loginUser

Input Arguments
Name	Req?	Type	Description
email	y	string (email)	Email address of user to authenticate
password	y	string	Password of user to authenticate

Output Arguments
Name	Child	Type	Description
valtoken		string	Opaque validation token string for user
user		struct user	User object representing all the details about this user
user.userid	+	string	Unique ID (opaque string) representing this user
user.screenname	+	string	Screen name of this user
user.email	+	list	Primary email address of this user
user.emails	+	string (email)	List of registered email addresses of this user
user.emails.address	+	string (email)	List of registered addresses of this user
user.emails.validated	+	string	'0' if address not validated, '1' if it is. Users will not be able to log in with an email address until it is validated.

getUser

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user

Output Arguments
Name	Child	Type	Description
user		struct user	User object representing all the details about this user
user.userid	+	string	Unique ID (opaque string) representing this user
user.screenname	+	string	Screen name of this user
user.email	+	string (email)	Primary email address of this user
user.emails	+	string (email)	List of registered email addresses of this user
user.emails.address	+	string (email)	List of registered addresses of this user
user.emails.validated	+	string	'0' if address not validated, '1' if it is. Users will not be able to log in with an email address until it is validated.

listDevices

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user

Output Arguments
Name	Child	Type	Description
devices		struct device[]	A sequence of device objects
device	+	struct device	device object
device.deviceid	++	string	Unique ID (opaque string) representing this device
device.name	++	string	User's name for this device
device.version	++	string	Version string of this device
device.flags	++	string	Flags about this device (TODO: Define these)
device.ownerid	++	string	Unique ID of the user that owns this device
device.owner	++	struct user	User compound object representing the owner of this device (see getUser for details)
device.services	++	list of services	List of Services representing the services on this device (see for details)

listServices

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
deviceid		string	Optional device id to list devices for. If ommitted, all services that the user has access to (either shared or not based on shared argument) are returned. If included, only the services exposed by the specified device are returned.
shared		boolean	Optional boolean argument indicating whether the list of services are the services on the devices owned by the user (false or omitted) or the list of services shared with this user by others (true)

Output Arguments
Name	Child	Type	Description
services		struct service[]	A sequence of service objects
service	+	struct service	service object
service.deviceid	++	string	Unique ID of the device that owns this service
service.serviceid	++	string	id of this service (only unique within device)
service.sclass	++	integer	Class of this service (TODO: Define these)
service.type	++	string (stype)	Type of access to this service
service.name	++	string	User's name for this service
service.version	++	string	Version string of this service
service.apiurl	++	string (url)	URL to use when communicating to this service specifically. If this argument is ommitted or empty, then continue to use the same base URL, otherwise switch to using the returned base URL.
service.online	++	integer	An integer indicating the on-line status of this service. A value of 1 indicates that this service has checked in recently and is likely (but not guaranteed) still on-line right now.
service.device	++	struct device	Device compound object representing the device this service is exposed from (see listDevices for details) the device object is omitted if the service is listed as an element of listDevices, and vice versa.

listFiles

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
deviceid	y	string	The device ID we are talking to.
serviceid	y	string	The service ID on the device we are talking to.
spaceid		string	View or SPACE id identifying the namespace. We support multiple different namespaces within the same file heirarchy for future applications. The default namespace is DEFAULT and omitting this argument means that.
parentid		string	ID of the parent object to list files within. Omitting this argument means the root directory of the namespace, otherwise this indicates the fileid of the folder to list contents of.
pageoffset		unsigned integer	If results are returned in a paginated fashion, this indicates the 0 based index of the page of results to return. Each page will contain up to maxcount items.
maxcount		unsigned integer	If results are returned in a paginated fashion, this indicates the maximum number of items to return per request. Fewer than this number may be returned if the server deems to do so, but this does not indicate a true end-of-list condition has been met (the server may return fewer just because of it's own resource management).
searchcrit		boolean	By default hidden files are omitted from the file list. To include them, this parameter must be true.
sortcrit		string	sort criteria for the file list. valid values are: +name, -name, +date, -date, +type, -type, +size, -size.

Output Arguments
Name	Child	Type	Description
pageoffset		unsigned integer	This is the 0 based index of this page of files within the full result set. Each page will contain up to count items.
count		unsigned integer	This is the number of files in this page of results.
files		struct file[]	A sequence of file objects beginning at page offset pageoffset * count and of length count.
file	+	struct file	A file object.
file.fileid	++	string	Unique ID (opaque string) representing this file
file.spaceid	++	string	Primary namespace ID of this file
file.parentid	++	string	fileid of parent object of this file
file.ownerid	++	string	userid of user that owns this file
file.type	++	enum file_type	Defined values: 0 -- Normal File 1 -- Directory 2 -- Extra Stream 3 -- Symbolic Link
file.name	++	string	Name of this file object
file.mimetype	++	string	Mime type of primary stream attached to this file (if known)
file.size	++	unsigned 64bit	Length in bytes of primary stream attached to this file
file.ctime	++	unsigned 64bit	Creation date of file object (as milliseconds since epoch)
file.mtime	++	unsigned 64bit	Modification date of file object (as milliseconds since epoch)
file.thumbnail	++	string	fileid of the "extra stream" that represents the thumbnail of this object
file.preview	++	string	fileid of the "extra stream" that represents the preview of this object

searchFiles

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
pageoffset	n	string	Which 'page' of results to return (for paginated viewing of results). Defaults to '0'
maxcount	n	string	The maximum number of items to return for each 'page'. Defaults to '32'
searchcrit	y	string	The criteria for the search. Currently available fields for searching include 'name', 'ctime', and 'mediatype'. Currently the name field only supports the 'contains' operator, in the form 'name contains "string"'. ctime supports >=, <=, and = operators and is milliseconds since 1970. mediatype only supports the = operator, and is one of "audio", "video", or "image"
sortcrit	n	string	Criteria for the sort. May be one of: '+name', '-name', '+date', '-date', '+type', '-type'. Currently search results cannot be sorted by file size.

Output Arguments
Name	Child	Type	Description
pageoffset		unsigned integer	This is the 0 based index of this page of files within the full result set. Each page will contain up to count items.
count		unsigned integer	This is the number of files in this page of results.
files		struct file[]	A sequence of file objects beginning at page offset pageoffset * count and of length count.
file	+	struct file	A file object.
file.fileid	++	string	Unique ID (opaque string) representing this file
file.spaceid	++	string	Primary namespace ID of this file
file.parentid	++	string	fileid of parent object of this file
file.ownerid	++	string	userid of user that owns this file
file.type	++	enum file_type	Defined values: 0 -- Normal File 1 -- Directory 2 -- Extra Stream 3 -- Symbolic Link
file.name	++	string	Name of this file object
file.mimetype	++	string	Mime type of primary stream attached to this file (if known)
file.size	++	unsigned 64bit	Length in bytes of primary stream attached to this file
file.ctime	++	unsigned 64bit	Creation date of file object (as milliseconds since epoch)
file.mtime	++	unsigned 64bit	Modification date of file object (as milliseconds since epoch)
file.thumbnail	++	string	fileid of the "extra stream" that represents the thumbnail of this object
file.preview	++	string	fileid of the "extra stream" that represents the preview of this object

getFile

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
deviceid	y	string	The device ID we are talking to.
serviceid	y	string	The service ID on the device we are talking to.
fileid	*	string	Fileid to lookup (exclusive only use this argument or path)
path	*	string	Path to lookup (exclusive only use this argument or fileid)

Output Arguments
Name	Child	Type	Description
file		struct file	A file object.
file.fileid	+	string	Unique ID (opaque string) representing this file
file.spaceid	+	string	Primary namespace ID of this file
file.parentid	+	string	fileid of parent object of this file
file.ownerid	+	string	userid of user that owns this file
file.type	+	enum file_type	Defined values: 0 -- Normal File 1 -- Directory 2 -- Extra Stream 3 -- Symbolic Link
file.name	+	string	Name of this file object
file.mimetype	+	string	Mime type of primary stream attached to this file (if known)
file.size	+	unsigned 64bit	Length in bytes of primary stream attached to this file
file.ctime	+	unsigned 64bit	Creation date of file object (as milliseconds since epoch)
file.mtime	+	unsigned 64bit	Modification date of file object (as milliseconds since epoch)
file.thumbnail	+	string	fileid of the "extra stream" that represents the thumbnail of this object
file.preview	+	string	fileid of the "extra stream" that represents the preview of this object

createFile

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
deviceid	y	string	The device ID we are talking to.
serviceid	y	string	The service ID on the device we are talking to.
spaceid		string	Name space ID to create file within (defaults to "DEFAULT" name space)
parentid		string	Fileid of parent directory to create file within (defaults to root)
filename	y	string	File name of new file to create
type		string	Integer file type of file to create: 0 -- Normal File 1 -- Directory 2 -- Extra Stream 3 -- Symbolic Link

Output Arguments
Name	Child	Type	Description
file		struct file	A file object.
file.fileid	+	string	Unique ID (opaque string) representing this file
file.spaceid	+	string	Primary namespace ID of this file
file.parentid	+	string	fileid of parent object of this file
file.ownerid	+	string	userid of user that owns this file
file.type	+	enum file_type	Defined values: 0 -- Normal File 1 -- Directory 2 -- Extra Stream 3 -- Symbolic Link
file.name	+	string	Name of this file object
file.mimetype	+	string	Mime type of primary stream attached to this file (if known)
file.size	+	unsigned 64bit	Length in bytes of primary stream attached to this file
file.ctime	+	unsigned 64bit	Creation date of file object (as milliseconds since epoch)
file.mtime	+	unsigned 64bit	Modification date of file object (as milliseconds since epoch)
file.thumbnail	+	string	fileid of the "extra stream" that represents the thumbnail of this object
file.preview	+	string	fileid of the "extra stream" that represents the preview of this object

removeFile

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
deviceid	y	string	The device ID we are talking to.
serviceid	y	string	The service ID on the device we are talking to.
spaceid		string	Name space ID to create file within (defaults to "DEFAULT" name space)
fileid	y	string	Fileid to remove

No Output Arguments

copyFile

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
deviceid	y	string	The device ID which the source file is on.
serviceid	y	string	The service ID where the source file is located.
fileid	y	string	the id of the file or folder that is to be copied
dstdeviceid	y	string	The destination device's id.
dstserviceid	y	string	The destination service's id.
dstfileid		string	The destination folder's id. The source fileid will be copied into this folder. If not specified, the file will be copied into the root of the destination service.

Output Arguments
Name	Child	Type	Description
progressid		string	handle which can be used to check progress with transferProgress call.

transferProgress

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
deviceid	y	string	The device ID that is being copied from.
serviceid	y	string	The service ID that is being copied from
progressid		string	The handle that was returned from copyFile.

Output Arguments
Name	Child	Type	Description
fileindex		unsigned integer	0 based index of the file that is being copied.
filecount		unsigned integer	the totaol number of files being copied.
name		string	the name of the file currently being copied.
offset		string	the number of bytes of the current file that have been copied so far.
length		string	the number of bytes total of the current file.
copiedsize		string	the total number of bytes that have been copied so far.
totalsize		string	the total number of bytes to be copied.
done		string	'1' if the copy operation is done. '0' if its still in progress. this is the only field you should consider when ascertaining whether or not the copy operation is still underway.

listShares

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
shared		boolean	true indicates that the shared list should be iterated, omitted or false indicates the owned list should be iterated.
offset		unsigned integer	If results are returned in a paginated fashion, this indicates the 0 based index of the first result to return. Each page will contain up to count items.
count		unsigned integer	If results are returned in a paginated fashion, this indicates the maximum number of items to return per request. Fewer than this number may be returned if the server deems to do so, but this does not indicate a true end-of-list condition has been met (the server may return fewer just because of it's own resource management).

Output Arguments
Name	Child	Type	Description
offset		unsigned integer	This is the 0 based index of the first shared folder within the full result set.
count		unsigned integer	This is the number of files in this page of results.
shares		struct share[]	A sequence of 'share' objects beginning at offset offset and of length count.
share	+	struct share	A 'share' object.
share.shareid	++	string	Unique ID (opaque string) representing this share.
share.ownerid	++	string	userid of user that owns this share
share.root	++	string	Compound object representing the folder being shared see listFiles for details
share.deviceid	++	string	Unique identifier for the device this share is stored on.
share.serviceid	++	string	Unique identifier for the service this share is shared from.

createShare

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user

Output Arguments
Name	Child	Type	Description
share	+	struct share	A 'share' object.
share.shareid	++	string	Unique ID (opaque string) representing this share.
share.ownerid	++	string	userid of user that owns this share
share.root	++	string	Compound object representing the folder being shared see listFiles for details
share.deviceid	++	string	Unique identifier for the device this share is stored on.
share.serviceid	++	string	Unique identifier for the service this share is shared from.

deleteShare

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
shareid	y	string	ID of the share to be deleted

No Output Arguments

listSharedUsers

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
shareid	y	string	Id of the share for this folder.

Output Arguments
Name	Child	Type	Description
users		list	List of users with whom this folder has been shared.
users.user	+	string	The user object. See getUser
users.perms	+	string	Permissions this user has to this folder. Currently '0' is read only access and '1' is write access.

addSharedUser

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
email	y	string	Email address of the user to be shared with. If there is no user for the email in the system, one will be created.

No Output Arguments

removeSharedUser

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
shareid	y	string	ID of folder share
userid	y	string	ID of user to be removed

No Output Arguments

removeSharedUser

Input Arguments
Name	Req?	Type	Description
valtoken	y	string	Opaque validation token string for user
shareid	y	string	ID of the folder share
userid	y	string	ID of the user whose permissions are being updated

No Output Arguments