REST API for Documents

Upload Custom Rendition

post

/documents/api/1.2/files/{fileId}/data/rendition

Upload a custom rendition file to the latest file version, using a multipart request. The given name will be used to uniquely identify this rendition within a file version.

Request

Supported Media Types

multipart/form-data

Path Parameters

fileId: string

Globally unique identifier (GUID) for the file.

Header Parameters

accessToken(optional): 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(optional): 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(optional): 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(optional): string

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

Form Parameters

file: file

Custom rendition file to upload.
jsonInputParameters: string
You can use this parameter to include the name parameter and the description parameter as a JSON payload with the request.
Set name as a unique identifier for this custom rendition within the file's latest revision scope.
The name parameter must be sent as a part of this JSON payload. This parameter is required.
For example:
{ "name": "smallCustomRendition" }
The following restrictions apply to name:
- The length of name can't exceed 28 characters.
- The name parameter isn't case-sensitive; that is, smallRendition and smallrendition are considered identical.
- The name parameter is limited to English letters, numbers, the hyphen character, and the underscore character only. Use of other characters will cause failure.
The description parameter can be sent as a part of this JSON payload. This parameter is optional.
For example:
{ "name": "smallCustomRendition", "description": "This is a small rendition version for this file" }

Response

Supported Media Types

application/json
application/xml

200 Response

Created. The request was fulfilled and the new resource was created.

Root Schema : FileCustomRenditionResponse

Type: object

The response body includes information about the uploaded rendition.

Show Source

errorCode(optional): number

An error code of zero (0) indicates no errors.
id(optional): string

Globally unique identifier (GUID) of the file.
type(optional): string

Item type file.

{
    "description":"The response body includes information about the uploaded rendition.",
    "properties":{
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) of the file."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>file</code>."
        },
        "errorCode":{
            "type":"number",
            "description":"An error code of zero (0) indicates no errors."
        }
    }
}

Example Response (application/json)

{
    "id":"D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "type":"file",
    "errorCode":"0"
}

400 Response

A mandatory parameter is missing or an invalid parameter was provided.

403 Response

Forbidden if the user does not have write permission.

404 Response

File ID is not found.

409 Response

A custom rendition with the given name already exists in the latest version.

Examples

The following example uploads a custom rendition image named small to the latest revision of an existing file.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/data/rendition

Request Header

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

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="file"; filename="smallJellyfish.png"
Content-Type: image/jpeg


<CONTENT OF IMAGE FILE>
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"name":"small",
"description":"jellyfish small custom rendition"
}
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "id": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "type": "file"
}

Example 2

The following example uploads a custom rendition image named small to the latest revision of an existing file. The latest revision of this file already has a custom rendition named small.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/data/rendition

Request Header

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

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="file"; 
filename="smallJellyfish.png"
Content-Type: image/jpeg

<CONTENT OF IMAGE FILE>
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"name":"small",
"description":"jellyfish small custom rendition version 2"
}
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 409

JSON Response

{
    "errorCode": "-17",
    "errorKey": "!csRenditionsUnableToAddDuplicateName,small",
    "errorMessage": "The 'small' attachment already exists. No attachments will be added.",
    "errorType": "file",
    "id": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "title": "The 'small' attachment already exists. No attachments will be added.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 3

The following example uploads a custom rendition image without the name parameter to the latest revision of an existing file.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/data/rendition

Request Header

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

Request Body

-----------------------------7dc7c172076a
Content-Disposition: form-data; name="file"; 
filename="smallJellyfish.png"
Content-Type: image/jpeg

<CONTENT OF IMAGE FILE>
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"description":"this is my custom rendition"
}
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "errorCode": "-97",
    "errorKey": "!csRequiredFieldMissing,name",
    "errorMessage": "Required field 'name' is missing.",
    "errorType": "file",
    "id": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "title": "Required field 'name' is missing.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 4

The following example uploads a custom rendition image named applinkRendition to the latest revision of an existing file. The example uses an applink ID 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/rendition

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="file"; filename="appLinkCustomRendition.png"
Content-Type: image/jpeg


<CONTENT OF IMAGE FILE>
-----------------------------7dc7c172076a
Content-Disposition: form-data; name="parameters"
Content-Type: application/json

{
"name":"applinkRendition",
"description":"custom rendition via applink"
}
-----------------------------7dc7c172076a--

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "id": "DED694950C14AFF280419F9AB5D17B95F47087F4E518",
    "type": "file"
}