This documentation is for XNAT versions 1.6.0 - 1.6.5. You can find the latest documentation for XNAT 1.7 at

Skip to end of metadata
Go to start of metadata

The REST API is currently accessible on XNAT Central, It is advised that you become familiar with the XNAT web application before attempting to use the REST API.

All restful services require a valid user account. This can either be specified via the HTTP Authorization property (using Basic Authorization) or can be performed in an existing Server session (using the JSESSION_ID cookie). As a shortcut, you can use the XNATRestClient to execute REST interactions from a command prompt: (from XNAT 1.4)

A quick is tutorial available at the bottom.

Using 'format' query string parameter to tailor GET results

When querying a resource (GET) which returns a list of items (projects, subjects, experiments, etc), you can use a query string variable 'format=html' to specify the return type of the result. If you are using a REST compliant client, you can also do this using the 'Accept' HTTP header. However, the 'format' tag can override the Accept header, and is especially useful in browsers.

There are currently 4 supported list types: html, json, xml or csv. Specifying any of these values with the format tag, will return a result of that type.

EXAMPLE, log into
Enter the url: Now, try the

When querying indvidual resources, the xnat xml document will be returned (except when referencing uploaded files).

Using POST or PUT to create xml resources

Creating projects, subjects, experiments, scans, reconstructions and assessments is simple using the REST API. Simply perform a POST or PUT to the relevant API, and your resource will be generated.

You can use several routes to create a resource via the REST API.

  • POST or PUT an xml document to the relevant URI. This allows you to easily upload chunks of xml documents or an entire document. The xml should be written directly to the body of the HTTP message (not as a form parameter).
  • POST or PUT an empty HTTP message to the relevant URI. If it is obvious from the URI, what you are creating, then posting an empty document is sufficient to create the item. You can configure additional parameters of the item by adding xml path parameters to the query string. If the type of document to create for the resource is not obvious from the URI (experiments), then you'll need to include at least one xml path parameter, so that the type can be derived.
  • You can use the XNATRestClient to perform your PUT or POST.

Get a list of the subjects in a project:

XNATRestClient -host -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects?format=csv"

Create a subject:

XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000"

This will create an empty subject within your project.

To customize the demographics of the subject you can either add query string parameters or submit an XNAT xml document.

Query String

You can modify your entry via the query string by adding xml path parameters to identify the entries you want to edit. You can identify the xml path by review the xnat.xsd.

To modify the gender and handedness of this subject, I'll append the following paths separated by a &. Keep in mind that the querystring parameters must be seperated from the actual URI by a ?.

xnat:subjectData/demographics@xsi:type=xnat.demographicData/gender = male
xnat:subjectData/demographics@xsi:type=xnat.demographicData/handedness = left
XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000?xnat:subjectData/demographics@xsi:type=xnat.demographicData/gender=male&xnat:subjectData/demographics@xsi:type=xnat.demographicData/handedness=left"

For your convenience, a few parameters have been added as shortcuts. The abbreviated term can be substituted in the querystring for the full XML PATH. The list of available shortcuts is here.

XML File

Instead of specifying each field in the query string, you can build an xml file describing your subject. This can be uploaded with your PUT to set the details of the subject.

XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000" - local ./YOURTEST_subject.xml
<xnat:Subject ID="" project="JUNIT1" group="control" label="1" src="12"  xmlns:xnat="" xmlns:xsi="">
    <xnat:demographics xsi:type="xnat:demographicData">




Using PUT to modify xml resources

Similar to create resources, you can modify existing resources using the HTTP PUT method on the relevant URI. You can use either a query string xml path variable to specify your modification, or a full xml file.

Notice that, by default, submitting your PUT command will not delete content which is absent from your submitted message. This allows you to submit 'partial' xml documents. If you want to delete the information which is not contained in the document, add the query parameter 'allowDataDeletion=true'.

Using DELETE to remove xml resources

Similarly to creating and modifying, you can use delete existing resources using the HTTP DELETE method on the relevant URI.

To delete a subject

XNATRestClient -host -u USERNAME -p PASSWORD -m DELETE -remote "/data/archive/projects/YOURTEST/subjects/1000"

By default, any files which have been uploaded for the entry, will not be deleted from the file system. To force the deletion of these files include the removeFiles attribute as a query string parameter.

XNATRestClient -host -u USERNAME -p PASSWORD -m DELETE -remote "/data/archive/projects/YOURTEST/subjects/1000?removeFiles=true"

Uploading files

Files can be uploaded at any of the following levels:









reconstructed image




To upload a file, you will need to specify the pertinent URI above and then add the file name. The file name can include a relative directory structure.

So if I have three files which I want to attach to a scan, I could use the following XNATRestClient commands:

./file1.img = /data/archive/projects/PROJECT_ID/subjects/SUBJECT_ID/experiments/EXPT_ID/scans/SCAN_ID/files/file1.img
./subfolder/file2.img = /data/archive/projects/PROJECT_ID/subjects/SUBJECT_ID/experiments/EXPT_ID/scans/SCAN_ID/files/subfolder/file2.img
./file3.img = /data/archive/projects/PROJECT_ID/subjects/SUBJECT_ID/experiments/EXPT_ID/scans/SCAN_ID/files/file3.img

I could upload these files using the following commands:

XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/file1.img" - local ./file1.img

XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/subfolder/file2.img" - local ./subfolder/file2.img

XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/file3/img" - local ./file3.img

NOTE: If you are using a different utility to upload your files to the REST API, the default expectation of XNAT is that the files will be posted as part of a Multi-Part Form data (similar to a post from within an HTML application). If your tool writes the contents of the file directly into the message body, use the ?inbody=true parameter to force XNAT to parse the contents of the body as the file itself. Using this option requires that you specify what your file should be called in the URI.

Grouping files together

To group files together you will need to define a resource, which you can map multiple files to. Instead of uploading a file to a specific resource uri (URI/files) you can define a resource first. A resource can contain one to many files. This especially useful in uploading file formats which contain multiple files (header and image) or collections of files which you want to be bundled together to represent a single resource.

As an example, if you want to upload an analyze reconstruction you would first create a resource for the reconstruction, then upload files to that resource.

XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE"
XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files" - local ./file1.hdr
XNATRestClient -host -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files" - local ./file1.img

These files would then be retrievable:

XNATRestClient -host -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files/file1.hdr"
XNATRestClient -host -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files/file1.img"

Querying files

You can request a list of files for a given resource using the GET method on the above URIs. To get the list of files for the scan images I uploaded previously I could use:

XNATRestClient -host -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files"

This would return a list of the three files I previously uploaded.

I could then retrieve each file the URIs specified in the listing OR the URI I used to insert the file originally.

XNATRestClient -host -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/file1.img" -local ./downloads/file1.img


Quick Tutorials

Downloading Files via XNAT REST API

Create Subjects with XNAT REST API

Upload Files with REST API (Quick Tutorial)

Access Search Results with REST API (Quick Tutorial)

Please email us with additional questions:

Quick Index

  • No labels

1 Comment

  1. A note: The example REST queries in this documentation were broken in several cases, due to a text conversion error when migrating this content from Wikispaces to Confluence. "" was mistakenly converted to " ( -)"

    Please report any bugs to if you find more instances of code like this. Thanks!