This resource represents a file object. A file object is a file, folder, or link shared in the Files App of your portal, with the type specified by the object property. Every file object belongs to a File Channel. This API resource describes the metadata of the file object.

To upload or download the contents of a file (as opposed to link or folder), you need to make two API calls. Details are specified in the Create a File and Retrieve a File pages.

Properties

This resources uses all common resource properties. The object property is used to indicate the type of this file resource.

object string
The file resource can represent either a file, link, or folder.

createdBy string
The ID of the user that created this item.

channelId string
The ID of the channel this file is assigned to.

downloadUrl string
A URL that can be used to download file objects. Field does not appear for folder and link objects. Expires after 15 minutes.

fields map
The metadata properties associated with a file object. Some of the keys in the map described below may not be present depending on value of the object property, as explained below.

  • path: The relative location from the channel root for this object. This is a / delimited string where each separated value represents a folder name, until the last value which represents the name of this file resource.
    • When the object is a folder, the last separated value represents the name of the folder. In the Example Folder Object below, the name of the folder is Test Folder and it is inside another folder named Example.
    • When the object is a file, the last separated value represents the name of the file including the file extension.
    • When the object is a link, the last separated value represents the name of the link (i.e. the label of the link in the UI).
  • linkUrl: When the file object is type link, this will be set to the URL the link points to. Otherwise this will be an empty string.
  • status: When the file object is type file, this can be either pending or completed. This represents the current state of a file being created via the API. If the status is pending, the file has been created via the API but not yet uploaded. Once the file is uploaded, the status will be completed. This field is only present for file objects.
  • size: Describes the size of the file, in bytes. This field is only present for file objects.
{
  "id": "fbd5a90b-5216-4230-bcd2-0d6a746aeb65",
  "object": "folder",
  "createdBy": "1dbb3e36-af70-4f41-89e6-6ddf9e2c62b5",
  "createdAt": "2022-08-07T15:11:13.549092588Z",
  "updatedAt": "2022-08-07T15:11:13.549092588Z",
  "channelId": "us-east-1_eq0ubI3tM/c6e79bda-08b0-4654-9d8b-23a4b5ff6e52",
  "fields": {
    "name": "Test Folder",
    "path": "Example/Test Folder",
    "linkUrl": ""
  }
}
{
  "id": "79d08b61-626a-4587-9e2c-b2ab01184a99",
  "object": "file",
  "createdBy": "1dbb3e36-af70-4f41-89e6-6ddf9e2c62b5",
  "createdAt": "2023-03-21T14:22:53.150948433Z",
  "updatedAt": "2023-03-21T14:22:53.150948433Z",
  "channelId": "us-east-1_eq0ubI3tM/c6e79bda-08b0-4654-9d8b-23a4b5ff6e52",
  "fields": {
    "name": "Screenshot 2022-08-02 at 16.32.54.png",
    "path": "Example/Test Folder/Screenshot 2022-08-02 at 16.32.54.png",
    "status": "complete",
    "size": 145777,
    "linkUrl": ""
  }
}
{
  "id": "79d08b61-626a-4587-9e2c-b2ab01184a99",
  "object": "link",
  "createdBy": "1dbb3e36-af70-4f41-89e6-6ddf9e2c62b5",
  "createdAt": "2023-03-21T14:22:53.150948433Z",
  "updatedAt": "2023-03-21T14:22:53.150948433Z",
  "channelId": "us-east-1_eq0ubI3tM/c6e79bda-08b0-4654-9d8b-23a4b5ff6e52",
  "fields": {
    "name": "Reference Documentation",
    "path": "Example/Test Folder/Reference Documentation",
    "linkUrl": "https://example.com"
  }
}