Current Web API

The current Web API offers services through the servlet webservice.do. It is described on the web_api.jsp webpage, and responds to these commands: getTypesOfCancer getCancerStudies getGeneticProfiles getCaseLists getCaseLists getMutationData getClinicalData getProteinArrayInfo getProteinArrayData.

Revised Web API (In Development)

There is a new Web API in development. A few of these functions are currently in use in cBioPortal, but the API is currently being expanded and revised. Below is a summary of the API captured with OpenAPI/swagger annotation (generated using tools from the SpringFox project and the Swagger2Markup project). There is also a springfox swagger-ui webpage.

Overview

A web service for supplying JSON formatted data to cBioPortal clients.

Version information

Version: 1.0 (beta)

Contact information

Contact: cbioportal@googlegroups.com

License information

License: License License URL: https://github.com/cBioPortal/cbioportal/blob/master/LICENSE

Terms of service: www.cbioportal.org

URI scheme

Host: cbioportal.org BasePath: /

Tags

  • api-controller: Api Controller

Paths

Get cancer types with meta data

GET /api/cancertypes

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParametercancer_type_idsList of cancer type identifiers (example: cll,brca,coad). Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBCancerType array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get cancer types with meta data

POST /api/cancertypes

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParametercancer_type_idsList of cancer type identifiers (example: cll,brca,coad). Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBCancerType array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical attribute identifiers, filtered by patient

GET /api/clinicalattributes/patients

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Empty string returns clinical attributes across all studies.falsestring
QueryParameterpatient_idsList of patient_ids. If provided, returned clinical attributes will be those which appear in any listed patient. Empty string returns clinical attributes across all patients.falsemulti string array

Responses

DBClinicalField array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical attribute identifiers, filtered by patient

POST /api/clinicalattributes/patients

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Empty string returns clinical attributes across all studies.falsestring
QueryParameterpatient_idsList of patient_ids. If provided, returned clinical attributes will be those which appear in any listed patient. Empty string returns clinical attributes across all patients.falsemulti string array

Responses

DBClinicalField array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical attribute identifiers, filtered by sample

GET /api/clinicalattributes/samples

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Empty string returns clinical attributes across all studies.falsestring
QueryParametersample_idsList of sample_ids. If provided, returned clinical attributes will be those which appear in any listed sample. Empty string returns clinical attributes across all samples.falsemulti string array

Responses

DBClinicalField array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical attribute identifiers, filtered by sample

POST /api/clinicalattributes/samples

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Empty string returns clinical attributes across all studies.falsestring
QueryParametersample_idsList of sample_ids. If provided, returned clinical attributes will be those which appear in any listed sample. Empty string returns clinical attributes across all samples.falsemulti string array

Responses

DBClinicalField array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical data records filtered by patient ids

GET /api/clinicaldata/patients

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParameterattribute_idsList of attribute ids, such as those returned by /api/clinicalattributes/patients. (example: PATIENT_ID,DFS_STATUS)truemulti string array
QueryParameterpatient_idsList of patient identifiers such as those returned by /api/patients. Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBClinicalPatientData array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical data records filtered by patient ids

POST /api/clinicaldata/patients

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParameterattribute_idsList of attribute ids, such as those returned by /api/clinicalattributes/patients. (example: PATIENT_ID,DFS_STATUS)truemulti string array
QueryParameterpatient_idsList of patient identifiers such as those returned by /api/patients. Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBClinicalPatientData array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical data records, filtered by sample ids

GET /api/clinicaldata/samples

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParameterattribute_idsList of attribute ids, such as those returned by /api/clinicalattributes/samples. (example: SAMPLE_TYPE,IS_FFPE)truemulti string array
QueryParametersample_idsList of sample identifiers. Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBClinicalSampleData array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get clinical data records, filtered by sample ids

POST /api/clinicaldata/samples

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParameterattribute_idsList of attribute ids, such as those returned by /api/clinicalattributes/samples. (example: SAMPLE_TYPE,IS_FFPE)truemulti string array
QueryParametersample_idsList of sample identifiers. Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBClinicalSampleData array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get gene meta data by hugo gene symbol lookup

GET /api/genes

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterhugo_gene_symbolsList of hugo gene symbols. Unrecognized genes are silently ignored. Empty string returns all genes.falsemulti string array

Responses

DBGene array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get gene meta data by hugo gene symbol lookup

POST /api/genes

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterhugo_gene_symbolsList of hugo gene symbols. Unrecognized genes are silently ignored. Empty string returns all genes.falsemulti string array

Responses

DBGene array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get genetic profile data across samples for given genes, and filtered by sample id or sample list id

GET /api/geneticprofiledata

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParametergenetic_profile_idsList of genetic_profile_ids such as those returned by /api/geneticprofiles. (example: brca_tcga_pub_mutations). Unrecognized genetic profile ids are silently ignored. Profile data is only returned for matching ids.truemulti string array
QueryParametergenesList of hugo gene symbols. (example: AKT1,CASP8,TGFBR1) Unrecognized gene ids are silently ignored. Profile data is only returned for matching genes.truemulti string array
QueryParametersample_idsList of sample identifiers such as those returned by /api/samples. Empty string returns all. Must be empty to query by sample list ids.falsemulti string array
QueryParametersample_list_idA single sample list ids such as those returned by /api/samplelists. (example: brca_tcga_idc,brca_tcga_lobular). Empty string returns all. If sample_ids argument was provided, this argument will be ignored.falsestring

Responses

DBProfileData array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get genetic profile data across samples for given genes, and filtered by sample id or sample list id

POST /api/geneticprofiledata

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParametergenetic_profile_idsList of genetic_profile_ids such as those returned by /api/geneticprofiles. (example: brca_tcga_pub_mutations). Unrecognized genetic profile ids are silently ignored. Profile data is only returned for matching ids.truemulti string array
QueryParametergenesList of hugo gene symbols. (example: AKT1,CASP8,TGFBR1) Unrecognized gene ids are silently ignored. Profile data is only returned for matching genes.truemulti string array
QueryParametersample_idsList of sample identifiers such as those returned by /api/samples. Empty string returns all. Must be empty to query by sample list ids.falsemulti string array
QueryParametersample_list_idA single sample list ids such as those returned by /api/samplelists. (example: brca_tcga_idc,brca_tcga_lobular). Empty string returns all. If sample_ids argument was provided, this argument will be ignored.falsestring

Responses

DBProfileData array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get list of genetic profile identifiers by study

GET /api/geneticprofiles

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Must be empty to query by genetic profile ids (across all studies).falsestring
QueryParametergenetic_profile_idsList of genetic_profile_ids. (example: brca_tcga_pub_mutations). Empty string returns all genetic profiles. If study_id argument was provided, this argument will be ignored.falsemulti string array

Responses

DBGeneticProfile array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get list of genetic profile identifiers by study

POST /api/geneticprofiles

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Must be empty to query by genetic profile ids (across all studies).falsestring
QueryParametergenetic_profile_idsList of genetic_profile_ids. (example: brca_tcga_pub_mutations). Empty string returns all genetic profiles. If study_id argument was provided, this argument will be ignored.falsemulti string array

Responses

DBGeneticProfile array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get patient id list by study or by sample id

GET /api/patients

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParameterpatient_idsList of patient ids such as those returned by /api/patients. Empty string returns all. Must be empty to query by sample ids.falsemulti string array
QueryParametersample_idsList of sample identifiers. Empty string returns all. If patient_ids argument was provided, this argument will be ignored.falsemulti string array

Responses

DBPatient array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get patient id list by study or by sample id

POST /api/patients

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParameterpatient_idsList of patient ids such as those returned by /api/patients. Empty string returns all. Must be empty to query by sample ids.falsemulti string array
QueryParametersample_idsList of sample identifiers. Empty string returns all. If patient_ids argument was provided, this argument will be ignored.falsemulti string array

Responses

DBPatient array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get list of sample lists (list name and sample id list) by study

GET /api/samplelists

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Must be empty to query by sample list ids (across all studies).falsestring
QueryParametersample_list_idsList of sample list ids. (example: brca_tcga_idc,brca_tcga_lobular). Empty string returns all genetic profiles. If study_id argument was provided, this argument will be ignored.falsemulti string array

Responses

DBSampleList array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get list of sample lists (list name and sample id list) by study

POST /api/samplelists

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga). Must be empty to query by sample list ids (across all studies).falsestring
QueryParametersample_list_idsList of sample list ids. (example: brca_tcga_idc,brca_tcga_lobular). Empty string returns all genetic profiles. If study_id argument was provided, this argument will be ignored.falsemulti string array

Responses

DBSampleList array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get list of samples ids with meta data by study, filtered by sample ids or patient ids

GET /api/samples

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParametersample_idsList of sample identifiers. Unrecognized ids are silently ignored. Empty string returns all. Must be empty to query by patient_ids.falsemulti string array
QueryParameterpatient_idsList of patient identifiers such as those returned by /api/patients. Unrecognized ids are silently ignored. Empty string returns all. If sample_ids argument was provided, this arument will be ignored.falsemulti string array

Responses

DBSample array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get list of samples ids with meta data by study, filtered by sample ids or patient ids

POST /api/samples

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idA single study id, such as those returned by /api/studies. (example: brca_tcga)truestring
QueryParametersample_idsList of sample identifiers. Unrecognized ids are silently ignored. Empty string returns all. Must be empty to query by patient_ids.falsemulti string array
QueryParameterpatient_idsList of patient identifiers such as those returned by /api/patients. Unrecognized ids are silently ignored. Empty string returns all. If sample_ids argument was provided, this arument will be ignored.falsemulti string array

Responses

DBSample array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get studies

GET /api/studies

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idsList of study_ids. Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBStudy array
HTTP CodeDescriptionSchema
200OK
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Get studies

POST /api/studies

Parameters

TypeNameDescriptionRequiredSchemaDefault
QueryParameterstudy_idsList of study_ids. Unrecognized ids are silently ignored. Empty string returns all.falsemulti string array

Responses

DBStudy array
HTTP CodeDescriptionSchema
200OK
201CreatedNo Content
401UnauthorizedNo Content
403ForbiddenNo Content
404Not FoundNo Content

Consumes

  • application/json

Produces

  • /

Tags

  • api-controller

Definitions

DBCancerType

NameDescriptionRequiredSchemaDefault
colorfalsestring
idfalsestring
namefalsestring

DBClinicalField

NameDescriptionRequiredSchemaDefault
attr_idfalsestring
datatypefalsestring
descriptionfalsestring
display_namefalsestring
is_patient_attributefalsestring
priorityfalsestring

DBClinicalPatientData

NameDescriptionRequiredSchemaDefault
attr_idfalsestring
attr_valfalsestring
patient_idfalsestring
study_idfalsestring

DBClinicalSampleData

NameDescriptionRequiredSchemaDefault
attr_idfalsestring
attr_valfalsestring
sample_idfalsestring
study_idfalsestring

DBGene

NameDescriptionRequiredSchemaDefault
entrez_gene_idfalsestring
hugo_gene_symbolfalsestring

DBGeneticProfile

NameDescriptionRequiredSchemaDefault
datatypefalsestring
descriptionfalsestring
genetic_alteration_typefalsestring
idfalsestring
namefalsestring
show_profile_in_analysis_tabfalsestring
study_idfalsestring

DBPatient

NameDescriptionRequiredSchemaDefault
idfalsestring
study_idfalsestring

DBProfileData

NameDescriptionRequiredSchemaDefault
entrez_gene_idfalsestring
genetic_profile_idfalsestring
hugo_gene_symbolfalsestring
sample_idfalsestring
sample_list_idfalsestring
study_idfalsestring

DBSample

NameDescriptionRequiredSchemaDefault
idfalsestring
internal_idfalsestring
patient_idfalsestring
sample_typefalsestring
study_idfalsestring

DBSampleList

NameDescriptionRequiredSchemaDefault
descriptionfalsestring
idfalsestring
namefalsestring
sample_idsfalsestring array
study_idfalsestring

DBStudy

NameDescriptionRequiredSchemaDefault
citationfalsestring
descriptionfalsestring
groupsfalsestring
idfalsestring
namefalsestring
pmidfalseinteger (int64)
short_namefalsestring
type_of_cancerfalsestring

Upcoming

####Services to be rewritten to use the new Web API

  • getProfileData.json : get genetic alterations for profile, genes
  • getGeneticProfile.json : get genetic alterations for study, genes
  • GeneData.json : get data from genetic profiles
  • CheckGeneSymbol.json : simple gene lookup
  • clinicalAttributes.json : fetch clinical attibute list
  • getAlterationData.json : lookup set of alterations by study, profile, genes
  • portal_meta_data.json : Fetch meta data for study
  • clinical_timeline_data.json : Fetch clinical data for a patient ID
  • ClinicalFreeForm.json : fetch clinical data based on availability
  • getMutationData.json : Get mutations across genetic profile (with gene filter)
  • portalMetadata.json : Get sample profile metadata

####Services to be migrated into additional Web API functionality

  • mutations.json : Bundle of functions providing study/gene/annotation merges for mutation tab
  • Gistic.json : lookup gistic entries for a study
  • cna.json : Bundle of functions providing copy number changes and segment metadata
  • MutSig.json : Fetch mutsig data for a study
  • getPfamSequence.json : Fetch pfam alignment strings
  • drugs.json : Fetch drug info and interactions
  • clinicaltrials.json : Search for matching clinical trials
  • getSurvivalData.json : Select survival data for sample set of a study
  • similar_patients.json : Find.Merge 2 sample sets: similar by mutation, similar by cna
  • pancancerMutations.json : Bundle of functions to find mutations in several ways
  • get3dPdb.json : Bundle of functions to get pdb data and related sequence data
  • crosscancerquery.json : Query by Studies and Genes, return profiles and patients
  • crosscancermutation.json : Query by Studies and Genes, return patients and mutations
  • igvlinking.json : Make igv links for study/case/locus
  • getMutationAligner.json : Create URL links to mutation aligner
  • bioGeneQuery.do : Create URL links to bioGene
  • oranalysis.do : Compute p-value for alteration subset in profile, gene
  • getCoExp.do : Compute co-expression for genes across profiles
  • network.do : Bundle of functions to return genes and interactions in a study,profile with meta data

####Services to be Deprecated and Dropped eventually

  • webservice.do : old WEB API requests