Note: Creating a file object of type file is a two-step process! After calling the /files/file endpoint to create the PENDING file object, you will need to upload the file itself (see below).

Request

To create a file, two body parameters are required - path and channelId.

path Provides the full path (including filename and file extension) where the file will be created. This is a / delimited string where each separated value represents a folder name. For example, when creating a file abc.txt in a folder Example, the path should be Example/abc.txt. In the root of the file channel, path should just be abc.txt. If any folders provided in the path do not already exist (such as the Example folder in this case), the call will fail with error code 400. Each folder must be created in an individual API call.
channelId Specifies the File Channel where the file will be created. Use the List File Channels API endpoint to determine the ID of the desired File Channel.

To create a folder, two body parameters are required - path and channelId.

path Provides the full path (including the folder name) where the file will be created. This should contain the folder name to be created and should include its full path. For example, to create a folder New Folder:
- In the root of the File Channel, path will be be New Folder
- Inside the existing folders Example/Subfolder, path will be Example/Subfolder/New Folder. If any folders provided in the path do not already exist, the call will fail with error code 400. Each folder must be created in an individual API call.
channelId Specifies the File Channel where the folder will be created. Use the List File Channels API endpoint to determine the ID of the desired File Channel.
clientPermissions (optional)

Defaults to read_write if not set. Set to read_only to limit client permissions for the folder.

Client Permission Functionality
read_write (default) Clients can view and modify the contents of the folder.
read_only Clients can view, but not modify the contents of the folder.

To create a link, parameters required are channelId, path and fileUrl.

path Provides the full path (including the name of the link) where the link will be created. For example, to create a link with name (i.e. label) Search Engine in an existing folder Test Folder, the path should be Test Folder/Search Engine.
linkUrl This contains the URL the link points to. Must be a valid URL format. e.g. google.com.
channelId Specifies the File Channel where the link will be created. Use the List File Channels API endpoint to determine the ID of the desired File Channel.

Example params to create a link:

{
  "path": "Test Folder/Search Engine",
  "linkUrl": "google.com",
  "channelId": "<file-channel-id>"
}

Response

On a successful API call, the metadata of the created file object is returned. For a folder or link, the creation process is complete.

When you create a file, upon creation it will be have a pending status and will not be visible in the web UI.

In order to complete the file creation, the file should be uploaded to theuploadUrl returned in the file metadata (example below). This uploadUrl will be valid for 15 minutes after file creation. After 15 minutes, a PUT request made to the uploadUrl will receive a 401 error.

To upload the file, a PUT request can be made to the uploadUrl with the contents of the file. When this is completed successfully, the file will be visible in the web UI and the file will have status = completed.

Uploading the File

Once you receive the uploadUrl, a file can be uploaded via a PUT request to the uploadUrl (no authentication required).

Example request to upload the file: curl -T file.txt -X PUT -L "https://copilot-user-files.s3.amazonaws.com/protected/us-…"

200200

400400

403403