XNAT Tools

Client Tools

XNAT Desktop


Web Services

Web Services: XNAT Rest API

Web Services: Examples

[Edit Nav] ]

How to Upload Files with REST

Depending on the tool you are using to PUT files to the server, you may need to add an inbody=true query string parameter to force XNAT to treat the contents of your HTTP message as the actual file rather then as multi-part form data.


The XNAT team has some developed some simple java based tools which can be used as command prompt tools to access the REST API.


The XNATRestClient is built specifically to facilitate user interaction with the REST API from the command prompt. Uploading files with this tool should be straightforward. You use the -local variable to identify the local file you are uploading. You use the -remote variable to identify the location you are PUTinig the file to.
XNATRestClient -host http://central.xnat.org -u USER -p PASS -m PUT -remote "/REST/projects/PATH/TO/DESTINATION/files" -local ./file.txt


Most UNIX operating systems come pre-installed with 'Curl' which is a tool for transferring data to or from a server. Because XNAT Servers are secured, you will need to provide a username and password to access the api. Curl will post the file directly in the HTTP message body. As such, you will need to include the inbody=true variable to prevent XNAT from attempting to parse the contents.

curl -u USERNAME:PASSWORD http://central.xnat.org/REST/projects/PATH TO DESTINATION/?inbody=true (plus appropriate tags from the curl documentation).
For more information on using curl, please review its documentation.

Compressed file upload

The REST API supports the upload of compressed files that can be extracted on the server after successful upload. There are a few caveats:
  • The files cannot cross hierarchical concepts. I.E. You cannot include files for both scans and reconstructions in the same zip file.
  • The files cannot cross objects. I.E. You cannot include files for scan A and scan B. They must be within a single scan.
  • The files cannot cross catalogs. Within each object you can have multiple catalogs (collections) of files. The files in a zip can only go in a single catalog.

To use compressed uploads, you would use a similar structure to uploading a normal file. Any where that you can upload files via the REST API, you can use the ?extract option.

PUT http://central.xnat.org/REST/projects/X/subjects/X/experiments/X/scans/X/files/FILENAME.zip?extract=true

If you are including the zipped file as the body of the message, you should also use the ?inbody=true attribute. Otherwise XNAT will expect MULTI-PART form data.

The file name must include the proper file extension. '.zip' for zipped data. '.gz' for a gzipped file. '.tar.gz' for a tar gz. This will be used to properly extract the file.

If the extract=true is missing, then the file will be uploaded and stored as is (not extracted).