Uploading files via an 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. Firstly, API tokens allow people who are not workspace members to upload to the workspace. Secondly, 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.

Generate an upload token

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.

Upload drop down.png

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.

api_upload.png

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

copy_token-1.png

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.

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.

download_azcopy.png

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.

az_upload.gif

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.

Updated on September 1, 2023

Was this article helpful?