Skip to main content
Skip table of contents


The XNATRestClient is deprecated. You should use XnatDataClient instead for on-going and future development.

XNATRestClient is a Java command-line tool that provides an easy way to script calls to the XNAT REST API. In many ways, XNATRestClient is similar to curl, although the syntax and usage is somewhat different. This tool is provided for platforms where curl may not be installed by default.e


XNATRestClient is provided as a bash shell script and a Windows batch file (where it's named XNATRestClient.bat) and is located in the bin folder of your xnat_builder. To configure XNATRestClient to work properly, all you should need to do is add that bin folder to your path variable or specify the path explicitly when you invoke the command.


XNATRestClient has the following parameters:


-u usernameThe XNAT system username to be used when validating your session.
-p passwordThe password to be used when validating your session.
-user_session sessionIdThis replaces the -u and -p parameters. You can generate the session ID by calling the REST API URL /data/JSESSION.
-host urlThis is the URL for your XNAT server instance. Note that this includes any application context folder, i.e. /xnat.
-ts storeIndicates the location of your trusted certificates store.
-tsPass passThe password for your trusted certificates store.
-proxy urlThe address of your proxy server, if necessary.
-proxyPort portThe port to use on your proxy server (the default is port 80).
-hPrint help.
-quietSuppresses output messages.
-remote pathThe remote path to access on your XNAT server. This is relative to the value you specified for the -host parameter.
-local fileA local file containing data to upload to the REST resource specified by the -host and -remote parameters.
-m methodThe HTTP method to use when accessing the specified REST resource.

Common Issues

URL Encoding

XNATRestClient does not encode parameters for URL submission in the value specified in the -remote parameter. This can lead to unexpected results when the characters in a REST resource are significant in HTTP transactions. For example, a search specifier might specify a search for data objects with the XSI type of xnat:demographicsData. That specifier looks like this:


In this case, the parameter key is intended to be xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/gender and the parameter value is intended to be male. But because the key actually already has the equal character ('='), the key actually is interpreted to be xnat:subjectData/demographics[@xsi:type. Because of this, you'll need to encode significant characters, including the equal character, ampersands ('&') and question marks ('?') within your parameter keys and values. 

For example, the above specifier would become:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.