REST API for Content Management 1.1

Upload File Version

post

/documents/api/1.1/files/{fileId}/data

Upload a new revision to a file using a multipart request to specify information for the target file and input file.

Note:

Two files cannot have the same name in a given folder. File names are not case-sensitive; that is, File_Name and file_name are considered identical. If a file with the same name exists in the target destination, the name of the new file is given a numeric increment. For example, if the file my_file already exists, the new file is named my_file(2).

Request

Supported Media Types

multipart/form-data

Path Parameters

fileId: Type: string

Required: true

Globally unique identifier (GUID) for the file.

Header Parameters

accessToken: Type: string

Applink access token authorizing the current user to access the parent folder or this file. 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 the parent folder or this file. Any time the parameter appLinkID is used, a parameter accessToken must be provided as well. To work, this applink must have at least the contributor role granted. 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 file. To work, this public link must have the contributor role granted. It can be used as linkID or LinkID.

Form Parameters

metadataValues: Type: string

You can use this parameter to set metadata values to a collection already assigned to any parent folder. The rules are the same as those applied to the set metadata values REST API. Use Content-Type: application/json to describe this information as a JSON object.
For example:
{ "collection ": "CollectionA", "fieldA ": "valueA", "fieldB ": "valueB", "fieldC ": "valueC" }
primaryFile: Type: file

Required: true

File to upload.

Response

Supported Media Types

application/json
application/xml

200 Response

The request was fulfilled.

Headers

Location: Type: string

The URI for the newly created resource is in the Location Header field.

Body

The response body includes information about the file.

Root Schema : FileUploadResponse

Type: object

The response body includes information about the file.

Properties

errorCode: Type: number

An error code of zero (0) indicates no errors.
errorMessage: Type: string

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

Match All

Type: object FileDefinition

Additional Properties Allowed:

File information

Nested Schema : FileDefinition

File information

Properties

createdBy: Type: object User

Additional Properties Allowed:

User information
createdTime: Type: string

File creation date.
id: Type: string

Globally unique identifier (GUID) for the file.
mimeType: Type: string

File format of the file.
modifiedBy: Type: object User

Additional Properties Allowed:

User information
modifiedTime: Type: string

File last modified date.
name: Type: string

File 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.
reservationTime: Type: string

Time the file was reserved (excluded from response data if the file is not reserved).
reservedBy: Type: object User

Additional Properties Allowed:

User information
size: Type: string

Size of the file in bytes.
type: Type: string

Item type file.
version: Type: string

File version.

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.

Example application/json


{
    "id":"D574378400573ED9D62B3195T0000000000100000001",
    "parentID":"FB4CD874EF94CD2CC1B60B72T0000000000100000001",
    "name":"example2.txt",
    "type":"file",
    "size":"13",
    "version":"1",
    "createdTime":"2014-02-21T21:15:57Z",
    "modifiedTime":"2014-02-21T21:18:20Z",
    "createdBy":{
        "id":"U0EAA20910FAF3052ACB79E4T00000000001",
        "displayName":"User AA",
        "type":"user"
    },
    "ownedBy":{
        "id":"U0EAA20910FAF3052ACB79E4T00000000001",
        "displayName":"User AA",
        "type":"user"
    },
    "modifiedBy":{
        "id":"U0EAA20910FAF3052ACB79E4T00000000001",
        "displayName":"User AA",
        "type":"user"
    },
    "errorCode":"0",
    "errorMessage":"Successfully checked in content item 'ADC412030000000000000000000003'."
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have write permission.

404 Response

File ID is not found.

Examples

The following example uploads a new version of a file using a multipart request.

POST .../files/D574378400573ED9D62B3195T0000000000100000001/data/

Request Header

The request is a multipart request with a specified boundary delimiter of the following general form:

Content-Type: multipart/form-data; boundary=---1234567890

Request Body

-----1234567890
Content-Disposition: form-data; name="primaryFile"; filename="example2.txt"
Content-Type: text/plain
 
<File Content>
-----1234567890--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "createdTime": "2014-02-21T21:15:57Z",
    "errorCode": "0",
    "errorMessage": "Successfully checked in content item 'ADC412030000000000000000000003'.",
    "id": "D574378400573ED9D62B3195T0000000000100000001",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "modifiedTime": "2014-02-21T21:18:20Z",
    "name": "example2.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "parentID": "FB4CD874EF94CD2CC1B60B72T0000000000100000001",
    "size": "13",
    "type": "file",
    "version": "3"
}

Example 2

The following example uploads a new version of a file using a multipart request. The example uses a public link ID because this file is under a folder structure not owned by or shared with the current user.

POST .../files/D574378400573ED9D62B3195T0000000000100000001/data/

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
LinkID: LF1F4C0670E07337F2A6AA1CB5D17B95F47087F4E518

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="example2.txt"
Content-Type: text/plain

This is example2.txt v2

-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "createdTime": "2014-02-21T21:15:57Z",
    "errorCode": "0",
    "errorMessage": "Successfully checked in content item 'ADC412030000000000000000000003'.",
    "id": "D574378400573ED9D62B3195T0000000000100000001",
    "modifiedBy": {
        "displayName": "User BB",
        "loginName": "userBBLoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000002",
        "type": "user"
    },
    "modifiedTime": "2014-02-21T21:18:20Z",
    "name": "example2.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "parentID": "FB4CD874EF94CD2CC1B60B72T0000000000100000001",
    "size": "13",
    "type": "file",
    "version": "2"
}

Example 3

The following example uploads a new version of a file using a multipart request. The example uses a public link ID protected by an access code because this file 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.

POST .../files/D574378400573ED9D62B3195T0000000000100000001/data/

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
LinkID: LF1F4C0670E07337F2A6AA1CB5D17B95F47087F4E518
Cookie: dAccessCode-LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518=test12345

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="example2.txt"
Content-Type: text/plain

This is example2.txt v2

-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "createdTime": "2014-02-21T21:15:57Z",
    "errorCode": "0",
    "errorMessage": "Successfully checked in content item 'ADC412030000000000000000000003'.",
    "id": "D574378400573ED9D62B3195T0000000000100000001",
    "modifiedBy": {
        "displayName": "User BB",
        "loginName": "userBBLoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000002",
        "type": "user"
    },
    "modifiedTime": "2014-02-21T21:18:20Z",
    "name": "example2.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "U0EAA20910FAF3052ACB79E4T00000000001",
        "type": "user"
    },
    "parentID": "FB4CD874EF94CD2CC1B60B72T0000000000100000001",
    "size": "13",
    "type": "file",
    "version": "2"
}

Example 4

The following example requests an upload of a new version of a file using a multipart request. Because this file is under a folder structure not owned by or shared with the current user, an access denied error message is returned.

POST .../files/D574378400573ED9D62B3195T0000000000100000001/data/

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="example2.txt"
Content-Type: text/plain

This is example2.txt v2

-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-20",
    "errorKey": "!csUnableToCheckIn,example2.txt!csCloudItemInsufficientPrivileges,User BB,fFileGUID:D574378400573ED9D62B3195T0000000000100000001,CHECKIN_UNIVERSAL",
    "errorMessage": "Content item 'example2.txt' was not successfully checked in. User 'User BB' has insufficient privilege to access fFileGUID:D574378400573ED9D62B3195T0000000000100000001 with service CHECKIN_UNIVERSAL.",
    "errorType": "file",
    "id": "D574378400573ED9D62B3195T0000000000100000001",
    "title": "Content item 'example2.txt' was not successfully checked in. User 'User BB' has insufficient privilege to access fFileGUID:D574378400573ED9D62B3195T0000000000100000001 with service CHECKIN_UNIVERSAL.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 5

The following example requests an upload of a new version of a file using a multipart request. This file 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.

POST .../files/D574378400573ED9D62B3195T0000000000100000001/data/

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
LinkID: LF1F4C0670E07337F2A6AA1CB5D17B95F47087F4E518

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="example2.txt"
Content-Type: text/plain

This is example2.txt v2

-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-18",
    "errorKey": "!csUnableToCheckIn,idcTestNewFile1KB.txt!csAccessCodeRequiredForLinkAccess",
    "errorMessage": "Content item 'idcTestNewFile1KB.txt' was not successfully checked in. The access code must be provided to access the link.",
    "errorType": "file",
    "id": "D574378400573ED9D62B3195T0000000000100000001",
    "title": "Content item 'idcTestNewFile1KB.txt' was not successfully checked in. The access code must be provided to access the link.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 6

The following example uploads a new version of a file using a multipart request. This example also sets metadata values for global collection CollectionA.

POST .../files/D4100E975A8096829C9CCB06B5D17B95F47087F4E518/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="primaryFile"; filename="fileWithMetadata.txt"
Content-Type: text/plain

This is version 2 of a file containing metadata values.
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="metadataValues"
Content-Type: application/json

{
    "collection": "CollectionA",
    "fieldA": "valueAv2",
    "fieldB": "valueBv2",
    "fieldC": "valueCv2"
}
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "createdBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "createdTime": "2016-07-13T19:47:23Z",
    "errorCode": "0",
    "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000001200",
    "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000001200'.",
    "id": "D4100E975A8096829C9CCB06B5D17B95F47087F4E518",
    "metadata": {
        "GlobalFile1": {
            "fieldA": "valueAv2",
            "fieldB": "valueBv2",
            "fieldC": "valueCv2"
        }
    },
    "mimeType": "text/plain",
    "modifiedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2016-07-13T19:52:48Z",
    "name": "fileWithMetadata.txt",
    "ownedBy": {
        "displayName": "User AA",
        "loginName": "userAALoginName",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "type": "user"
    },
    "parentID": "F79B040D5393DAC0F3511BBAB5D17B95F47087F4E518",
    "size": "56",
    "type": "file",
    "version": "2"
}

Example 7

The following example uploads a new version of a file using a multipart request. The example uses an applink because this file 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.

POST .../files/DED694950C14AFF280419F9AB5D17B95F47087F4E518/data

Request Header

Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg==
accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ

Request Body

-----------------------------7dc7c172076a

Content-Disposition: form-data; name="primaryFile"; filename="fileViaApplink.txt"
Content-Type: text/plain

This is fileViaApplink.txt v2
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "createdBy": {
        "displayName": "Tenant2.UserB",
        "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "type": "user"
    },
    "createdTime": "2017-06-26T15:29:00Z",
    "errorCode": "0",
    "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000007006",
    "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000007006'.",
    "id": "DED694950C14AFF280419F9AB5D17B95F47087F4E518",
    "mimeType": "text/plain",
    "modifiedBy": {
        "displayName": "Tenant2.UserB",
        "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
        "type": "user"
    },
    "modifiedTime": "2017-06-29T22:00:33Z",
    "name": "fileViaApplink.txt",
    "ownedBy": {
        "displayName": "Tenant2.UserA",
        "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470",
        "loginName": "Tenant2.UserA",
        "type": "user"
    },
    "parentID": "FDC22B65E850730CAA60AF83B5D17B95F47087F4E518",
    "size": "29",
    "type": "file",
    "version": "3"
}