Jump to

• Request
• Response
• Examples

Get Home Folder Contents

get

/documents/api/1.2/folders/items

Get a collection of all items (folders and files) that the user has access to, including folders that others have shared with that user. The type field indicates whether an item is a folder or a file.

Request

Supported Media Types

• application/json
• application/xml

Query Parameters

• limit(optional): string

  Specify the maximum number of items to return. Use this parameter to specify how many items to include on a single page of results. The default is 50 and maximum is 10000. The following example limits the number of returned items to 10:

  limit=10

• offset(optional): string

  Specify the point at which to begin the list of items from the complete set of items returned for the action. If you do not specify an offset, the returned items begin with the first item in the item list (offset=0).

  Use this parameter to specify the starting point for a given page of results from the complete set of returned items. The following example limits the number of items per page to 10 and displays the second page of results (items 11-20):

  limit=10&offset=10

• orderby(optional): string

  Order the resulting items using the specified field and sort order. You can use the name, createdTime, and modifiedTime fields, and a sort order of ascending (asc) or descending (desc). For example, this is the default:

  orderby=name:asc

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

Body ()

Root Schema : HomeFolderContents

Type: object

Show Source

• count(optional): string
  The number of items listed on the page.
• errorCode(optional): string
  An error code of zero (0) indicates no errors.
• hasMore(optional): string
  The number of users found.
• items(optional): array items
  The files and subfolders in the folder.
• ownerFolderID(optional): string

  Globally unique identifier (GUID) for the folder. If the referenced folder is the user's home folder, the value is self.

• totalResults(optional): string
  Total number of items in the response.

{
    "description":"",
    "properties":{
        "count":{
            "type":"string",
            "description":"The number of items listed on the page."
        },
        "totalResults":{
            "type":"string",
            "description":"Total number of items in the response."
        },
        "ownerFolderID":{
            "type":"string",
            "description":"<p>Globally unique identifier (GUID) for the folder. If the referenced folder is the user&#39;s home folder, the value is <code>self</code>.</p>"
        },
        "hasMore":{
            "type":"string",
            "description":"The number of users found."
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        },
        "items":{
            "type":"array",
            "description":"The files and subfolders in the folder.",
            "items":{
                "$ref":"#/definitions/FileAndSubFoldersItemsDefinition"
            }
        }
    }
}

Nested Schema : items

Type: array

The files and subfolders in the folder.

Show Source

• Array of: object FileAndSubFoldersItemsDefinition
  The files and subfolders in the folder.

{
    "type":"array",
    "description":"The files and subfolders in the folder.",
    "items":{
        "$ref":"#/definitions/FileAndSubFoldersItemsDefinition"
    }
}

Nested Schema : FileAndSubFoldersItemsDefinition

Type: object

The files and subfolders in the folder.

Show Source

• childItemsCount(optional): string
  Number of items contained in the folder.
• createdBy(optional): object User
  User information
• createdTime(optional): string
  Folder or file creation date.
• id(optional): string
  Globally unique identifier (GUID) for the folder or file.
• modifiedBy(optional): object User
  User information
• modifiedTime(optional): string
  Folder or file last modified date.
• name(optional): string
  Folder or file name.
• ownedBy(optional): object User
  User information
• parentID(optional): string

  Globally unique identifier (GUID) for the parent folder. If the parent folder is the user's home folder, the value for parentID is self.

• size(optional): string

  If the item is a file, the size of the file in bytes. If the item is a folder, then the size of the folder including all of the files and sub folders contained in the folder.

• type(optional): string
  Item type, either folder or file.
• version(optional): string
  If the item is a file, the number of versions of the file.

{
    "description":"The files and subfolders in the folder.",
    "properties":{
        "type":{
            "type":"string",
            "description":"Item type, either <code>folder</code> or <code>file</code>."
        },
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the folder or file."
        },
        "parentID":{
            "type":"string",
            "description":"<p>Globally unique identifier (GUID) for the parent folder. If the parent  folder is the user&#39;s home folder, the value for <code>parentID</code> is <code>self</code>.</p>"
        },
        "name":{
            "type":"string",
            "description":"Folder or file name."
        },
        "ownedBy":{
            "$ref":"#/definitions/User"
        },
        "createdBy":{
            "$ref":"#/definitions/User"
        },
        "modifiedBy":{
            "$ref":"#/definitions/User"
        },
        "createdTime":{
            "type":"string",
            "description":"Folder or file creation date."
        },
        "modifiedTime":{
            "type":"string",
            "description":"Folder or file last modified date."
        },
        "size":{
            "type":"string",
            "description":"<p>If the item is a file, the size of the file in bytes. If the item is a folder, then the size of the folder including all of the files and sub folders contained in the folder.</p>"
        },
        "childItemsCount":{
            "type":"string",
            "description":"Number of items contained in the folder."
        },
        "version":{
            "type":"string",
            "description":"If the item is a file, the number of versions of the file."
        }
    }
}

Nested Schema : User

Type: object

User information

Show Source

• displayName(optional): string
  The display name for the user.
• id(optional): string
  Globally unique identifier (GUID) for the user.
• loginName(optional): string
  The login name for the user.
• type(optional): string
  Item type user.

{
    "description":"User information",
    "properties":{
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the user."
        },
        "displayName":{
            "type":"string",
            "description":"The display name for the user."
        },
        "loginName":{
            "type":"string",
            "description":"The login name for the user."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>user</code>."
        }
    }
}

Example Response (application/json)

{
    "count":"3",
    "totalResults":"3",
    "ownerFolderID":"self",
    "hasMore":"0",
    "errorCode":"0",
    "items":[
        {
            "id":"FF4729683CD68C1AFB1AE87DT0000000000100000001",
            "parentID":"self",
            "name":"foldera",
            "type":"folder",
            "size":"39",
            "childItemsCount":"2",
            "createdTime":"2014-02-21T20:52:37Z",
            "modifiedTime":"2014-02-21T20:52:37Z",
            "createdBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            },
            "ownedBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            },
            "modifiedBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            }
        },
        {
            "id":"F4A669A2B7B69F2376C640A9T0000000000100000001",
            "parentID":"self",
            "name":"folderb",
            "type":"folder",
            "size":"0",
            "childItemsCount":"0",
            "createdTime":"2014-02-21T21:38:44Z",
            "modifiedTime":"2014-02-21T21:38:44Z",
            "createdBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            },
            "ownedBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            },
            "modifiedBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            }
        },
        {
            "id":"DBFDB0B6543FB5B68107423AT0000000000100000001",
            "parentID":"self",
            "name":"test cases.txt",
            "type":"file",
            "size":"37786",
            "version":"1",
            "createdTime":"2014-02-21T21:38:52Z",
            "modifiedTime":"2014-02-21T21:38:52Z",
            "createdBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            },
            "ownedBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            },
            "modifiedBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            }
        }
    ]
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have read permission.

404 Response

Folder ID is not found.

Back to Top

Examples

The following example returns the list of child items in the specified folder.

GET .../folders/items?orderby=name:asc&limit=10&offset=10

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "3",
    "errorCode": "0",
    "hasMore": "0",
    "ownerFolderID": "self",
    "totalResults": "3",
    "items": [
        {
            "type": "folder",
            "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001",
            "parentID": "self",
            "name": "foldera",
            "ownedBy": {
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "createdBy": {
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "createdTime": "2014-02-21T20:52:37Z",
            "modifiedTime": "2014-02-21T20:52:37Z",
            "size": "39",
            "childItemsCount": "2"
        },
        {
            "type": "folder",
            "id": "F4A669A2B7B69F2376C640A9T0000000000100000001",
            "parentID": "self",
            "name": "folderb",
            "ownedBy": "{
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
 
            "createdBy": {
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": {
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "createdTime": "2014-02-21T21:38:44Z",
            "modifiedTime": "2014-02-21T21:38:44Z",
            "description": "folder b",
            "size": "0",
            "childItemsCount": "0"
        },
        {
            "type": "file",
            "id": "DBFDB0B6543FB5B68107423AT0000000000100000001",
            "parentID": "self",
            "name": "test cases.txt",
            "ownedBy": "{
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
 
            "createdBy": {
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
            "modifiedBy": "{
                "displayName": "User AA",
                "loginName": "userAALoginName",
                "id": "U0EAA20910FAF3052ACB79E4T00000000001",
                "type": "user"
            },
 
            "createdTime": "2014-02-21T21:38:52Z",
            "modifiedTime": "2014-02-21T21:38:52Z",
            "size": "37786",
            "version": "1"
        }
    ]
}

Back to Top