IntroductionBefore you beginTerminologyGetting started
Authorization
Accounts
Entities
User accounts
GroupsFilesThe file objectRetrieve file informationCopy or move a fileUpload a fileDownload a fileDelete a fileFoldersTemplatesEmail templatesAppsErrors

Files

Files are managed using the /nodes/pth resource. This structure is key to integrating with SmartVault if you are using the generic integration model.
You can retrieve, copy, move and delete a file, as well as upload and download them.







The file object

Show Attributes








Retrieve file information

You can also use the /nodes/pth structure to get information about a file, including its file ID and various links for previewing and downloading the file.

Get file
GET/nodes/pth/{path}/{filename}

Parameters


pathstringThe folder path containing the file, including the account and vault
filenamestringThe full file name, including the extension.


Query parameters


In the SmartVault infrastructure, all files are stored under a folder. To list all the files a folder has we can simply use the "children" query parameter as well as some others to tweak the endpoint response.

Show query parameters



Request


curl --include \
--header "Authorization: Basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==" \
--header "Accept: application/json" \
'https://rest.smartvault.com/nodes/pth/{path}/{filename}'

Response


Returns a file object.

Show success object


Returns an error object if the file doesn't exist.

Show error object








Copy or move a file

To copy or move a file, you need to execute a POST request to the url pointing at the file you'd like to copy / move and pass the parameters specified below in the body of the request.
Note that you need to specify the filename, otherwise it'll move the whole folder.
Copy or move file
POST/nodes/pth/{path}/{filename}


Body parameters


dst_uristringThe destination URI starting from /nodes/pth. This must include the destination file name and extension.
replacestringSets what to do if the file already exists.Values can be "fail" or "replace"

For copying a file the body of the request would need to be:

{
"copy": {
"dst_uri": "/nodes/pth/{path}/{filename}",
"replace": "Replace"
}
}

Instead, if what you want is to move a certain file:

{
"move": {
"dst_uri": "/nodes/pth/{path}/{filename}",
"replace": "Replace"
}
}

Request


We'll use the "copy" keyword for the request body as default for the examples below. As it's specified above, the body of the request would need to change in case you'd wanted to move the file instead.


Headers:
Content-Type:application/json
Authorization:Basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==
Accept:application/json
Body:
{
"copy": {
"dst_uri": "/nodes/pth/SmartVault/testing/OtherFolder/hello.txt",
"replace": "Replace"
}
}

Response


Returns a file object if the object exist.

Show success object


Returns an error object if the object can't be found.

Show error object








Upload a file

Uploading documents requires three steps, each of them related to a PUT request.

Add information about the document.
Add the document version.
Upload the file.

Add the file metadata


Specify the path to the file via param and the name of it on the body of the request.

Upload 1st step
PUT/nodes/pth/{path}

Parameters


pathstringThe destination URI starting from /nodes/pth.


Body parameters


namestringThe name for the file to be uploaded.
{
"create_file": [
{
"name": "newUploadedFile.jpg"
}
]
}

Request


Headers:
Content-Type:application/json
Authorization:Basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==
Accept:application/json
Body:
{
"create_file": [
{
"name": "hello.txt"
}
]
}

Response


Returns a folder object if the object exist.

Show success object


Returns an error object if the file name is not present in the request body.

Show error object


The file ID


You should be able to see your new defined file in the "children" array of the answer.
Right after the "&id" characters in the link_uri, preview_link_uri or download_link_uri parameters of the child object you should find the ID of the new uploaded file that you'll need for the next step.

"link_uri": "https://my.smartvault.com/users/secure/ElementBrowser.aspx?type=Document&id= v2fFF5ZFnESuP3usjl5yHw",

In the given example the id would be v2fFF5ZFnESuP3usjl5yHw




Add the document version


Use the recently created file ID on the request and specify the file version on the body of the request.

Upload 2nd step
PUT/nodes/upload/{file_id}

Parameters


file_idstringThe file ID.


Body parameters


lengthnumberThe exact size in bytes of the file that you'll upload on the 3rd step.
{
"length": 14346
}

md5_checksumstring (optional)You can specify a md5 checksum of the file. The server will set the checksum of the file itself if no one is specified.

Request


Headers:
Content-Type:application/json
Authorization:Basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==
Accept:application/json
Body:
{
“length”: 7
}

Response


Returns a file object if the ID exist.

Show success object


Returns an error object if the file id doesn't exist.

Show error object


The file document version ID


In the fileExProperties object you can see the url you'd need to execute to upload the file bits to the file. In the example given:

/nodes/adlopu / v2fFF5ZFnESuP3usjl5yHw / qOKhq_gaLE6462IOKsvQig;

File ID: v2fFF5ZFnESuP3usjl5yHw.
Document version ID: qOKhq_gaLE6462IOKsvQig. (We will use this in the next step)



Upload the file


Upload the file bits to the file. We need the file id and the document version id described before.
You should be able to use the "upload_uri" of the previous step return object as the endpoint url.

Upload 3rd step
PUT/nodes/upload/{file_id}/{doc_version_id}

Headers


We need to set a specific header for this request:

Content-Type: application/binary

Parameters


filebinaryThe file.


Request


Headers:
Content-Type:application/binary
Authorization:Basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==
Accept:application/binary
Body:
your_file

Response


Returns a file object if the object exist.

Show success object


Returns an error object if the file size doesn't match the length that was specified in the previous request.

Show error object








Download a file

Downloading files requires the document ID.
You can find the ID, the endpoint GET request path ("download_uri") and the direct link to download the file ("download_link_uri") on the File object as a successful call to the getting file information request.

Get file
GET/files/id/Document/{doc_id}

Parameters


doc_idnumberThe file ID of the file being retrieved


Request


curl --include \
--header "Authorization: Basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==" \
'https://rest.smartvault.com/files/id/Document/{docid}'

Response


Will return the file itself if the file ID specified is correct and / or exists.

Returns an error object if the file id doesn't exist.

Show error object








Delete a file

Delete a file at the given path. Be careful to specify the filename, otherwise you'll be deleting the whole folder.

Delete file
DELETE/nodes/pth/{path}

Parameters


pathstringThe file path; including the account, vault and the full file name (including extension)


Request


curl --include \
--request DELETE \
--header "Authorization: Basic dGVzdHVzZXJAc21hcnR2YXVsdC5jb206UTB4Sk1EQUFBQUFBQUFBQlVZRE9MOE82N3oyQjdvVmJLcytWMngybmZHTXgzR2FzY2pNUEp4Y0dGeHZPeWc9PQ==" \
--header "Accept: application/json" \
'https://rest.smartvault.com/nodes/pth/path'

Response


Returns a default success object or an error object if the file you are trying to delete doesn't exist.

Show result object