Skip to main content
Skip table of contents

Subject API

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 

CODE
GET - /data/subjects

Parameters:

format

Optional querystring parameter

  • 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
limit

Used to page the results returned.  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 insure it.  In later releases, the default behavior of this url could change.

offset

Used to page the results returned.  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

Response:

CODE
{
  "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 

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

Parameters:

{project-id}Required path parameter
format

Optional querystring parameter

  • 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
limit

Used to page the results returned.  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 insure it.  In later releases, the default behavior of this url could change.

offset

Used to page the results returned.  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

Response:

CODE
{
  "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.

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

Parameters

{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.

{project-id}Optional (but common) path parameter
format

Optional querystring parameter

  • 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.

Show Response Format
CODE
{
  "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.

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

Parameters

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

Response Codes

201Subject Created
403Forbidden (i.e. the logged-in user does not have permission to add data to this project)
422Unprocessable 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:

CODE
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.

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

Parameters

{project-id}Required path parameter
{subject-label}Required path parameter. To modify a subject, you must specify an existing subject label in this project
{params}Subject Data REST XML Path Shortcuts

Response Codes

200Subject Modified
403Forbidden (i.e. the logged-in user does not have permission to modify data to this project)
422Unprocessable 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:

CODE
XNAT_S00036


Share Subject And Its Experiments Into A New Project

CODE
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.

labelOptional 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

200OK
403Forbidden – User does not have permission to perform the requested operation
404Not Found – Project ID not recognized
409Conflict – 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.

CODE
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.

CODE
{
  "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.

CODE
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
removeFilesOptional 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

200Subject Deleted
403Forbidden (i.e. the logged-in user does not have permission to delete data in this project)
422Unprocessable Entity (i.e. the supplied project ID could not be resolved)

Response Format:
None

JavaScript errors detected

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

If this problem persists, please contact our support.