REST API for Content Management 1.1

Get Folder

get

/documents/api/1.1/folders/{folderId}

Get folder information for the specified folder.

Request

Supported Media Types

application/json
application/xml

Path Parameters

folderId: Type: string

Required: true

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

Header Parameters

accessToken: Type: string

Applink access token authorizing the current user to access this folder. This parameter is mandatory if appLinkID is used. It can be used as accessToken or AccessToken.
appLinkID: Type: string

Applink ID authorizing the current user to access this folder. Any time the parameter appLinkID is used, a parameter accessToken must be provided as well. It can be used as appLinkID or AppLinkID.
dAccessCode: Type: string

Access code needed to use protected public links. It needs to be sent as part of a Cookie header in the following format: dAccessCode-<linkID>=<passcodeValue>
linkID: Type: string

Public link ID of a public link authorizing the current user to access this folder. It can be used as linkID or LinkID.

Response

Supported Media Types

application/json
application/xml

200 Response

The response body contains information about the specific folder.

Body

The response body includes information about the folder.

Root Schema : FolderResponseWithConversation

Type: object

The response body includes information about the folder.

Properties

errorCode: Type: string

An error code of zero (0) indicates no errors.

Match All

Type: object FolderDefinitionWithConversation

Additional Properties Allowed:

Folder metadata information.

Nested Schema : FolderDefinitionWithConversation

Folder metadata information.

Properties

childitemsCount: Type: string

Number of items contained in the folder.
conversationID: Type: string

Conversation ID associated with this folder or a parent folder.
createdBy: Type: object User

Additional Properties Allowed:

User information
createdTime: Type: string

Date the folder was created.
description: Type: string

Folder description.
id: Type: string

Globally unique identifier (GUID) for the folder.
isConversationInherited: Type: boolean

Flag indicating whether the conversation ID is associated with the current folder (false) or if the conversation ID is associated with a parent folder (true).
modifiedBy: Type: object User

Additional Properties Allowed:

User information
modifiedTime: Type: string

Date the folder was last modified.
name: Type: string

Folder name.
ownedBy: Type: object User

Additional Properties Allowed:

User information
parentID: Type: 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: Type: string

Size of the folder in bytes, including all of the files and folders contained in the folder.
type: Type: string

Item type folder.

Nested Schema : User

User information

Properties

displayName: Type: string

The display name for the user.
id: Type: string

Globally unique identifier (GUID) for the user.
type: Type: string

Item type user.

403 Response

Forbidden if the user does not have read permission.

404 Response

Folder ID is not found.

Examples

The following example returns folder-definition information for the specified folder.

GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "childItemsCount": "2",
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "createdTime": "2014-02-21T20:52:37Z",
    "errorCode": "0",
    "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "modifiedTime": "2014-02-21T20:52:37Z",
    "name": "foldera",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "parentID": "self",
    "size": "39",
    "type": "folder"
}

Example 2

The following example returns folder-definition information for the specified folder. This folder has a conversation associated with it, so two new fields, conversationID and isConversationInherited, are returned as well.

GET .../folders/F3EA22EE4F524F2931AAA841T0000000000100000001

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "childItemsCount": "1",
    "conversationID": "39912",
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "createdTime": "2016-05-13T20:40:24Z",
    "errorCode": "0",
    "id": "F3EA22EE4F524F2931AAA841T0000000000100000001",
    "isConversationInherited": "false",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "modifiedTime": "2016-05-13T20:40:24Z",
    "name": "folderB",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "parentID": "self",
    "size": "0",
    "type": "folder"
}

Example 3

The following example returns folder-definition information for the specified folder. The example uses a public link ID because this folder is under a folder structure not owned by or shared with the current user.

GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001

Request Header

LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "childItemsCount": "4",
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "createdTime": "2016-06-06T21:34:23Z",
    "description": "PublicLinkDemo",
    "errorCode": "0",
    "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2016-06-06T21:34:23Z",
    "name": "PublicLinkDemo",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "size": "1189",
    "type": "folder"
}

Example 4

The following example returns folder-definition information for the specified folder. The example uses a public link ID protected by an access code because this folder is under a folder structure not owned by or shared with the current user. An access code (test12345) is submitted as part of a Cookie in the request header.

GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001

Request Header

LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Cookie: dAccessCode-LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518=test12345

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "childItemsCount": "4",
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "createdTime": "2016-06-06T21:34:23Z",
    "description": "PublicLinkDemo",
    "errorCode": "0",
    "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2016-06-06T21:34:23Z",
    "name": "PublicLinkDemo",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "size": "1189",
    "type": "folder"
}

Example 5

The following example requests folder-definition information for the specified folder. Because this folder is under a folder structure not owned by or shared with the current user, an access denied error message is returned.

GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-20",
    "errorKey": "!csCloudItemInsufficientPrivileges,User BB,fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001,FLD_INFO",
    "errorMessage": "User 'User BB' has insufficient privilege to access fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001 with service FLD_INFO.",
    "errorType": "folder",
    "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001",
    "title": "User 'User BB' has insufficient privilege to access fFolderGUID:FF4729683CD68C1AFB1AE87DT0000000000100000001 with service FLD_INFO.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 6

The following example requests folder-definition information for the specified folder. This folder is under a folder structure not owned by or shared with the current user, and only a public link protected by an access code is available. An error is returned because the access code was not submitted as part of the request.

GET .../folders/FF4729683CD68C1AFB1AE87DT0000000000100000001

Request Header

LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518

Request Body

None.

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-18",
    "errorKey": "!csAccessCodeRequiredForLinkAccess",
    "errorMessage": "The access code must be provided to access the link.",
    "errorType": "folder",
    "id": "FF4729683CD68C1AFB1AE87DT0000000000100000001",
    "title": "The access code must be provided to access the link.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 7

The following example returns folder-definition information for the specified folder. The example uses an applink because this folder is under a folder structure not owned by or shared with the current user. The applink ID and access token are submitted in the request header.

GET .../folders/FAA7449732E312E8174731B3B5D17B95F47087F4E518

Request Header

appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg==
accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "childItemsCount": "0",
    "createdBy": {
        "displayName": "User BB",
        "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "type": "user"
    },
    "createdTime": "2017-06-21T18:53:43Z",
    "description": "subFolderTestByUserB CONTRIBUTOR applink",
    "errorCode": "0",
    "id": "FAA7449732E312E8174731B3B5D17B95F47087F4E518",
    "modifiedBy": {
        "displayName": "User BB",
        "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2017-06-21T18:53:43Z",
    "name": "subFolderTestByUserB",
    "ownedBy": {
        "displayName": "User AA",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "loginName": "userAALoginName",
        "type": "user"
    },
    "parentID": "F9681146B0BAAB329B58D6CFB5D17B95F47087F4E518",
    "size": "0",
    "type": "folder"
}