Skip to main content
Skip table of contents

Image Scan Resource API

Get A Listing Of All Scan Resource Folders

For an image session, this only URI only returns resources stored with the experiment, not any resources stored at the scan or image assessor context. See Image Session Scans API and Image Assessor Resource API for details.

CODE
GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}/scans/{scan-id}/resources
GET - /data/experiments/{experiment-id}/scans/{scan-id}/resources

Parameters

{project-id}

Path parameter

{subject-id} or {subject-label}

Path parameter. Subject label is a project-specific field, and can only be used if a project is specified.

{experiment-id} or {experiment-label}

Path parameter. Experiment label is a project-specific field, and can only be used if a project is specified.

{scan-id}

Path parameter.

format

Optional querystring parameter. Specify the format of the returned response.

  • json (default)

  • html

  • xml

  • csv

sortBy

Optional querystring parameter: Sort the returned results by one or more parameters in the Result array. Multiple parameters can be provided, separated by commas.

Response

This call returns an array of resource descriptors, where the key values are "xnat_abstractresource_id" and "label", which can be used as a path parameter.

CODE
{
    "ResultSet": {
        "Result": [
            {
                "cat_desc": "string",
                "cat_id": "",
                "category": "resources",
                "content": "",
                "element_name": "xnat:resourceCatalog",
                "file_count": "integer",
                "file_size": "integer (bytes)",
                "format": "string",
                "label": "string {resource-label}",
                "tags": "string",
                "xnat_abstractresource_id": "integer {resource-id}"
            }
        ],
        "totalRecords": "integer",
        "title": "Resources"
    }
}

Get A Listing Of All Scan Resource Files

For an image session, this only URI only returns files stored with the experiment, not any files stored at the scan or image assessor context.

CODE
GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}/scans/{scan-id}/files
GET - /data/experiments/{experiment-id}/scans/{scan-id}/files

Parameters

{project-id}

Path parameter

{subject-id} or {subject-label}

Path parameter. Subject label is a project-specific field, and can only be used if a project is specified.

{experiment-id} or {experiment-label}

Path parameter. Experiment label is a project-specific field, and can only be used if a project is specified.

{scan-id}

Path parameter.

format

Optional querystring parameter. Specify the format of the returned response.

  • json (default)

  • html

  • xml

  • csv

sortBy

Optional querystring parameter: Sort the returned results by one or more parameters in the Result array. Multiple parameters can be provided, separated by commas.

Response

This call returns an array of file listings, where each has a unique URI path to the resource file.

CODE
{
    "ResultSet": {
        "Columns": [
            {
                "key": "URI",
                "serverRoot": ""
            }
        ],
        "Result": [
            {
                "cat_ID": "integer {resource-id}",
                "collection": "string {resource-label}",
                "file_content": "string",
                "file_format": "",
                "file_tags": "string",
                "digest": "hash",
                "Name": "string {filename}",
                "Size": "integer",
                "URI": "/data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-id}/files/{filename}"
            }
        ],
        "title": "Files"
    }
}

Get A Listing Of All Files For A Single Scan Resource

For an image session, this only URI only returns files stored with the experiment, not any files stored at the scan or image assessor context.

CODE
GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}/scans/{scan-id}/resources/{resource-label}/files
GET - /data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-label}/files

Parameters

{project-id}

Path parameter

{subject-id} or {subject-label}

Path parameter. Subject label is a project-specific field, and can only be used if a project is specified.

{experiment-id} or {experiment-label}

Path parameter. Experiment label is a project-specific field, and can only be used if a project is specified.

{scan-id}

Path parameter.

{resource-label}

Path parameter. Use the resource label as shown in a Manage Files interface, or in a query on resource. e.g. "DICOM" or "SNAPSHOTS"

format

Optional querystring parameter. Specify the format of the returned response.

  • json (default)

  • html

  • xml

  • csv

sortBy

Optional querystring parameter: Sort the returned results by one or more parameters in the Result array. Multiple parameters can be provided, separated by commas.

Response

This call returns an array of file listings, where each has a unique URI path to the resource file.

CODE
{
    "ResultSet": {
        "Columns": [
            {
                "key": "URI",
                "serverRoot": ""
            }
        ],
        "Result": [
            {
                "cat_ID": "integer {resource-id}",
                "collection": "string {resource-label}",
                "file_content": "string",
                "file_format": "",
                "file_tags": "string",
                "digest": "hash",
                "Name": "string {filename}",
                "Size": "integer",
                "URI": "/data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-id}/files/{filename}"
            }
        ],
        "title": "Files"
    }
}

Get The Contents Of An Experiment Resource File

This URI returns the raw contents of a resource file. If your client cannot parse this file, it will not provide a usable output. See How To Download Files via the XNAT REST API for help on downloading resources.

CODE
GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}/scans/{scan-id}/resources/{resource-id | resource-label}/files/{filename}
GET - /data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-id}/files/{filename}

Parameters

{project-id}

Path parameter

{subject-id} or {subject-label}

Path parameter. Subject label is a project-specific field, and can only be used if a project is specified.

{experiment-id} or {experiment-label}

Path parameter. Experiment label is a project-specific field, and can only be used if a project is specified.

{scan-id}

Path parameter.

{resource-id} or {resource-label}

Path parameter.

{filename}

Path parameter.

Response

Success (200) returns the file in its native format.

Create A New Experiment Resource Folder

Note: {resource-label} must be new and unique in this subject. Once created, resource descriptors cannot be modified. 

CODE
PUT - /data/projects/{project-id}/subjects/{subject-label}/experiments/{experiment-label}/scans/{scan-id}/resources/{resource-label}
PUT - /data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-label}

Parameters

{project-id}

Required path parameter

{subject-id} or {subject-label}

Required path parameter

{experiment-id} or {experiment-label}

Required path parameter

{scan-id}

Path parameter.

{resource-label}

Required path parameter. Specify the label of the resource that you want to create. XNAT will automatically assign an ID.

format

Optional querystring parameter. Specify a string format descriptor for this resource folder.

tags

Optional querystring parameter. Specify a comma-separated list of tags for this resource folder.

content

Optional querystring parameter. Specify a string description of the resource folder's content.

Response: none

Upload A New Experiment Resource File

Note: {filename} must be unique within this resource folder, otherwise the file will not be uploaded.

CODE
PUT - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}/scans/{scan-id}/resources/{resource-id | resource-label}/files/{filename}
PUT - /data/experiments/{experiment-id | experiment-label}/scans/{scan-id}/resources/{resource-id | resource-label}/files/{filename}

Parameters

{project-id}

Required path parameter

{subject-id} or {subject-label}

Required path parameter

{experiment-id} or {experiment-label}

Required path parameter

{scan-id}

Path parameter.

{resource-id} or {resource-label}

Required path parameter. If this resource collection is not already defined, it will be defined automatically by this call.

{filename}

Required path parameter. This will be the name of the file as it is stored in XNAT. It can be different from the original name of your uploaded file.

inbody=true

Optional querystring parameter. Use if including the file in the body of the request as opposed to part of a multi-part form data

file

Required body or form parameter.

format

Optional querystring parameter. Specify a string format descriptor for this resource folder.

content

Optional querystring parameter. Specify a string description of the resource folder's content.

Response Codes

200

OK - File Created


OK - Duplicates Existing File (File not created or updated)


OK - User does not have permission to upload files (File not created or updated)


Update An Existing Resource File

CODE
POST - /data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-id | resource-label}/files/{filename}?overwrite=true

Parameters

{experiment-id}

Required path parameter

{scan-id}

Path parameter.

{resource-id} or {resource-label}

Required path parameter.

{filename}

Required path parameter. This must match an existing file name as it is stored in XNAT.

overwrite=true

Required querystring parameter. This must be set to allow your new file to overwrite your existing one

file

Required body parameter

inbody=true

Optional querystring parameter. Use if including the file in the body of the request as opposed to part of a multi-part form data

Response Codes

200

OK


Delete An Experiment Resource Collection

This URI will also delete all files in the resource collection

CODE
DELETE - /data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-id | resource-label}

Parameters

{experiment-id} or {experiment-label}

Required path parameter

{scan-id}

Path parameter.

{resource-id} or {resource-label}

Required path parameter

Response Codes

200

OK

403

Forbidden

Delete An Experiment Resource File

CODE
DELETE - /data/experiments/{experiment-id}/scans/{scan-id}/resources/{resource-id | resource-label}/files/{filename}

Parameters

{experiment-id} or {experiment-label}

Required path parameter

{scan-id}

Path parameter.

{resource-id} or {resource-label}

Required path parameter

{filename}

Required path parameter

Response Codes

200

OK

403

Forbidden

JavaScript errors detected

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

If this problem persists, please contact our support.