Endpoint Details

This page provides details on each of the IDC API endpoints.

get

Get links to the IDC API Swagger UI and IDC documentation

Responses

200

API Description and link to SwaggerUI interface.

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/about

HTTPcURLJavaScriptPython

GET /about HTTP/1.1
Host: 
Accept: */*

{
  "message": "text",
  "documentation": "text",
  "code": 1
}

get

Returns a list of IDC data versions and activation dates

Responses

200

A list of IDC data versions and metadata

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/versions

HTTPcURLJavaScriptPython

GET /versions HTTP/1.1
Host: 
Accept: */*

{
  "idc_data_versions": [
    {
      "idc_data_version": "text",
      "date_active": "text",
      "active": "text"
    }
  ],
  "code": 1
}

get

Returns a list of collections, and associated metadata, in the current IDC data version.

Responses

200

A list of collections

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/collections

HTTPcURLJavaScriptPython

GET /collections HTTP/1.1
Host: 
Accept: */*

{
  "collections": [
    {
      "collection_id": "text",
      "cancer_type": "text",
      "date_updated": "text",
      "description": "text",
      "source_doi": "text",
      "source_url": "text",
      "image_types": "text",
      "location": "text",
      "species": "text",
      "subject_count": 1,
      "supporting_data": "text"
    }
  ],
  "code": 1
}

get

Returns a list of the analysis results, and associated metadata, in the current IDC data version

Responses

200

A list of analysis results

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/analysis_results

HTTPcURLJavaScriptPython

GET /analysis_results HTTP/1.1
Host: 
Accept: */*

{
  "analysisResults": [
    {
      "analysis_result_id": "text",
      "analysisArtifacts": "text",
      "cancer_type": "text",
      "collections": "text",
      "date_updated": "text",
      "description": "text",
      "doi": "text",
      "location": "text",
      "subjects": 1,
      "title": "text"
    }
  ],
  "code": 1
}

get

Returns a list of 'filters', organized by data source (BQ table), for the current IDC data version. An IDC cohort is defined by a 'filterset', a set of (filter,[values]) pairs, and the IDC version against which the filterset is applied. The returned data is grouped by source (the BQ table that contains the corresponding filter values). For each filter, its data type and units, when available, are reported.

Responses

200

A list of filters

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/filters

HTTPcURLJavaScriptPython

GET /filters HTTP/1.1
Host: 
Accept: */*

{
  "idc_data_version": "text",
  "data_sources": [
    {
      "data_source": "text",
      "filters": [
        {
          "name": "text",
          "data_type": "CONTINUOUS_NUMERIC",
          "units": "text"
        }
      ]
    }
  ],
  "code": 1
}

get

Return a list of the values accepted for a 'categorical filter'. A categorical filter is a filter having a data type of 'Categorical String' or 'Categorical Number'.

Path parameters

filterstringRequired

Categorical filter whose values are to be returned

Responses

200

A list of accepted values

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/filters/values/{filter}

HTTPcURLJavaScriptPython

GET /filters/values/{filter} HTTP/1.1
Host: 
Accept: */*

{
  "values": [
    "text"
  ]
}

get

Return a list of queryable manifest fields.

Path parameters

versionstringRequired

IDC data version whose data is to be returned. If the version is 'current', the fields of the current IDC version are returned.

Responses

200

A list of fields

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/fields/{version}

HTTPcURLJavaScriptPython

GET /fields/{version} HTTP/1.1
Host: 
Accept: */*

{
  "idc_data_version": "text",
  "data_sources": [
    {
      "data_source": "text",
      "fields": [
        "text"
      ]
    }
  ],
  "code": 1
}

post

Returns a manifest of a 'previewed cohort' as defined by a specified filterset. The filterset is always applied to the current IDC version. The metadata to be returned in the manifest is configurable. A previewed cohort is not saved in the user's IDC account.

Body

application/json

countsstringOptional

If True, return counts of DICOM objects

Default: False

group_sizestringOptional

If True, return size in bytes of instances in group

Default: False

sqlstringOptional

If True, return the BQ SQL for this query.

Default: False

page_sizeintegerOptional

Maximum number of rows to return

Default: 1000

Responses

200

Preview cohort spec and manifest

application/jsonapplication/xml

202

Timeout waiting for BQ job to complete

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

post

/cohorts/manifest/preview

HTTPcURLJavaScriptPython

POST /cohorts/manifest/preview HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 345

{
  "cohort_def": {
    "name": "mycohort",
    "description": "Example description",
    "filters": {
      "collection_id": [
        "TCGA_luad",
        "tcga_kirc"
      ],
      "Modality": [
        "CT",
        "MR"
      ],
      "Race": [
        "WHITE"
      ],
      "age_at_diagnosis_btw": [
        65,
        75
      ]
    }
  },
  "fields": [
    "Age_At_Diagnosis",
    "aws_bucket",
    "crdc_series_uuid",
    "Modality",
    "SliceThickness"
  ],
  "counts": true,
  "group_size": true,
  "sql": true,
  "page_size": 1000
}

{
  "cohort": {
    "name": "text",
    "description": "text",
    "filterSet": {
      "idc_data_version": "text",
      "filters": {
        "project_short_name": [
          "text"
        ],
        "sample_type": [
          "text"
        ],
        "age_at_diagnosis_btw": [
          1
        ],
        "age_at_diagnosis_ebtw": [
          1
        ],
        "age_at_diagnosis_btwe": [
          1
        ],
        "age_at_diagnosis_ebtwe": [
          1
        ],
        "age_at_diagnosis_gte": [
          1
        ],
        "age_at_diagnosis_lte": [
          1
        ],
        "age_at_diagnosis_gt": [
          1
        ],
        "age_at_diagnosis_lt": [
          1
        ],
        "age_at_diagnosis_eq": [
          1
        ],
        "bmi_btw": [
          1
        ],
        "bmi_ebtw": [
          1
        ],
        "bmi_btwe": [
          1
        ],
        "bmi_ebtwe": [
          1
        ],
        "bmi_gte": [
          1
        ],
        "bmi_lte": [
          1
        ],
        "bmi_gt": [
          1
        ],
        "bmi_lt": [
          1
        ],
        "bmi_eq": [
          1
        ],
        "country": [
          "text"
        ],
        "disease_code": [
          "text"
        ],
        "ethnicity": [
          "text"
        ],
        "gender": [
          "text"
        ],
        "histological_type": [
          "text"
        ],
        "pathologic_stage": [
          "text"
        ],
        "project_name": [
          "text"
        ],
        "race": [
          "text"
        ],
        "tumor_tissue_site": [
          "text"
        ],
        "vital_status": [
          "text"
        ],
        "analysis_results_id": [
          "text"
        ],
        "AnatomicRegionSequence": [
          "text"
        ],
        "Apparent_Diffusion_Coefficient_btw": [
          1
        ],
        "Apparent_Diffusion_Coefficient_ebtw": [
          1
        ],
        "Apparent_Diffusion_Coefficient_btwe": [
          1
        ],
        "Apparent_Diffusion_Coefficient_ebtwe": [
          1
        ],
        "Apparent_Diffusion_Coefficient_gte": [
          1
        ],
        "Apparent_Diffusion_Coefficient_lte": [
          1
        ],
        "Apparent_Diffusion_Coefficient_gt": [
          1
        ],
        "Apparent_Diffusion_Coefficient_lt": [
          1
        ],
        "Apparent_Diffusion_Coefficient_eq": [
          1
        ],
        "BodyPartExamined": [
          "text"
        ],
        "Calcification": [
          "text"
        ],
        "CancerType": [
          "text"
        ],
        "collection_id": [
          "text"
        ],
        "Diameter_btw": [
          1
        ],
        "Diameter_ebtw": [
          1
        ],
        "Diameter_btwe": [
          1
        ],
        "Diameter_ebtwe": [
          1
        ],
        "Diameter_gte": [
          1
        ],
        "Diameter_lte": [
          1
        ],
        "Diameter_gt": [
          1
        ],
        "Diameter_lt": [
          1
        ],
        "Diameter_eq": [
          1
        ],
        "illuminationType": [
          "text"
        ],
        "Internal_structure": [
          "text"
        ],
        "license_short_name": [
          "text"
        ],
        "Lobular_Pattern": [
          "text"
        ],
        "Malignancy": [
          "text"
        ],
        "Manufacturer": [
          "text"
        ],
        "ManufacturerModelName": [
          "text"
        ],
        "Margin": [
          "text"
        ],
        "max_TotalPixelMatrixColumns_btw": [
          1
        ],
        "max_TotalPixelMatrixColumns_ebtw": [
          1
        ],
        "max_TotalPixelMatrixColumns_btwe": [
          1
        ],
        "max_TotalPixelMatrixColumns_ebtwe": [
          1
        ],
        "max_TotalPixelMatrixColumns_gte": [
          1
        ],
        "max_TotalPixelMatrixColumns_lte": [
          1
        ],
        "max_TotalPixelMatrixColumns_gt": [
          1
        ],
        "max_TotalPixelMatrixColumns_lt": [
          1
        ],
        "max_TotalPixelMatrixColumns_eq": [
          1
        ],
        "max_TotalPixelMatrixRows_btw": [
          1
        ],
        "max_TotalPixelMatrixRows_ebtw": [
          1
        ],
        "max_TotalPixelMatrixRows_btwe": [
          1
        ],
        "max_TotalPixelMatrixRows_ebtwe": [
          1
        ],
        "max_TotalPixelMatrixRows_gte": [
          1
        ],
        "max_TotalPixelMatrixRows_lte": [
          1
        ],
        "max_TotalPixelMatrixRows_gt": [
          1
        ],
        "max_TotalPixelMatrixRows_lt": [
          1
        ],
        "max_TotalPixelMatrixRows_eq": [
          1
        ],
        "min_PixelSpacing_btw": [
          1
        ],
        "min_PixelSpacing_ebtw": [
          1
        ],
        "min_PixelSpacing_btwe": [
          1
        ],
        "min_PixelSpacing_ebtwe": [
          1
        ],
        "min_PixelSpacing_gte": [
          1
        ],
        "min_PixelSpacing_lte": [
          1
        ],
        "min_PixelSpacing_gt": [
          1
        ],
        "min_PixelSpacing_lt": [
          1
        ],
        "min_PixelSpacing_eq": [
          1
        ],
        "Modality": [
          "text"
        ],
        "ObjectiveLensPower": [
          1
        ],
        "PatientID": [
          "text"
        ],
        "primaryAnatomicStructure": [
          "text"
        ],
        "SamplesPerPixel": [
          "text"
        ],
        "SegmentAlgorithmName": [
          "text"
        ],
        "SegmentAlgorithmType": [
          "text"
        ],
        "SegmentedPropertyCategoryCodeSequence": [
          "text"
        ],
        "SegmentedPropertyTypeCodeSequence": [
          "text"
        ],
        "SeriesDescription": [
          "text"
        ],
        "SeriesInstanceUID": [
          "text"
        ],
        "SeriesNumber": [
          "text"
        ],
        "SliceThickness_btw": [
          1
        ],
        "SliceThickness_ebtw": [
          1
        ],
        "SliceThickness_btwe": [
          1
        ],
        "SliceThickness_ebtwe": [
          1
        ],
        "SliceThickness_gte": [
          1
        ],
        "SliceThickness_lte": [
          1
        ],
        "SliceThickness_gt": [
          1
        ],
        "SliceThickness_lt": [
          1
        ],
        "SliceThickness_eq": [
          1
        ],
        "SOPClassUID": [
          "text"
        ],
        "SOPInstanceUID": [
          "text"
        ],
        "Sphericity": [
          "text"
        ],
        "Sphericity_quant_btw": [
          1
        ],
        "Sphericity_quant_ebtw": [
          1
        ],
        "Sphericity_quant_btwe": [
          1
        ],
        "Sphericity_quant_ebtwe": [
          1
        ],
        "Sphericity_quant_gte": [
          1
        ],
        "Sphericity_quant_lte": [
          1
        ],
        "Sphericity_quant_gt": [
          1
        ],
        "Sphericity_quant_lt": [
          1
        ],
        "Sphericity_quant_eq": [
          1
        ],
        "Spiculation": [
          "text"
        ],
        "StudyDate": [
          "text"
        ],
        "StudyDescription": [
          "text"
        ],
        "StudyInstanceUID": [
          "text"
        ],
        "Subtlety_score": [
          "text"
        ],
        "Surface_area_of_mesh_btw": [
          1
        ],
        "Surface_area_of_mesh_ebtw": [
          1
        ],
        "Surface_area_of_mesh_btwe": [
          1
        ],
        "Surface_area_of_mesh_ebtwe": [
          1
        ],
        "Surface_area_of_mesh_gte": [
          1
        ],
        "Surface_area_of_mesh_lte": [
          1
        ],
        "Surface_area_of_mesh_gt": [
          1
        ],
        "Surface_area_of_mesh_lt": [
          1
        ],
        "Surface_area_of_mesh_eq": [
          1
        ],
        "tcia_species": [
          "text"
        ],
        "tcia_tumorLocation": [
          "text"
        ],
        "Texture": [
          "text"
        ],
        "Volume_btw": [
          1
        ],
        "Volume_ebtw": [
          1
        ],
        "Volume_btwe": [
          1
        ],
        "Volume_ebtwe": [
          1
        ],
        "Volume_gte": [
          1
        ],
        "Volume_lte": [
          1
        ],
        "Volume_gt": [
          1
        ],
        "Volume_lt": [
          1
        ],
        "Volume_eq": [
          1
        ],
        "Volume_of_Mesh_btw": [
          1
        ],
        "Volume_of_Mesh_ebtw": [
          1
        ],
        "Volume_of_Mesh_btwe": [
          1
        ],
        "Volume_of_Mesh_ebtwe": [
          1
        ],
        "Volume_of_Mesh_gte": [
          1
        ],
        "Volume_of_Mesh_lte": [
          1
        ],
        "Volume_of_Mesh_gt": [
          1
        ],
        "Volume_of_Mesh_lt": [
          1
        ],
        "Volume_of_Mesh_eq": [
          1
        ]
      }
    },
    "sql": "text"
  },
  "manifest": {
    "manifest_data": [
      {
        "age_at_diagnosis": 1,
        "analysis_results_id": "text",
        "AnatomicRegionSequence": "text",
        "Apparent_Diffusion_Coefficient": 1,
        "aws_bucket": "text",
        "aws_url": "text",
        "bmi": 1,
        "BodyPartExamined": "text",
        "Calcification": "text",
        "CancerType": "text",
        "collection_id": "text",
        "country": "text",
        "crdc_instance_uuid": "text",
        "crdc_series_uuid": "text",
        "crdc_study_uuid": "text",
        "Diameter": 1,
        "disease_code": "text",
        "ethnicity": "text",
        "FrameOfReferenceUID": "text",
        "gcs_bucket": "text",
        "gcs_url": "text",
        "gender": "text",
        "histological_type": "text",
        "illuminationType": "text",
        "instance_size": 1,
        "Internal_structure": "text",
        "license_short_name": "text",
        "Lobular_Pattern": "text",
        "Malignancy": "text",
        "Manufacturer": "text",
        "ManufacturerModelName": "text",
        "Margin": "text",
        "max_TotalPixelMatrixColumns": 1,
        "max_TotalPixelMatrixRows": 1,
        "min_PixelSpacing": 1,
        "Modality": "text",
        "ObjectiveLensPower": 1,
        "pathologic_stage": "text",
        "PatientID": "text",
        "primaryAnatomicStructure": "text",
        "Program": "text",
        "project_name": "text",
        "project_short_name": "text",
        "race": "text",
        "sample_type": "text",
        "SamplesPerPixel": 1,
        "SegmentAlgorithmType": "text",
        "SegmentedPropertyCategoryCodeSequence": "text",
        "SegmentedPropertyTypeCodeSequence": "text",
        "SegmentNumber": 1,
        "SeriesDescription": "text",
        "SeriesInstanceUID": "text",
        "SeriesNumber": "text",
        "SliceThickness": 1,
        "SOPClassUID": "text",
        "SOPInstanceUID": "text",
        "source_DOI": "text",
        "Sphericity": "text",
        "Sphericity_quant": 1,
        "Spiculation": "text",
        "StudyDate": "text",
        "StudyDescription": "text",
        "StudyInstanceUID": "text",
        "Subtlety_score": "text",
        "Surface_area_of_mesh": 1,
        "tcia_species": "text",
        "tcia_tumorLocation": "text",
        "Texture": "text",
        "tumor_tissue_site": "text",
        "vital_status": "text",
        "Volume": 1,
        "Volume_of_Mesh": 1,
        "instance_count": 1,
        "series_count": 1,
        "study_count": 1,
        "patient_count": 1,
        "collection_count": 1,
        "group_size": 1
      }
    ],
    "totalFound": 1,
    "rowsReturned": 1
  },
  "next_page": "text",
  "code": 1
}

get

Returns the next page of a /cohorts/manifest/preview request, when additional data is available.

Query parameters

next_pagestringRequired

The next_page token returned by a previous access of the /cohorts/manifest/preview endpoint. The token identifies the next page to be retrieved

page_sizeintegerOptional

The maximum number of rows to be returned. If the manifest contains additional rows, another 'next_page' token is returned.

Responses

200

Preview manifest page

application/jsonapplication/xml

202

Timeout waiting for BQ job to complete

application/jsonapplication/xml

500

Server error message

application/jsonapplication/xml

get

/cohorts/manifest/preview/nextPage

HTTPcURLJavaScriptPython

GET /cohorts/manifest/preview/nextPage?next_page=text HTTP/1.1
Host: 
Accept: */*

{
  "manifest": {
    "manifest_data": [
      {
        "age_at_diagnosis": 1,
        "analysis_results_id": "text",
        "AnatomicRegionSequence": "text",
        "Apparent_Diffusion_Coefficient": 1,
        "aws_bucket": "text",
        "aws_url": "text",
        "bmi": 1,
        "BodyPartExamined": "text",
        "Calcification": "text",
        "CancerType": "text",
        "collection_id": "text",
        "country": "text",
        "crdc_instance_uuid": "text",
        "crdc_series_uuid": "text",
        "crdc_study_uuid": "text",
        "Diameter": 1,
        "disease_code": "text",
        "ethnicity": "text",
        "FrameOfReferenceUID": "text",
        "gcs_bucket": "text",
        "gcs_url": "text",
        "gender": "text",
        "histological_type": "text",
        "illuminationType": "text",
        "instance_size": 1,
        "Internal_structure": "text",
        "license_short_name": "text",
        "Lobular_Pattern": "text",
        "Malignancy": "text",
        "Manufacturer": "text",
        "ManufacturerModelName": "text",
        "Margin": "text",
        "max_TotalPixelMatrixColumns": 1,
        "max_TotalPixelMatrixRows": 1,
        "min_PixelSpacing": 1,
        "Modality": "text",
        "ObjectiveLensPower": 1,
        "pathologic_stage": "text",
        "PatientID": "text",
        "primaryAnatomicStructure": "text",
        "Program": "text",
        "project_name": "text",
        "project_short_name": "text",
        "race": "text",
        "sample_type": "text",
        "SamplesPerPixel": 1,
        "SegmentAlgorithmType": "text",
        "SegmentedPropertyCategoryCodeSequence": "text",
        "SegmentedPropertyTypeCodeSequence": "text",
        "SegmentNumber": 1,
        "SeriesDescription": "text",
        "SeriesInstanceUID": "text",
        "SeriesNumber": "text",
        "SliceThickness": 1,
        "SOPClassUID": "text",
        "SOPInstanceUID": "text",
        "source_DOI": "text",
        "Sphericity": "text",
        "Sphericity_quant": 1,
        "Spiculation": "text",
        "StudyDate": "text",
        "StudyDescription": "text",
        "StudyInstanceUID": "text",
        "Subtlety_score": "text",
        "Surface_area_of_mesh": 1,
        "tcia_species": "text",
        "tcia_tumorLocation": "text",
        "Texture": "text",
        "tumor_tissue_site": "text",
        "vital_status": "text",
        "Volume": 1,
        "Volume_of_Mesh": 1,
        "instance_count": 1,
        "series_count": 1,
        "study_count": 1,
        "patient_count": 1,
        "collection_count": 1,
        "group_size": 1
      }
    ],
    "totalFound": 1,
    "rowsReturned": 1
  },
  "next_page": "text",
  "code": 1
}