AZ Copy Tutorial

Lean how to upload files using AZ Copy and the workspace API. 

As well as uploading files via the user interface, it is also possible to do so using an API.

There are a few reasons you may wish to do this.

  1. Firstly, API tokens allow you to upload files larger than 250GB (and less than 1TB).
  2. Secondly, people who are not workspace members to upload to the workspace.
  3. Third, the use of the API allows users to upload data programmatically. For example, perhaps you have a regular stream of data coming into your study and you want it to be automatically pushed on to your workspace.

Watch the demo video (which follows the steps below) to learn how to upload files using AZ Copy and the workspace API.

1. Generate an Upload Token

To use the API interface, a user first generates an API token, which is like a password that is used to authenticate your request to upload files to a workspace. This ensures that only valid and secure uploads are permitted within the workspace. 

First, go to the Upload dropdown menu and select Manage upload tokens. This will take you to a new tab showing existing tokens and a form to generate new ones.

Provide a reason for the token generation and select the validity period for your new token – the default is set to the maximum (30 days).

If you tick the 'Upload data to database' checkbox, uploaded CSV files and associated metadata will be used to create a dataset. If you do not check it, the files will be uploaded to your workspace Inbox.

Your new token will be listed as the first entry in the table. Use the Copy button to copy your token to your clipboard.

Be aware that once you close the tab you will not be able to copy the token anymore. Save the copied token if you wish to use it again.

2. Download AzCopy

To use the API, you will need to download AzCopy to your computer. You can add the AzCopy directory to your path, which allows you to use AzCopy from any directory on your system.

If you choose not to add the AzCopy directory to your path, you'll have to first navigate to the location of your AzCopy executable before using it in the command line.

3. Upload Your Files

To run AzCopy on your own machine, if you did not add it to your path, first navigate to the location where you have installed AzCopy and run the following command:

azcopy copy "/path/to/your/file" "token"

If you want to recursively copy data from a local directory, add the --recursive=true flag at the end.

Depending on whether you checked the 'Upload data to database' box, the files uploaded through an API will be found either in the Database tab or in the Inbox.