Skip to main content
Skip table of contents

XNAT Search API

Post A Search To The XNAT Search Engine

This REST endpoint assumes you have built a valid XML search. You can download the XML of any existing data table in XNAT and use that as a starting point, or you can build your own. See How to Query the XNAT Search Engine with REST API.

CODE 
POST - /data/search

Parameters:

format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)

  • html

  • json

  • csv

body

Required XML search definition. Can be included in the body, or in a supplied XML file

Response: A valid search will return a formatted search result, showing data that the user has permission to see.

You can also create a stored search out of a valid XML search. See Stored Search API

Get A List Of Available Data Elements

This REST endpoint displays a list of all installed data types in your XNAT, regardless of whether there is available data of that type. 

CODE 
GET - /data/search/elements

Parameters:

format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)

  • html

  • json

  • csv

Response:

Showing JSON formatted results. Note that the ELEMENT_NAME field corresponds with the XNAT xsiType for that data type.

CODE 
{
  "ResultSet": {
    "Result": [
      {
        "SINGULAR": "Project",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:projectData",
        "COUNT": "10",
        "PLURAL": "Projects"
      },
      {
        "SINGULAR": "Subject",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:subjectData",
        "COUNT": "39",
        "PLURAL": "Subjects"
      },
      {
        "SINGULAR": "MR Session",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:mrSessionData",
        "COUNT": "36",
        "PLURAL": "MR Sessions"
      },
      {
        "SINGULAR": "PET Session",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:petSessionData",
        "COUNT": "7",
        "PLURAL": "PET Sessions"
      },
      ...
    ],
    "title": "Data-Types"
  }
}


Get A List Of Queryable Fields For A Given Data Type

From the list of available elements, supply an xsiType to get a list of columns you can search on.

CODE 
GET - /data/search/elements/{xsiType}

Parameters

{xsiType}

Required path parameter.

format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)

  • html

  • json

  • csv

Response

Displaying JSON-formatted result for a search on /data/search/elements/xnat:subjectData

CODE 
{
  "ResultSet": {
    "Result": [
      {
        "SUMMARY": "xnat:subjectData\/meta\/insert_date",
        "SRC": "0",
        "FIELD_ID": "INSERT_DATE",
        "HEADER": "Inserted",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "date",
        "DESC": "Inserted"
      },
      {
        "SUMMARY": "xnat:subjectData\/meta\/insert_user\/login",
        "SRC": "0",
        "FIELD_ID": "INSERT_USER",
        "HEADER": "Creator",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Creator"
      },
      {
        "SUMMARY": "CASE xnat:demographicData\/gender WHEN 'male' THEN 'M' WHEN 'female' THEN 'F' ELSE 'U' END",
        "SRC": "0",
        "FIELD_ID": "GENDER_TEXT",
        "HEADER": "M\/F",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "M\/F"
      },
      {
        "SUMMARY": "CASE LOWER(xnat:demographicData\/handedness) WHEN 'left' THEN 'L' WHEN 'right' THEN 'R' WHEN 'ambidextrous' THEN 'A' WHEN 'r' THEN 'R' WHEN 'l' THEN 'L' WHEN 'a' THEN 'A' END",
        "SRC": "0",
        "FIELD_ID": "HANDEDNESS_TEXT",
        "HEADER": "Hand",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Hand"
      },
      {
        "SUMMARY": "CAST(FLOOR(COALESCE(xnat:demographicData\/yob,EXTRACT(YEAR FROM xnat:demographicData\/dob))) AS INTEGER)",
        "SRC": "0",
        "FIELD_ID": "DOB",
        "HEADER": "YOB",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "integer",
        "DESC": "YOB"
      },
      {
        "SUMMARY": "xnat:demographicData\/education",
        "SRC": "0",
        "FIELD_ID": "EDUC",
        "HEADER": "Education",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "integer",
        "DESC": "Education"
      },
      {
        "SUMMARY": "xnat:demographicData\/ses",
        "SRC": "0",
        "FIELD_ID": "SES",
        "HEADER": "Ses",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "integer",
        "DESC": "Ses"
      },
      {
        "SUMMARY": "xnat:subjectData\/investigator\/lastname",
        "SRC": "0",
        "FIELD_ID": "INVEST_CSV",
        "HEADER": "PI",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "PI"
      },
      {
        "SUMMARY": "SUB_PROJECTS.PROJECTS",
        "SRC": "0",
        "FIELD_ID": "PROJECTS",
        "HEADER": "Projects",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "All projects tied to a subject"
      },
      {
        "SUMMARY": "xnat:subjectData\/project",
        "SRC": "0",
        "FIELD_ID": "PROJECT",
        "HEADER": "Project",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Subject's primary project"
      },
      {
        "SUMMARY": "xnat:subjectData\/group",
        "SRC": "0",
        "FIELD_ID": "SUB_GROUP",
        "HEADER": "Group",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Group"
      },
      {
        "SUMMARY": "SUBJECT_IDS.ADDIDS",
        "SRC": "0",
        "FIELD_ID": "ADD_IDS",
        "HEADER": "Labels",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Labels"
      },
      {
        "SUMMARY": "xnat:demographicData\/race",
        "SRC": "0",
        "FIELD_ID": "RACE",
        "HEADER": "Race",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Race"
      },
      {
        "SUMMARY": "xnat:demographicData\/ethnicity",
        "SRC": "0",
        "FIELD_ID": "ETHNICITY",
        "HEADER": "Ethnicity",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Ethnicity"
      },
      {
        "SUMMARY": "xnat:mrSessionData\/LABEL",
        "SRC": "0",
        "FIELD_ID": "XNAT_COL_MRSESSIONDATALABEL",
        "HEADER": "LABEL",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "LABEL"
      },
      {
        "SUMMARY": "Label within the * project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=*",
        "HEADER": "*",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the * project."
      },
      {
        "SUMMARY": "Label within the BJC_Pat project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=BJC_Pat",
        "HEADER": "BJC_Pat",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the BJC_Pat project."
      },
      {
        "SUMMARY": "Label within the Behavior_DB project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=Behavior_DB",
        "HEADER": "Behavior_DB",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the Behavior_DB project."
      },
      {
        "SUMMARY": "Label within the Fruit_Struct project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=Fruit_Struct",
        "HEADER": "Fruit_Struct",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the Fruit_Struct project."
      },
      {
        "SUMMARY": "Label within the Nifti_Proc project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=Nifti_Proc",
        "HEADER": "Nifti_Proc",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the Nifti_Proc project."
      },
      {
        "SUMMARY": "Label within the QC_Review project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=QC_Review",
        "HEADER": "QC_Review",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the QC_Review project."
      },
      {
        "SUMMARY": "Label within the ResourceDemo project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=ResourceDemo",
        "HEADER": "ResourceDemo",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the ResourceDemo project."
      },
      {
        "SUMMARY": "Label within the UXE project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE",
        "HEADER": "UXE",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE project."
      },
      {
        "SUMMARY": "Label within the UXE_London project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE_London",
        "HEADER": "UXE_London",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE_London project."
      },
      {
        "SUMMARY": "Label within the UXE_NYC project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE_NYC",
        "HEADER": "UXE_NYC",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE_NYC project."
      },
      {
        "SUMMARY": "Label within the UXE_Seoul project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE_Seoul",
        "HEADER": "UXE_Seoul",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE_Seoul project."
      }
    ],
    "versions": {
      "DisplayVersions": {
        "element_name": "xnat:subjectData",
        "versions": [
          {
            "name": "brief",
            "orderBy": "SUBJECT_ID",
            "darkColor": "DEDEDE",
            "lightColor": "FFFFFF",
            "defaultSortOrder": "ASC",
            "fields": [
              {
                "id": "SUBJECT_LABEL",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "GENDER",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "EDUC",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "SES",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              }
            ]
          },
          {
            "name": "project_bundle",
            "orderBy": "SUBJECTID",
            "darkColor": "DEDEDE",
            "lightColor": "FFFFFF",
            "defaultSortOrder": "ASC",
            "fields": [
              {
                "id": "SUB_PROJECT_IDENTIFIER",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "GENDER_TEXT",
                "element_name": "xnat:subjectData",
                "header": "M\/F",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS_TEXT",
                "element_name": "xnat:subjectData",
                "header": "Hand",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "header": "YOB",
                "value": "null",
                "visible": "true"
              }
            ]
          },
          {
            "name": "listing",
            "orderBy": "SUBJECT_ID",
            "darkColor": "DEDEDE",
            "lightColor": "FFFFFF",
            "defaultSortOrder": "ASC",
            "fields": [
              {
                "id": "SUBJECT_LABEL",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "GENDER",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "EDUC",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "SES",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "MR_COUNT",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              }
            ]
          },
          {
            "name": "all",
            "fields": [
              {
                "id": "SUBJECT_ID",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SUBJECTID",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "INSERT_DATE",
                "element_name": "xnat:subjectData",
                "header": "Inserted",
                "type": "date",
                "visible": "true"
              },
              {
                "id": "INSERT_USER",
                "element_name": "xnat:subjectData",
                "header": "Creator",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "GENDER",
                "element_name": "xnat:subjectData",
                "header": "Gender",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "GENDER_TEXT",
                "element_name": "xnat:subjectData",
                "header": "M\/F",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS",
                "element_name": "xnat:subjectData",
                "header": "Hand",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS_TEXT",
                "element_name": "xnat:subjectData",
                "header": "Hand",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "header": "YOB",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "EDUC",
                "element_name": "xnat:subjectData",
                "header": "Education",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "SES",
                "element_name": "xnat:subjectData",
                "header": "Ses",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "MR_COUNT",
                "element_name": "xnat:subjectData",
                "header": "MR Count",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "INVEST_CSV",
                "element_name": "xnat:subjectData",
                "header": "PI",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "PROJECTS",
                "element_name": "xnat:subjectData",
                "header": "Projects",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "PROJECT",
                "element_name": "xnat:subjectData",
                "header": "Project",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SUB_GROUP",
                "element_name": "xnat:subjectData",
                "header": "Group",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SUBJECT_LABEL",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SHARED_LABEL",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "ADD_IDS",
                "element_name": "xnat:subjectData",
                "header": "Labels",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "RACE",
                "element_name": "xnat:subjectData",
                "header": "Race",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "ETHNICITY",
                "element_name": "xnat:subjectData",
                "header": "Ethnicity",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "XNAT_COL_MRSESSIONDATALABEL",
                "element_name": "xnat:subjectData",
                "header": "LABEL",
                "type": "string",
                "visible": "true"
              }
            ]
          }
        ]
      }
    },
    "element_name": "xnat:subjectData",
    "title": "Search Fields"
  }
}


Get A List Of Search Report Versions For A Data Type

In the Advanced Search UI, you will notice a set of options when joining two data types together, whether you want to join a "Brief" or "Detailed" view of the data. These are two defined search report versions for a given data type. There are also other defined versions that may be shown in various contexts. This REST endpoint returns a full list of those versions.

CODE 
GET - /data/search/elements/{xsiType}/versions

Parameters

{xsiType}

Required path parameter.

format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)

  • html

  • json

  • csv

Response:
Displays just the contents of the "versions" object in the xsiType search example listed above

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close