XNAT API Documentation
XNAT API Documentation
Breadcrumbs

Subject API

Related

These API query the user's permissions with the XNAT security model and only return results that the user has permission to access, or to modify.


Get All Subjects In XNAT

This API call is essentially a search of a single data type, and is formatted to return a table of results.

Note: You can set this API to return paged results via the "limit" and "offset" settings. See Paging RESTful tables 

GET - /data/subjects

Parameters:

Parameter

Description

Format

format

Optional querystring parameter

String:

  • json (default)

  • xml

  • html

  • csv

columns

Optional querystring parameter, specifying specific columns via Subject Data REST XML Path Shortcuts.

Always included:

  • ID

  • URI

Included by default if no columns are specified:

  • insert_date

  • insert_user

  • project

  • label

String of comma-separated values

limit

Optional querystring parameter: Returns a single page of paginated results. This setting chooses the number of rows to return.

Note: Adding 'limit=*' will force all results to be returned.  If you are encoding a reference to this API in a script and expect all results to be returned, add this parameter to ensure it.  In later releases, the default behavior of this url could change.

Integer

offset

Optional querystring parameter: Returns a single page of paginated results. This setting controls the number of rows to skip.  With a limit of 100, then page 1 would be offset=0, page 2 would be offset=100, page 3 would be offset 200, etc

Integer

Response:

{
  "ResultSet": {
    "Result": [
      {
        "insert_date": "datetime",
        "project": "string",
        "ID": "string",
        "label": "string",
        "insert_user": "string",
        "URI": "string"
      },
      ...
    ],
    "totalRecords": "integer"
  }
}


Get All Subjects In A Project

This API call is essentially a search of a single data type, and is formatted to return a table of results.

Note: You can set this API to return paged results via the "limit" and "offset" settings. See Paging RESTful tables 

GET - /data/projects/{project-id}/subjects

Parameters:

Parameter

Description

Format

{project-id}

Required path parameter

String

format

Optional querystring parameter

String

  • json (default)

  • xml

  • html

  • csv

columns

Optional querystring parameter, specifying specific columns via Subject Data REST XML Path Shortcuts.

Always included:

  • ID

  • URI

Included by default if no columns are specified:

  • insert_date

  • insert_user

  • project

  • label

String of comma-separated values

limit

Optional querystring parameter: Returns a single page of paginated results. This setting chooses the number of rows to return.

Note: Adding 'limit=*' will force all results to be returned.  If you are encoding a reference to this API in a script and expect all results to be returned, add this parameter to ensure it.  In later releases, the default behavior of this url could change.

Integer

offset

Optional querystring parameter: Returns a single page of paginated results. This setting controls the number of rows to skip.  With a limit of 100, then page 1 would be offset=0, page 2 would be offset=100, page 3 would be offset 200, etc

Integer

Response: 

{
  "ResultSet": {
    "Result": [
      {
        "insert_date": "datetime",
        "project": "string",
        "ID": "string",
        "label": "string",
        "insert_user": "string",
        "URI": "string"
      },
      ...
    ],
    "totalRecords": "integer"
  }
}


Get A Single Subject Record

This API call returns a much more detailed subject record, including child data that is owned by the subject.

GET - /data/subjects/{subject-id}
GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}

Parameters

Parameter

Description

Format

{subject-id} or {subject-label}

Required path parameter.

Note that subject-label is a project-specific field and can only be used if project-id is also specified.

String

{project-id}

Optional (but common) path parameter

String

format

Optional querystring parameter

String

  • html (default)

  • xml

  • json

  • csv

Response

The response object contains a representation of the subject's metadata, its sharing attributes, as well as a representation of the subject's experiments and those experiments' children.

{
  "items": [
    {
      "children": [
        {
          "field": "demographics",
          "items": [
            {
              "children": [],
              "meta": {
                "create_event_id": integer,
                "xsi:type": "xnat:demographicData",
                "isHistory": false,
                "start_date": "UTC datetime"
              },
              "data_fields": {
                "education": integer,
                "xnat_abstractDemographicData_id": integer,
                "gender": "string",
                "xnat_abstractdemographicdata_id": integer,
                "handedness": "string",
                "yob": integer
              }
            }
          ]
        },
        {
          "field": "sharing/share",
          "items": [
            {
              "children": [],
              "meta": {
                "create_event_id": integer,
                "xsi:type": "xnat:projectParticipant",
                "isHistory": false,
                "start_date": "UTC datetime"
              },
              "data_fields": {
                "subject_ID": "string",
                "project": "string",
                "label": "string",
                "xnat_projectParticipant_id": integer
              }
            }
          ]
        },
        {
          "field": "experiments/experiment",
          "items": [
            {
              "children": [
                {
                  "field": "sharing/share",
                  "items": [ ... ]
                },
                {
                  "field": "scans/scan",
                  "items": [ ... ]
                }
              ]
            }
          ]
        }
      ],
      "data_fields": {
        "ID": "string",
        "label": "string",
        "project": "string"
      },
      "meta": {
          "create_event_id": integer,
          "xsi:type": "xnat:projectParticipant",
          "isHistory": false,
          "start_date": "UTC datetime"
      }
    }
  ]
}


Create A New Subject Record

Use this call to create a new subject record in a project, where the subject label you intend to create is not already in use.

PUT - /data/projects/{project-id}/subjects/{subject-label}

Parameters

Parameter

Description

Format

{project-id}

Required path parameter

String

{subject-label}

Required path parameter. When creating a new subject, this is the label that will appear in search tables.

String

Response Codes

201

Subject Created

403

Forbidden (i.e. the logged-in user does not have permission to add data to this project)

422

Unprocessable Entity (i.e. the supplied project ID could not be resolved)

Response Format
The response from a successful subject creation is a simple string displaying the new subject's XNAT accession ID. For example:

XNAT_S00036


Modify A Subject Record

You can set values for an existing subject record by appending XML path shortcuts as querystring parameters to the end of the PUT request.

PUT - /data/projects/{project-id}/subjects/{subject-label}?{params}

Parameters

Parameter

Description

Format

{project-id}

Required path parameter

String

{subject-label}

Required path parameter. To modify a subject, you must specify an existing subject label in this project

String

{params}

Subject Data REST XML Path Shortcuts

Querystring

Response Codes

200

Subject Modified

403

Forbidden (i.e. the logged-in user does not have permission to modify data to this project)

422

Unprocessable Entity (i.e. the supplied project ID could not be resolved)

Response Format
The response from a successful subject record modification is a simple string displaying the subject's XNAT accession ID. For example:

XNAT_S00036



Share Subject And Its Experiments Into A New Project 

PUT - /data/projects/{original-project-id}/subjects/{subject-id | subject-label}/projects/{shared-project-id}

Parameters

{original-project-id}

Required path parameter. Specify the ID of the project that owns a given subject.

{subject-id} or {subject-label}

Required path parameter.

{shared-project-id}

Required path parameter. Specify the ID of the project that you intend a subject to be shared into.

Logged-in user must have ownership permissions in the shared project.

label

Optional querystring parameter. Specify a new label for this subject that will be used in the shared project, if desired.

primary

Optional querystring parameter.

  • If set to "true", you are changing the primary ownership of the subject from the original project to the new project.

Logged-in user must have ownership permissions in both projects to change the primary ownership.

format

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

  • html (default)

  • json

  • xml

  • csv

Response Codes

200

OK

403

Forbidden – User does not have permission to perform the requested operation

404

Not Found – Project ID not recognized

409

Conflict – Attempting to write data into an XNAT object that already exists

Response Format
Returns the subject metadata from the original project


Get A List Of Shared Projects Associated With A Subject

This query will return a list of all projects associated with a subject. The root project ID in the URI can be either a project that owns the subject or a shared project.

GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}/projects

Parameters

{project-id}

Required path parameter

{subject-id} or {subject-label}

Required path parameter

format

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

  • html (default)

  • json

  • xml

  • csv

Response Format
Displaying JSON results. Note that the response does not specify which project owns a subject.

{
  "ResultSet": {
    "Result": [
      {
        "label": "string",
        "ID": "string",
        "Secondary_ID": "string",
        "Name": "string"
      },
      ...
    ]
  }
}



Delete (Or Unshare) A Subject Record

Performing this call in a project that owns a subject record will permanently delete the subject and its experiment data from your project and your XNAT archive.

Performing this call in a project that this subject has been shared into will simply delete the sharing relationship – no data will be deleted from your XNAT archive, it will simply be removed from this project.

DELETE - /data/projects/{project-id}/subjects/{subject-label}

Parameters

{project-id}

Required path parameter

{subject-label}

Required path parameter. To delete a subject, you must specify an existing subject label in this project

removeFiles

Optional query param. Defaults to "false", which will leave files in the file system after deleting the experiment record in Postgres. When this param is set to "true", those files are permanently deleted. 

Response Codes

200

Subject Deleted

403

Forbidden (i.e. the logged-in user does not have permission to delete data in this project)

422

Unprocessable Entity (i.e. the supplied project ID could not be resolved)

Response Format:
None