Skip to main content
Version: v5.0

Overview

The File API provides a range of API calls for basic file operations in the File Service.

These File API calls are:

Note: The nsfilter (namespace filter) query parameter is mandatory for every request. It sets the context, helping you look up resources within that namespace. Example: GET /files?nsfilter=proj_DrZrSNrW

API Calls

Create Folder#

This API call creates a folder in the File Service.

Endpoints#

POST /filesvc/api/v1/files

Parameters#

Query#

ParameterTypeDescriptionRequired
"_name"StringName your folderRequired
"_namespaces"Array of StringOne or more namespaces you want to add the folder toRequired
"_parents"Array of FileCreate one or more parent folders in an empty root directory. To create more than one folder, add them to a comma separated string.Optional
"_tags"StringAdd tags to your folder object in a comma separated string. You can add a maximum of 10 tags with each tag a maximum of 50 characters.Optional
nsfilterStringnamespace context, Please note that both _namespaces and nsfilter requiredRequired
Code example#
/filesvc/api/v1/files?_name=My folder name&_namespaces=SampleProject_O61pLOhd&nsfilter=SampleProject_O61pLOhd

Response#

Codes#

CodeDescription
200Success
400Bad Request

Body#

Code example#
{  "_nextVersion": 1,  "_namespaces": [    "SampleProject_O61pLOhd"  ],  "_name": "Level0",  "_tipVersion": 0,  "_type": "dir",  "_irn": "filesvc:file:8a972d06-e881-4452-b140-ab5644d743ec",  "_id": "8a972d06-e881-4452-b140-ab5644d743ec",  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxx",    "_createdAt": 1530083734541,    "_updatedByName": "xxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1530083734541  },  "_parents": []}
Body schema#
FieldTypeDescriptionRequired
"_nextVersion"Number
"_namespaces"Array of StringAn array of one or more namespaces that contain the file.Required
"_name"StringThe file's name.
"_tipVersion"NumberThe latest version of the file.
"_type"StringThe file's type.
"_irn"StringThe resource path. Concetenate the service name, resource type, and resource's id with colons, for example, filesvc:file:6336c490017d84b0a506e453 for a file or filesvc:file:* for all files in the file service.Required
"_metadata"ObjectAn object that contains the file's metadata.
"_parents"Array of StringAn array of one or more parent folders that contain the file.

Upload File#

This API call performs a normal file upload to the file service.

Note: If you want to perform a resumable file upload, see Resumable File Upload.

Endpoints#

POST /filesvc/api/v1/files

The body of the upload should be formatted as a standard multipart/form.

Parameters#

Query#

ParameterTypeDescriptionRequired
fileStringName your fileRequired
_namespacesArray of StringAdd your file to one or more namespacesRequired
_parentsArray of FileCreate one or more parent folders in an empty root directory that contains the file or files. To create more than one folder, add them to a comma separated string.Optional
nsfilterStringnamespace context, Please note that both _namespaces and nsfilter requiredRequired
_tagsStringAdd tags to your file object in comma separated string. You can add a maximum of 10 tags with each tag a maximum of 50 characters.Optional
nsfilterStringnamespace context, Please note that both _namespaces and nsfilter requiredRequired

Request Headers#

The headers will be used while downloading files.

HeaderTypeDescriptionRequired
content-encodingStringSpecify content encoding such as gzipOptional
content-typeStringSpecify content type such as image/png, application/pdfOptional

Response#

Codes#

CodeDescription
201Created
400Bad Request

Body#

Code example#
[  {    "_nextVersion": 2,    "_namespaces": [      "SampleProject_O61pLOhd"    ],    "_previews": [      {        "_id": "f80d0d47-4216-4edb-aa42-3c067d059d80",        "_width": 640,        "_height": 480,        "_fileVersionId": "660731b1-ef83-41e1-9a18-436645f0d7b8"      }    ],    "_fileVersion": {      "_fileSize": 285165,      "_id": "660731b1-ef83-41e1-9a18-436645f0d7b8",      "_metadata": {        "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",        "_createdByName": "xxxxxxx",        "_createdAt": 1530084463050,        "_updatedByName": "xxxxxxx",        "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",        "_updatedAt": 1530084463050      },      "_version": 1,      "_fileId": "283ac08e-6b80-47aa-b062-4664b065a905"    },    "_name": "33333.jpg",    "_tipVersion": 1,    "_tipId": "660731b1-ef83-41e1-9a18-436645f0d7b8",    "_type": "file",    "_irn": "filesvc:file:283ac08e-6b80-47aa-b062-4664b065a905",    "_id": "283ac08e-6b80-47aa-b062-4664b065a905",    "_metadata": {      "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_createdByName": "xxxxxxx",      "_createdAt": 1530084463050,      "_updatedByName": "xxxxxxx",      "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_updatedAt": 1530084463050    },    "_parents": [      "8a972d06-e881-4452-b140-ab5644d743ec"    ]  },  {    "_nextVersion": 2,    "_namespaces": [      "SampleProject_O61pLOhd"    ],    "_previews": [      {        "_id": "523ca20f-22c7-4e0d-8170-fda844e53eb6",        "_width": 640,        "_height": 480,        "_fileVersionId": "03e9e62e-2170-439d-9040-0c1673711a46"      }    ],    "_fileVersion": {      "_fileSize": 285165,      "_id": "03e9e62e-2170-439d-9040-0c1673711a46",      "_metadata": {        "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",        "_createdByName": "xxxxxxx",        "_createdAt": 1530084463361,        "_updatedByName": "xxxxxxx",        "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",        "_updatedAt": 1530084463361      },      "_version": 1,      "_fileId": "8aef69d9-d6f8-4c69-b6b9-65a39e00742e"    },    "_name": "111111.jpg",    "_tipVersion": 1,    "_tipId": "03e9e62e-2170-439d-9040-0c1673711a46",    "_type": "file",    "_irn": "filesvc:file:8aef69d9-d6f8-4c69-b6b9-65a39e00742e",    "_id": "8aef69d9-d6f8-4c69-b6b9-65a39e00742e",    "_metadata": {      "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_createdByName": "xxxxxxx",      "_createdAt": 1530084463361,      "_updatedByName": "xxxxxxx",      "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_updatedAt": 1530084463361    },    "_parents": [      "8a972d06-e881-4452-b140-ab5644d743ec"    ]  }]
Body schema#
FieldTypeDescriptionRequired
_nextVersionNumber
_namespacesArray of StringAn array of one or more namespaces that contain the file.Required
_previewsArray of ObjectAn array of one or more preview objects.Required
_fileVersionObjectAn object with file version information.Required
_nameStringThe file's name.
_tipVersionNumberThe latest version of the file.
_tipIdStringThe latest file version's id.
_typeStringThe file's type.
_irnStringThe file's resource number.Required
_metadataObjectAn object that contains the file's metadata.
_parentsArray of StringAn array of one or more parent folders that contain the file.

Get Files#

This API call retrieves a set of files from one or more namespaces.

Endpoints#

GET /filesvc/api/v1/files

Parameters#

Query#

ParameterTypeDescriptionRequired
_namespacesArray of StringFetch files from one or more namespaces you provide. If you do not pass any namespaces, the query fetches files in all the namespaces in your principal info.Optional
_parentsArray of FileFetch files from one or more parent folders. If you do not pass any parent folder, the query fetches files from all folders. If you pass multiple parent folders, the query response fetches only files common to all the parent folders. To search from the root folder, pass _parents=root.Optional
_idsStringTo query by file id, pass an id or a comma-separated string with up to 200 file ids.Optional
_nameStringTo query a name, pass a Regex value, such as geom*.2d or .*bimpk.Optional
_tagsStringAdd a tag or add multiple tags as a comma-separated string.Optional
_statusStringFilter by file status.Optional
_offsetNumberSet a response control option for offset.Optional
_pageSizeNumberSet a response control option for offset. The default value is 25 and the maximum value is 200.Optional
withUrlBooleanThe response also have download url for the files, Note that URL exists only when the file status is 'UPLOAD_COMPLETED'Optional
nsfilterStringnamespace contextRequired

Response#

Codes#

CodeDescription
200Success
400Bad Request

Body#

Code example#
{  "_pageSize": 2,  "_list": [    {      "_nextVersion": 2,      "_namespaces": [        "lntpurelocal_Xw6AQru7"      ],      "_name": "pdf-sample_25_7.pdf",      "_tipVersion": 1,      "_tipId": "e8b12f04-f8b9-4af4-a0c8-ce2ebdc2b796",      "_type": "file",      "_irn": "filesvc:file:ba466d37-92e6-47a1-9c77-f4dd5be988ec",      "_id": "ba466d37-92e6-47a1-9c77-f4dd5be988ec",      "_status": "UPLOAD_COMPLETED",      "_metadata": {        "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",        "_createdAt": 1559644347163,        "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",        "_updatedAt": 1559644347252      },      "_parents": []    },    {      "_nextVersion": 2,      "_namespaces": [        "lntpurelocal_Xw6AQru7"      ],      "_name": "sample.pdf",      "_tipVersion": 1,      "_tipId": "f7635683-6178-4b46-b55b-851fc38c36bb",      "_type": "file",      "_irn": "filesvc:file:f0c69ce3-c4b1-4453-acf5-a2923ffaace5",      "_id": "f0c69ce3-c4b1-4453-acf5-a2923ffaace5",      "_status": "UPLOAD_COMPLETED",      "_metadata": {        "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",        "_createdAt": 1561011074671,        "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",        "_updatedAt": 1561011074915      },      "_parents": [        "72038db4-f645-4cbd-a92d-e253345766b0"      ]    }  ],  "_offset": 0,  "_total": 2,  "_includeTotal": true}
Response body schema#
FieldTypeDescriptionRequired
"_nextVersion"NumberOptional
"_namespaces"Array of StringAn array of one or more namespaces that contain the file.Required
"_name"StringThe file's nameOptional
"_tipVersion"NumberThe latest version of the fileOptional
"_tipId"StringThe latest file version's idOptional
"_type"StringThe file's typeOptional
"_irn"StringThe resource path. Concetenate the service name, resource type, and resource's id with colons, for example, filesvc:file:6336c490017d84b0a506e453 for a file or filesvc:file:* for all files in the file service.Required
"_id"StringThe file's idRequired
"_status"StringThe file's statusRequired
"_metadata"ObjectAn object that contains the file's metadataOptional
"_parents"Array of StringAn array of one or more parent folders that contain the file.Optional
"_offset"NumberResponse control offset optionsRequired
"_total"NumberThe total number of files in the responseOptional
"_includeTotal"BooleanIncludes the total number of files in the responseOptional

Get Folder Files#

This API call retrieves the files that match your filter in a folder.

Endpoints#

GET /filesvc/api/v1/files/{parent_id}/children

Parameters#

Path#

ParameterTypeDescriptionRequired
parent_idStringPass the file's id.Required

Query#

ParameterTypeDescriptionRequired
_namespacesArray of StringFetch files from one or more namespaces you provide. If you do not pass any namespaces, the query fetches files in all the namespaces in your principal info.Optional
_idsStringTo query by file id, pass an id or a comma separated string with up to 200 file ids.Optional
_nameStringTo query a name, pass a Regex value, such as geom*.2d or .*bimpk.Optional
_tagsStringAdd a tag or add multiple tags as a comma-separated string.Optional
_offsetNumberSet a response control option for offset.Optional
_pageSizeNumberSet a response control option for offset. The default value is 25 and the maximum value is 200.Optional
nsfilterStringnamespace contextRequired

Response#

Codes#

CodeDescription
200Success
400Bad Request

Response#

Code example#
{  "_pageSize": 1,  "_list": [    {      "_nextVersion": 2,      "_namespaces": [        "lntpurelocal_Xw6AQru7"      ],      "_name": "sample.pdf",      "_tipVersion": 1,      "_tipId": "f7635683-6178-4b46-b55b-851fc38c36bb",      "_type": "file",      "_irn": "filesvc:file:f0c69ce3-c4b1-4453-acf5-a2923ffaace5",      "_id": "f0c69ce3-c4b1-4453-acf5-a2923ffaace5",      "_status": "UPLOAD_COMPLETED",      "_metadata": {        "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",        "_createdAt": 1561011074671,        "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",        "_updatedAt": 1561011074915      },      "_parents": [        "72038db4-f645-4cbd-a92d-e253345766b0"      ]    }  ],  "_offset": 0,  "_total": 1,  "_includeTotal": true}
Body schema#
FieldTypeDescriptionRequired
_pageSizeNumberThe number of results per page
_listArray of ObjectAn array of one or more folders that match your query.Required
_nextVersionNumber
_namespacesArray of StringAn array of one or more namespaces that contain the file.Required
_nameStringThe file's name
_tipVersionNumberThe latest version of the file
_tipIdStringThe latest file version's id
_typeStringThe file's type
_irnStringThe resource path. Concetenate the service name, resource type, and resource's id with colons, for example, filesvc:file:6336c490017d84b0a506e453 for a file or filesvc:file:* for all files in the file service.Required
_idStringThe file's idRequired
_statusStringThe file's statusRequired
_metadataObjectAn object that contains the file's metadata
_parentsArray of StringAn array of one or more parent folders that contain the file.

Get File by ID#

This API call retrieve a file with a specific ID.

Endpoints#

GET /filesvc/api/v1/files/{id}

Parameters#

Query#

  • nsfilter - namespace context (Required)

Path#

ParameterTypeDescriptionRequired
idStringPass the file's ID.Optional

Response#

Codes#

CodeDescription
200Success
404File Not Found

Body#

Code example#
{  "_nextVersion": 1,  "_namespaces": [    "xxxx_yyyy"  ],  "_previews": [],  "_name": "Level0",  "_tipVersion": 0,  "_type": "dir",  "_irn": "filesvc:file:8a972d06-e881-4452-b140-ab5644d743ec",  "_id": "8a972d06-e881-4452-b140-ab5644d743ec",  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxx",    "_createdAt": 1530083734541,    "_updatedByName": "xxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1530083734541  },  "_parents": []}
Body schema#
FieldTypeDescriptionRequired
_nextVersionNumber
_namespacesArray of StringAn array of one or more namespaces that contain the file.Required
_previewsArray of ObjectAn array of one or more preview objects.Required
_nameStringThe file's name.
_tipVersionNumberThe latest version of the file.
_typeStringThe file's type.
_irnStringThe resource path. Concetenate the service name, resource type, and resource's id with colons, for example, filesvc:file:6336c490017d84b0a506e453 for a file or filesvc:file:* for all files in the file service.Required
_metadataObjectAn object that contains the file's metadata.
_parentsArray of StringAn array of one or more parent folders that contain the file.

Update File#

This API call allows you to update a file or edit its tags in the File Service.

Endpoints#

PUT /filesvc/api/v1/files/{id}

Parameters#

Query#

  • nsfilter - namespace context (Required)

Path#

ParameterTypeDescriptionRequired
idStringPass the file's id.Required

Body#

ParameterTypeDescriptionRequired
_nameStringPass the new file name with its file extension.Required
_tagsArray of StringUpdate the tags in your file object. You can add up to 10 tags with each tag a maximum of 50 characters.Optional
Code example#
{  "_name": "renamed_file.png"}

Response#

Codes#

CodeDescription
200Success
400File Not Found

Body#

Body#
{  "_nextVersion": 2,  "_namespaces": [    "xxxx_yyyy"  ],  "_name": "renamed_file.png",  "_tipVersion": 1,  "_tipId": "4d45433b-85d1-44c1-829d-22adc7515c2e",  "_type": "file",  "_irn": "filesvc:file:0947ea1a-dae3-4498-b4e3-0d4e7a3a4d37",  "_id": "0947ea1a-dae3-4498-b4e3-0d4e7a3a4d37",  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxx",    "_createdAt": 1530089625693,    "_updatedByName": "xxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1530089625693  },  "_parents": []}

Code example

FieldTypeDescriptionRequired
_nextVersionNumber
_namespacesArray of StringAn array of one or more namespaces that contain the file.Required
_nameStringThe file's name
_tipVersionNumberThe latest version of the file
_tipIdStringThe latest file version's id
_typeStringThe file's type
_irnStringThe resource path. Concetenate the service name, resource type, and resource's id with colons, for example, filesvc:file:6336c490017d84b0a506e453 for a file or filesvc:file:* for all files in the file service.Required
_metadataObjectAn object that contains the file's metadata
_parentsArray of StringAn array of one or more parent folders that contain the file.

Get Download URL#

This API call retrieves a download URL for a file in the File Service.

Endpoints#

GET /filesvc/api/v1/files/{id}/url

Parameters#

Query#

  • nsfilter - namespace context (Required)

Path#

ParameterTypeDescriptionRequired
idStringPass the file's ID.Required

Response#

Codes#

CodeDescription
200Success
400Bad Request
404File Not Found

Body#

Code example#
{  "_nextVersion": 2,  "_namespaces": [    "xxxx_yyyy"  ],  "_name": "renamed_file.png",  "_tipVersion": 1,  "_tipId": "4d45433b-85d1-44c1-829d-22adc7515c2e",  "_type": "file",  "_irn": "filesvc:file:0947ea1a-dae3-4498-b4e3-0d4e7a3a4d37",  "_id": "0947ea1a-dae3-4498-b4e3-0d4e7a3a4d37",  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxx",    "_createdAt": 1530089625693,    "_updatedByName": "xxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1530089625693  },  "_url": "xxxxxxx",  "_parents": []}
Body schema#
FieldTypeDescriptionRequired
_nextVersionNumber
_namespacesArray of StringAn array of one or more namespaces that contain the file.Required
_nameStringThe file's name
_tipVersionNumberThe latest version of the file
_tipIdStringThe latest file version's ID
_typeStringThe file's type
_irnStringThe resource path. Concetenate the service name, resource type, and resource's id with colons, for example, filesvc:file:6336c490017d84b0a506e453 for a file or filesvc:file:* for all files in the file service.Required
_metadataObjectAn object that contains the file's metadata
_parentsArray of StringAn array of one or more parent folders that contain the file.

Get Preview URL#

This API call returns a URL that links to a preview of a file in the file service.

Endpoints#

GET /filesvc/api/v1/files/{id}/previewurl

Parameters#

Query#

  • nsfilter - namespace context (Required)

Path#

ParameterTypeDescriptionRequired
idStringPass the file's id.Required

Query#

ParameterTypeDescriptionRequired
widthNumberThe preview width. Currently, the only supported value is 640.Required
heightNumberThe preview width. Currently, the only supported value is 480.Required

Response#

Codes#

CodeDescription
200Success
400Bad Request
404File Not Found

Body#

Code example#
{  "_nextVersion": 2,  "_namespaces": [    "xxxx_yyyy"  ],  "_name": "renamed_file.png",  "_tipVersion": 1,  "_previewUrl": "xxxxxxxx",  "_tipId": "4d45433b-85d1-44c1-829d-22adc7515c2e",  "_type": "file",  "_irn": "filesvc:file:0947ea1a-dae3-4498-b4e3-0d4e7a3a4d37",  "_id": "0947ea1a-dae3-4498-b4e3-0d4e7a3a4d37",  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxx",    "_createdAt": 1530089625693,    "_updatedByName": "xxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1530089625693  },  "_parents": []}
Body schema#
FieldTypeDescriptionRequired
_nextVersionNumber
_namespacesArray of StringAn array of one or more namespaces that contain the file.Required
_nameStringThe file's name
_tipVersionNumberThe latest version of the file
_previewUrlStringThe preview URL
_tipIdStringThe latest file version's id
_typeStringThe file's type
_irnStringThe resource path. Concetenate the service name, resource type, and resource's id with colons, for example, filesvc:file:6336c490017d84b0a506e453 for a file or filesvc:file:* for all files in the file service.Required
_metadataObjectAn object that contains the file's metadata
_parentsArray of StringAn array of one or more parent folders that contain the file.

Get File Versions#

This API call retrieves the versions of a file in the file service.

Endpoints#

GET /filesvc/api/v1/files/{id}/versions

Parameters#

Query#

  • nsfilter - namespace context (Required)

Path#

ParameterTypeDescriptionRequired
idStringPass the file's id.Optional

Response#

Codes#

CodeDescription
200Success
404File Not Found

Response#

Body#
{  "_pageSize": 1,  "_list": [    {      "_fileSize": 285165,      "_id": "72ef7153-360b-4bd9-be7a-e1b0dcbd7d1d",      "_metadata": {        "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",        "_createdByName": "xxxxxxx",        "_createdAt": 1530089332667,        "_updatedByName": "xxxxxxx",        "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",        "_updatedAt": 1530089332667      },      "_version": 1,      "_fileId": "c48bd75d-4818-4dc7-85e5-3a6c0ebe3859"    }  ],  "_offset": 0,  "_total": 1,  "_includeTotal": true}
Body schema#
FieldTypeDescriptionRequired
_pageSizeNumberThe number of results per page
_listArray of ObjectAn array of one or more file versionsRequired
_fileSizeNumberThe file size in bytes
_idStringThe file version's IDRequired
_metadataObjectAn object that contains the file's metadata
_versionNumberThe file version's version number
_fileIdNumberThe file's ID
_offsetNumberResponse control offset optionsRequired
_totalNumberThe total number of files in the response
_includeTotalBooleanIncludes the total number of files in the response

Delete File#

This API call deletes a file from the file service.

Endpoints#

DELETE /filesvc/api/v1/files/{id}

Parameters#

Query#

  • nsfilter - namespace context (Required)

Path#

ParameterTypeDescriptionRequired
idStringPass the file's id.Optional

Response#

Codes#

CodeDescription
204No Content
404File Not Found

Delete Files#

This API call deletes multiple files from the file service.

Endpoints#

DELETE /filesvc/api/v1/files

Parameters#

Query#

  • nsfilter - namespace context (Required)

Body#

Array of file ids

[  "14e63426-e664-44bc-a85e-697fbf00b01f" ,  "650d9886-3534-445c-b514-0f0a426078a9",  "cfd0bc81-d9b7-4892-a83f-47af96a48c96"]

Response#

Codes#

CodeDescription
204No Content
404File Not Found