Uploading a file

To upload a file using the File API, the following steps are involved:

• Register your intent to upload a file, obtaining a blob storage URL.
• Upload your file to the blob storage URL.
• Poll the "get file" endpoint until the file is available.

A file can be uploaded either by path (folder and file name), or by UUID. See the API schema for more information on these endpoints. The examples here include both.

Get blob storage URL

PUT https://<service_host>/file/v2/orgs/<org_id>/workspaces/<workspace_id>/files/<file_id>

The first step when uploading a file using the File API is to register your intent to upload, and obtain a pre-signed blob storage URL. This is done to support large, multipart file uploads that would otherwise not be able to be uploaded in a single request.

import requests

file_path = "path_to_my_file.txt"
url = f"https://<service_host>/file/v2/orgs/{org_uuid}/workspaces/{workspace_uuid}/files/path/{file_path}"

upload_link_response = requests.put(url, headers={ "Authorization": "Bearer [yourtokenhere]" }).json()
print(upload_link_response)

An example response will include the new file_id, version_id, and the pre-signed upload URL to upload your file contents:

{
    "file_id": "13771ee0-c399-4b52-8ccb-ed3a114dcc0d",
    "version_id": 1701303755570785597,
    "upload": "https://<service_host>/file/efda2f60-a80b-45c0-a484-4001bfe7b3cb/956f86b3-384d-412f-913f-c0bdfac96108/13771ee0-c399-4b52-8ccb-ed3a114dcc0d/1701303755570785597?se=2023-11-30T00%3A52%3A35Z&sp=wt&sv=2023-08-03&sr=b&rscd=attachment%3B+filename%2A%3DUTF-8%27%271701303755570785597&skoid=e5e6494a-6b97-403b-8dfd-30d5b24d8ca7&sktid=067e9632-ea4c-4ed9-9e6d-e294956e284b&skt=2023-11-30T00%3A22%3A35Z&ske=2023-11-30T01%3A22%3A35Z&sks=b&skv=2023-08-03&sig=6d3hgI3JTZMu%2FVKI88M3ndpHJhwL5ijQSWUT9NTR5%2Fg%3D"
}

Upload the data blob

Once the blob storage upload URL has been obtained, you can upload your file contents to it. The pre-signed URL is valid for 30 minutes.

upload_file = {f"{upload_link_response['file_id']}": open(file_path, "rb")}
upload_response = requests.put(
    upload_link_response["upload"],
    files=upload_file,
    headers={"x-ms-blob-type": "BlockBlob"},
)

Poll until the file is ready

GET https://<service_host>/file/v2/orgs/<org_id>/workspaces/<workspace_id>/files/path/<file_path>

Even though you may be uploading your file synchronously in the same script, and the upload has completed, the file may not be ready to use yet. In order to ensure it is ready before you continue, you can poll the "get file" API to find out the progress of the upload.

import time

url = f"https://<service_host>/file/v2/orgs/{org_uuid}/workspaces/{workspace_uuid}/files/path/{file_path}"
i = 1
limit = 10  # To prevent an infinite loop

while True:
    file = requests.get(url, headers={ "Authorization": "Bearer [yourtokenhere]" })
    result = file.json()
    # Is the file ready yet?
    if result:
        break
    # Have we reached our recursion limit?
    i += 1
    if i > limit:
        break
    # Wait a bit until trying again
    time.sleep(1)

Once your requests have completed, you will have a file response in the result variable:

{
    "name": "path_to_my_file.txt",
    "path": "/",
    "file_id": "13771ee0-c399-4b52-8ccb-ed3a114dcc0d",
    "version_id": 1701303763589905104,
    "size": 191,
    "created_at": "2024-07-04T00:22:46",
    "etag": "\"0x8DBF13A7A4ECB68\"",
    "author": {
        "id": "fb224065-b853-4daa-8332-60cf41cd5231",
        "name": "Leslie Lawless",
        "email": "leslie.lawless@example.com"
    },
    "download": "https://<service_host>/file/efda2f60-a80b-45c0-a484-4001bfe7b3cb/956f86b3-384d-412f-913f-c0bdfac96108/13771ee0-c399-4b52-8ccb-ed3a114dcc0d/1701303763589905104?se=2023-11-30T00%3A53%3A30Z&sp=rt&sv=2023-08-03&sr=b&rscd=attachment%3B+filename%2A%3DUTF-8%27%27path_to_file.txt&skoid=e5e6494a-6b97-403b-8dfd-30d5b24d8ca7&sktid=067e9632-ea4c-4ed9-9e6d-e294956e284b&skt=2023-11-30T00%3A22%3A35Z&ske=2023-11-30T01%3A22%3A35Z&sks=b&skv=2023-08-03&sig=9dLrqxcxsdEUYvgRWe1ydaRYIyTtBcoDEy7a4BoJDFY%3D",
    "self": "https://<service_host>/file/v2/orgs/efda2f60-a80b-45c0-a484-4001bfe7b3cb/workspaces/956f86b3-384d-412f-913f-c0bdfac96108/files/13771ee0-c399-4b52-8ccb-ed3a114dcc0d?version_id=1701303763589905104&include_versions=false"
}

!!! info "Pro-tip" If you're uploading a new version of an existing file, you can compare the version_id you receive in the first and last steps of this example to determine whether the new version has finished uploading.

Uploading a new file version

PUT https://<service_host>/file/v2/orgs/<org_id>/workspaces/<workspace_id>/files/<file_id>

If you want to upload a new version of a file, you can use the "update file by ID" API to retrieve a new pre-signed blob storage URL. The steps are the same as the examples above, however you should ensure you are comparing the initial version_id against each new request while polling to ensure you can detect when the new version is available.