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.


id string
The unique identifier for this item.

createdAt string
The date this item was created in RFC3339 format.

object string
The object type of this resource. 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.

path string
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.

ObjectWhat the last separated value represents
folderThe 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.
fileThe name of the file including the file extension.
linkThe name of the link (i.e. the label of the link in the UI).

linkUrl string
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 string
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 number
Describes the size of the file, in bytes. This field is only present for file objects when performing Retrieve a File.


Deprecation note

We are deprecating the nested fields object and have promoted all of the properties previously contained within the fields object to top-level properties. For backwards compatibility, you may still see the nested fields object in responses and examples.

    "channelId": "us-east-1_Gz7TRlAaM/7787061b-21d6-4742-b38d-319f3d18831b/none",
    "createdAt": "2024-02-29T22:34:48.044346124Z",
    "creatorId": "dc0f1749-7d01-48b7-bd80-fcbfce835642",
    "id": "9640718b-e291-4c93-8366-989ae26f58c9",
    "linkUrl": "",
    "name": "Example Folder",
    "object": "folder",
    "path": "Example Folder"
    "channelId": "b1VRvR-zM/c3b39b06-4a7c-4e66-92e3-35201c5f4542",
    "createdAt": "2023-12-01T18:57:50.519785029Z",
    "creatorId": "335775a7-9115-449e-8578-45d798a1c77e",
    "downloadUrl": "",
    "id": "91c4ed75-c903-4ef2-b087-a0c0cfc67563",
    "linkUrl": "",
    "name": "ExampleFile.docx",
    "object": "file",
    "path": "Welcome Letters/ExampleFile.docx",
    "size": 341141,
    "status": "complete"
    "channelId": "us-east-1_Gz7TRlAaM/7787061b-21d6-4742-b38d-319f3d18831b/none",
    "createdAt": "2024-02-29T22:34:39.549178548Z",
    "creatorId": "dc0f1749-7d01-48b7-bd80-fcbfce835642",
    "id": "9fb39008-6f3b-4f2e-9c8e-f4d5daf4c49a",
    "linkUrl": "",
    "name": "Example Link",
    "object": "link",
    "path": "Example Link"