Overview

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

These File API calls are:

• Create Folder
• Upload File
• Get Files
• Get Folder Files
• Get File by ID
• Update File
• Move File
• Get Download URL
• Get Preview URL
• Get File Versions
• Delete File
• Delete Files

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

Parameter	Type	Description	Required
"_name"	String	Name your folder	Required
"_namespaces"	Array of String	One or more namespaces you want to add the folder to	Required
"_parents"	Array of File	Create 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"	String	Add 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
nsfilter	String	namespace context, Please note that both _namespaces and nsfilter required	Required

Code example

/filesvc/api/v1/files?_name=My folder name&_namespaces=SampleProject_O61pLOhd&nsfilter=SampleProject_O61pLOhd

Response

Codes

Code	Description
200	Success
400	Bad 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

Field	Type	Description	Required
"_nextVersion"	Number
"_namespaces"	Array of String	An array of one or more namespaces that contain the file.	Required
"_name"	String	The file's name.
"_tipVersion"	Number	The latest version of the file.
"_type"	String	The file's type.
"_irn"	String	The 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"	Object	An object that contains the file's metadata.
"_parents"	Array of String	An 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

Parameter	Type	Description	Required
file	String	Name your file	Required
_namespaces	Array of String	Add your file to one or more namespaces	Required
_parents	Array of File	Create 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
nsfilter	String	namespace context, Please note that both _namespaces and nsfilter required	Required
_tags	String	Add 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
nsfilter	String	namespace context, Please note that both _namespaces and nsfilter required	Required

Request Headers

The headers will be used while downloading files.

Header	Type	Description	Required
content-encoding	String	Specify content encoding such as gzip	Optional
content-type	String	Specify content type such as image/png, application/pdf	Optional

Response

Codes

Code	Description
201	Created
400	Bad 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

Field	Type	Description	Required
_nextVersion	Number
_namespaces	Array of String	An array of one or more namespaces that contain the file.	Required
_previews	Array of Object	An array of one or more preview objects.	Required
_fileVersion	Object	An object with file version information.	Required
_name	String	The file's name.
_tipVersion	Number	The latest version of the file.
_tipId	String	The latest file version's id.
_type	String	The file's type.
_irn	String	The file's resource number.	Required
_metadata	Object	An object that contains the file's metadata.
_parents	Array of String	An 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

Parameter	Type	Description	Required
_namespaces	Array of String	Fetch 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
_parents	Array of File	Fetch 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
_ids	String	To query by file id, pass an id or a comma-separated string with up to 200 file ids.	Optional
_name	String	To query a name, pass a Regex value, such as geom*.2d or .*bimpk.	Optional
_tags	String	Add a tag or add multiple tags as a comma-separated string.	Optional
tagMode	String	Controls how multiple _tags values are combined. Accepted values: or (default) returns files that match any of the specified tags; and returns only files that match all of the specified tags. Omitting this parameter defaults to or behavior. Returns 400 for any other value.	Optional
_status	String	Filter by file status.	Optional
_offset	Number	Set a response control option for offset.	Optional
_pageSize	Number	Set a response control option for offset. The default value is 25 and the maximum value is 200.	Optional
withUrl	Boolean	The response also have download url for the files, Note that URL exists only when the file status is 'UPLOAD_COMPLETED'	Optional
nsfilter	String	namespace context	Required

Tag filtering examples

Example	Behavior
GET /files?_tags=book,movie	Returns files tagged book or movie (default OR behavior)
GET /files?_tags=book,movie&tagMode=or	Returns files tagged book or movie (explicit OR)
GET /files?_tags=book,movie&tagMode=and	Returns only files tagged both book and movie
GET /files?_tags=book&tagMode=and	Returns files tagged book (single tag — AND and OR produce identical results)
GET /files?_tags=book&tagMode=xyz	Returns 400 Bad Request — unsupported tagMode value

Response

Codes

Code	Description
200	Success
400	Bad 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

Field	Type	Description	Required
"_nextVersion"	Number		Optional
"_namespaces"	Array of String	An array of one or more namespaces that contain the file.	Required
"_name"	String	The file's name	Optional
"_tipVersion"	Number	The latest version of the file	Optional
"_tipId"	String	The latest file version's id	Optional
"_type"	String	The file's type	Optional
"_irn"	String	The 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"	String	The file's id	Required
"_status"	String	The file's status	Required
"_metadata"	Object	An object that contains the file's metadata	Optional
"_parents"	Array of String	An array of one or more parent folders that contain the file.	Optional
"_offset"	Number	Response control offset options	Required
"_total"	Number	The total number of files in the response	Optional
"_includeTotal"	Boolean	Includes the total number of files in the response	Optional

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

Parameter	Type	Description	Required
parent_id	String	Pass the file's id.	Required

Query

Parameter	Type	Description	Required
_namespaces	Array of String	Fetch 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
_ids	String	To query by file id, pass an id or a comma separated string with up to 200 file ids.	Optional
_name	String	To query a name, pass a Regex value, such as geom*.2d or .*bimpk.	Optional
_tags	String	Add a tag or add multiple tags as a comma-separated string.	Optional
tagMode	String	Controls how multiple _tags values are combined. Accepted values: or (default) returns files that match any of the specified tags; and returns only files that match all of the specified tags. Omitting this parameter defaults to or behavior. Returns 400 for any other value.	Optional
_offset	Number	Set a response control option for offset.	Optional
_pageSize	Number	Set a response control option for offset. The default value is 25 and the maximum value is 200.	Optional
nsfilter	String	namespace context	Required

Response

Codes

Code	Description
200	Success
400	Bad 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

Field	Type	Description	Required
_pageSize	Number	The number of results per page
_list	Array of Object	An array of one or more folders that match your query.	Required
_nextVersion	Number
_namespaces	Array of String	An array of one or more namespaces that contain the file.	Required
_name	String	The file's name
_tipVersion	Number	The latest version of the file
_tipId	String	The latest file version's id
_type	String	The file's type
_irn	String	The 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	String	The file's id	Required
_status	String	The file's status	Required
_metadata	Object	An object that contains the file's metadata
_parents	Array of String	An 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

Parameter	Type	Description	Required
id	String	Pass the file's ID.	Optional

Response

Codes

Code	Description
200	Success
404	File 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

Field	Type	Description	Required
_nextVersion	Number
_namespaces	Array of String	An array of one or more namespaces that contain the file.	Required
_previews	Array of Object	An array of one or more preview objects.	Required
_name	String	The file's name.
_tipVersion	Number	The latest version of the file.
_type	String	The file's type.
_irn	String	The 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	Object	An object that contains the file's metadata.
_parents	Array of String	An 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

Parameter	Type	Description	Required
id	String	Pass the file's id.	Required

Body

Parameter	Type	Description	Required
_name	String	Pass the new file name with its file extension.	Required
_tags	Array of String	Update 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

Code	Description
200	Success
400	File 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

Field	Type	Description	Required
_nextVersion	Number
_namespaces	Array of String	An array of one or more namespaces that contain the file.	Required
_name	String	The file's name
_tipVersion	Number	The latest version of the file
_tipId	String	The latest file version's id
_type	String	The file's type
_irn	String	The 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	Object	An object that contains the file's metadata
_parents	Array of String	An array of one or more parent folders that contain the file.

Move File

This API call moves a file or folder to a different parent folder, or moves it to the root.

The file's own (explicit) permissions stay with the file after the move. Permissions inherited from the source folder no longer apply; permissions inherited from the target folder now apply. If the moved item is a folder, every descendant file and folder is updated so inherited permissions follow the new location.

Authorization

The caller must have:

Action	Resource	Notes
EDIT	the file being moved	Same check that gates PUT /files/{id}.
CREATE	the target folder	When moving to root, this is checked against filesvc:file:* in the file's namespaces, matching how root-level folder creation is authorized.

Endpoints

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

Parameters

Query

• nsfilter - namespace context (Required)

Path

Parameter	Type	Description	Required
id	String	The id of the file or folder being moved.	Required

Body

A JSON array containing the id of the target folder. To move to the root, pass an empty array.

Shape	Meaning
["<target-folder-id>"]	Move under the folder with that id.
[]	Move to the root.

At most one element is allowed. The element must be a valid UUID that resolves to an existing folder in a namespace the caller can read.

Code example — move under a folder

["e1d2c3b4-a5f6-7890-1234-567890abcdef"]

Code example — move to root

[]

Response

Codes

Code	Description
200	Success. Returns the updated file JSON.
400	Bad request — body is not a JSON array, contains more than one element, the parent id is not a valid UUID, the target is not a directory, the file is being moved into itself, or a folder is being moved into one of its own descendants.
403	Caller lacks EDIT on the file or CREATE on the target.
404	File or target folder not found in the caller's namespaces.

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",
  "_status": "UPLOAD_COMPLETED",
  "_metadata": {
    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",
    "_createdByName": "xxxxxxx",
    "_createdAt": 1530089625693,
    "_updatedByName": "xxxxxxx",
    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",
    "_updatedAt": 1530089625693
  },
  "_parents": [
    "e1d2c3b4-a5f6-7890-1234-567890abcdef"
  ]
}

When the file has been moved to the root, _parents is an empty array.

Body schema

Field	Type	Description	Required
_nextVersion	Number
_namespaces	Array of String	An array of one or more namespaces that contain the file.	Required
_name	String	The file's name.
_tipVersion	Number	The latest version of the file.
_tipId	String	The latest file version's id.
_type	String	The file's type.
_irn	String	The resource path. Concatenate 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	String	The file's id.	Required
_status	String	The file's status.
_metadata	Object	An object that contains the file's metadata.
_parents	Array of String	The file's new parent. Contains one folder id after a folder-targeted move, or is empty after a move-to-root.	Required

Permission behavior after a move

• Permissions explicitly granted on the file's IRN are unchanged.
• Permissions previously inherited from the source folder no longer apply.
• Permissions granted on the target folder now apply via inheritance.
• For folder moves, the same rules apply to every descendant — they pick up the target folder's inherited permissions and drop the source's.

Examples

# Move a file under a folder
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '["e1d2c3b4-a5f6-7890-1234-567890abcdef"]' \
  "https://<host>/filesvc/api/v1/files/7a4c2f8e-1b3d-4e5f-9a8c-6d2e1b3a4c5d/parents?nsfilter=<namespace>"

# Move a file to the root
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[]' \
  "https://<host>/filesvc/api/v1/files/7a4c2f8e-1b3d-4e5f-9a8c-6d2e1b3a4c5d/parents?nsfilter=<namespace>"

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

Parameter	Type	Description	Required
id	String	Pass the file's ID.	Required

Response

Codes

Code	Description
200	Success
400	Bad Request
404	File 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

Field	Type	Description	Required
_nextVersion	Number
_namespaces	Array of String	An array of one or more namespaces that contain the file.	Required
_name	String	The file's name
_tipVersion	Number	The latest version of the file
_tipId	String	The latest file version's ID
_type	String	The file's type
_irn	String	The 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	Object	An object that contains the file's metadata
_parents	Array of String	An 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

Parameter	Type	Description	Required
id	String	Pass the file's id.	Required

Query

Parameter	Type	Description	Required
width	Number	The preview width. Currently, the only supported value is 640.	Required
height	Number	The preview width. Currently, the only supported value is 480.	Required

Response

Codes

Code	Description
200	Success
400	Bad Request
404	File 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

Field	Type	Description	Required
_nextVersion	Number
_namespaces	Array of String	An array of one or more namespaces that contain the file.	Required
_name	String	The file's name
_tipVersion	Number	The latest version of the file
_previewUrl	String	The preview URL
_tipId	String	The latest file version's id
_type	String	The file's type
_irn	String	The 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	Object	An object that contains the file's metadata
_parents	Array of String	An 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

Parameter	Type	Description	Required
id	String	Pass the file's id.	Optional

Response

Codes

Code	Description
200	Success
404	File 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

Field	Type	Description	Required
_pageSize	Number	The number of results per page
_list	Array of Object	An array of one or more file versions	Required
_fileSize	Number	The file size in bytes
_id	String	The file version's ID	Required
_metadata	Object	An object that contains the file's metadata
_version	Number	The file version's version number
_fileId	Number	The file's ID
_offset	Number	Response control offset options	Required
_total	Number	The total number of files in the response
_includeTotal	Boolean	Includes 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

Parameter	Type	Description	Required
id	String	Pass the file's id.	Optional

Response

Codes

Code	Description
204	No Content
404	File 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

Code	Description
204	No Content
404	File Not Found