openapi: 3.0.3
info:
description: The HuBMAP Search API is a thin wrapper of the Elasticsearch API. It handles data indexing and reindexing into the backend Elasticsearch. It also accepts the search query and passes through to the Elasticsearch with data access security check.
version: 3.0.1
title: HuBMAP Search API
termsOfService: 'https://hubmapconsortium.org'
contact:
name: HuBMAP Help Desk
email: help@hubmapconsortium.org
license:
name: MIT License
url: 'https://github.com/hubmapconsortium/entity-api/blob/master/license.txt'
externalDocs:
description: Generating a HuBMAP CLT Manifest with search-api
url: https://docs.hubmapconsortium.org/clt/generate-manifest.html
servers:
- url: "https://search.api.hubmapconsortium.org/v3/"
components:
schemas:
Person:
type: object
properties:
first_name:
type: string
description: "The full name of the person."
last_name:
type: string
description: The last name of the person.
middle_name_or_initial:
type: string
description: The middle name or initial of the person.
orcid_id:
type: string
description: The ORCID iD of the person.
affiliation:
type: string
description: The institution that the person is affiliated with.
Antibody:
type: object
properties:
antibody_name:
type: string
description: "The name of the antibody."
channel_id:
type: string
description: "The assay specific identifier for the channel corresponding to the antibody."
conjugated_cat_number:
type: string
description: "An antibody may be conjugated to a fluorescent tag or a metal tag for detection. Conjugated antibodies may be purchased from commercial providers. Blank if not applicable."
conjugated_tag:
type: string
description: "An antibody may be conjugated to a fluorescent tag or a metal tag for detection. Conjugated antibodies may be purchased from commercial providers. Blank if not applicable."
dilution:
type: string
description: "The dilition ratio, e.g. 1/200 for the antibody. Blank if not applicable."
lot_number:
type: string
description: "The antibody lot number from the vendor."
rr_id:
type: string
description: "The unique antibody identifier from the Antibody Registry (https://antibodyregistry.org). "
uniprot_accession_number:
type: string
description: "The unique identifier for the target protein in the UniProt database (https://www.uniprot.org)."
DonorMetadata:
type: object
properties:
code:
type: string
description: "This is a Code from a source vocabulary in the HuBMAP Knowledge Graph, currently limited to UMLS source vocabulary terms."
sab:
type: string
description: "This is the source vocabulary in the HuBMAP Knowledge Graph. Currently limited to UMLS source vocabularies."
concept_id:
type: string
description: "This is the Concept ID from the HuBMAP Knowledge Graph. Currently limited to UMLS concepts."
data_type:
type: string
enum:
- Nominal
- Numeric
description: "This is the data type of thw record. Numeric types will generally have non-null data_value. Nominal types will generally have null data_value."
data_value:
type: string
description: "The data value of the record."
numeric_operator:
type: string
enum:
- EQ
- GT
- LT
description: "This is the numeric operator for the data value .This enables inputing thresholds and ranges for data values by using greater than or less than."
units:
type: string
description: "This are the units for the data value."
preferred_term:
type: string
description: "This is the preferred display term for the item. It may or may not correspond to a term in UMLS for this concept."
grouping_concept:
type: string
description: "This is the Concept ID from the HuBMAP Knowledge Graph, currently limited to UMLS concetps, that is to be used for grouping the record."
grouping_concept_preferred_term:
type: string
description: "This is the preferred display term for the facet in which this record should be counted for faceted search in the portal. It may or may not correspond to a term in UMLS for the grouping concept."
grouping_code:
type: string
description: "This is a Code from a source vocabulary in the HuBMAP Knowledge Graph, currently limited to UMLS vocabulary codes. This code corresponds to the grouping_concept."
grouping_sab:
type: string
description: "This is a grouping for the source vocabulary in the HuBMAP Knowledge Graph, currently limited to UMLS source vocabularies.. This sab corresponds to the grouping_code."
graph_version:
type: string
description: "This is the version of the HuBMAP Knowledge Graph that the Concept appears in, currently the version of UMLS that is used."
start_datetime:
type: integer
description: "This is the approximate time difference in seconds between the procurement and the start of this event (this is to construct time series records of clinical data for event-level data not donor-level data). An empty or zero value designates missing data or that this field is not applicable for the concept."
end_datetime:
type: integer
description: "This is the approximate time difference in seconds between the procurement and the end of this event (this is to construct time series records of clinical data for event-level data not donor-level data). An epty of zero value designates missing data or that this field is not applicable for the concept"
SampleMetadata:
type: object
description: "The sample specific metadata derived from the uploaded sample_metadata.tsv file. Returned as a json object."
properties:
sample_id:
type: string
description: "The HuBMAP Identifier for the sample."
vital_state:
type: string
enum:
- living
- deceased
description: "The vital state of the donor who the tissue sample came from."
health_status:
type: string
enum:
- cancer
- "relatively healthy"
- "chronic illness"
description: "Donor from which the tissue sample came from's baseline physical condition prior to immediate event leading to organ/tissue acquisition. For example, if a relatively healthy patient suffers trauma, and as a result of reparative surgery, a tissue sample is collected, the subject will be deemed 'relatively healthy'. Likewise, a relatively healthy subject may have experienced trauma leading to brain death. As a result of organ donation, a sample is collected. In this scenario, the subject is deemed 'relatively healthy'."
organ_condition:
type: string
enum:
- healthy
- diseased
description: "Health status of the organ at the time of tissue sample recovery."
procedure_date:
type: string
description: "The date at which the organ from which the tissue sample came from was procurred, in the format YYYY-MM-DD"
perfusion_solution:
type: string
enum:
- UWS
- HTK
- Belzer MPS/KPS
- Formalin
- Unknown
- None
description: "Health status of the organ at the time of sample recovery."
pathologist_report:
type: string
description: "Further details on organ level QC checks."
warm_ischemia_time_value:
type: integer
description: "Time interval between cessation of blood flow and cooling to 4C. Blank if not applicable."
warm_ischemia_time_unit:
type: string
description: "Time units that the warm_ischemia_time_value is reported in. Blank if not applicable"
cold_ischemia_time_value:
type: integer
description: "Time interval on ice to the start of preservation protocol. Blank if not applicable."
cold_ischemia_time_unit:
type: string
description: "Time units that the cold_ischemia_time_value is reported in. Blank if not applicable."
specimen_preservation_temperature:
type: string
description: "The temperature of the medium during the preservation process. Reported as preservation method, temperature and units, e.g. Freezer (-80 Celsius)"
specimen_quality_criteria:
type: string
description: "RIN score. e.g. RIN: 8.7"
specimen_tumor_distance_value:
type: string
description: "If surgical sample from a tumor biopsy, how far from the tumor was the sample obtained from. Typically a number of centimeters. Blank if not applicable or unknown."
specimen_tumor_distance_unit:
type: string
description: ""
File:
type: object
properties:
filename:
type: string
description: "The name of the file."
description:
type: string
description: "A description of the file. The Dataset.thumbnail_file does not have this file description."
file_uuid:
type: string
description: "The HuBMAP unique identifier for the file."
Donor:
type: object
properties:
created_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the node was created. The format is an integer representing milliseconds since midnight Jan 1, 1970"
created_by_user_displayname:
type: string
readOnly: true
description: "The name of the person or process authenticated when creating the object"
created_by_user_email:
type: string
readOnly: true
description: "The email address of the person or process authenticated when creating the object."
created_by_user_sub:
type: string
readOnly: true
description: "The subject id as provided by the authorization mechanism for the person or process authenticated when creating the object."
uuid:
type: string
readOnly: true
description: "The HuBMAP unique identifier, intended for internal software use only. This is a 32 digit hexadecimal uuid e.g. 461bbfdc353a2673e381f632510b0f17"
hubmap_id:
type: string
readOnly: true
description: "A HuBMAP Consortium wide unique identifier randomly generated in the format HBM###.ABCD.### for every entity."
last_modified_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the object was last modified. The format is an integer representing milliseconds since midnight, Jan 1, 1970"
last_modified_user_sub:
type: string
readOnly: true
description: "The subject id of the user who last modified the entity as provided by the authorization mechanism for the person or process authenticated when the object was modified."
last_modified_user_email:
type: string
readOnly: true
description: "The email address of the person or process which authenticated when the object was last modified."
last_modified_user_displayname:
type: string
readOnly: true
description: "The name of the person or process which authenticated when the object was last modified."
entity_type:
type: string
readOnly: true
description: "One of the normalized entity types: Dataset, Collection, Sample, Donor, Upload"
registered_doi:
type: string
description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets."
doi_url:
type: string
readOnly: true
description: "The url from the doi registry for this entity. e.g. https://doi.org/10.35079/hbm289.pcbm.487"
description:
type: string
description: "Free text description of the donor"
data_access_level:
type: string
readOnly: true
enum:
- consortium
- public
description: "One of the values: public, consortium"
image_files:
readOnly: true
type: array
items:
$ref: '#/components/schemas/File'
description: "List of uploaded image files and descriptions of the files. Stored in db as a stringfied json array."
metadata:
type: object
properties:
organ_donor_data:
type: array
description: "Information about the donor who's organ(s) was/were used. The organ was obtained via an organ donation program from a deceaced donor. Only living_donor_data or organ_donor_data, not both can be defined for a single donor."
items:
$ref: '#/components/schemas/DonorMetadata'
living_donor_data:
type: array
description: "Information about the donor who's tissue was used. The tissue was obtained during a procedure. Only living_donor_data or organ_donor_data, not both can be defined for a single donor."
items:
$ref: '#/components/schemas/DonorMetadata'
description: "Donor metadata as an array of UMLS codes and descriptions"
protocol_url:
type: string
description: "The protocols.io doi url pointing the protocol describing the donor selection, inclusion/exclusion criteria"
group_uuid:
type: string
description: "The uuid of globus group which the user who created this entity is a member of. This is required on Create/POST if the user creating the Donor is a member of more than one write group. This property cannot be set via PUT (only on Create/POST)."
group_name:
readOnly: true
type: string
description: "The displayname of globus group which the user who created this entity is a member of"
label:
type: string
description: "Lab provided, de-identified name for the donor"
Sample:
type: object
properties:
created_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the node was created. The format is an integer representing milliseconds since midnight Jan 1, 1970"
created_by_user_displayname:
type: string
readOnly: true
description: "The name of the person or process authenticated when creating the object"
created_by_user_email:
type: string
readOnly: true
description: "The email address of the person or process authenticated when creating the object."
created_by_user_sub:
type: string
readOnly: true
description: "The subject id as provided by the authorization mechanism for the person or process authenticated when creating the object."
uuid:
type: string
readOnly: true
description: "The HuBMAP unique identifier, intended for internal software use only. This is a 32 digit hexadecimal uuid e.g. 461bbfdc353a2673e381f632510b0f17"
hubmap_id:
type: string
readOnly: true
description: "A HuBMAP Consortium wide unique identifier randomly generated in the format HBM###.ABCD.### for every entity."
last_modified_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the object was last modified. The format is an integer representing milliseconds since midnight, Jan 1, 1970"
last_modified_user_sub:
type: string
readOnly: true
description: "The subject id of the user who last modified the entity as provided by the authorization mechanism for the person or process authenticated when the object was modified."
last_modified_user_email:
type: string
readOnly: true
description: "The email address of the person or process which authenticated when the object was last modified."
last_modified_user_displayname:
type: string
readOnly: true
description: "The name of the person or process which authenticated when the object was last modified."
entity_type:
type: string
readOnly: true
description: "One of the normalized entity types: Dataset, Collection, Sample, Donor"
registered_doi:
type: string
description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets."
doi_url:
type: string
readOnly: true
description: "The url from the doi registry for this entity. e.g. https://doi.org/10.35079/hbm289.pcbm.487"
description:
type: string
description: "Free text description of the sample"
data_access_level:
type: string
enum:
- consortium
- public
description: "One of the values: public, consortium."
sample_category:
type: string
enum:
- organ
- block
- section
- suspension
description: "A code representing the type of specimen. Must be an organ, block, section, or suspension"
protocol_url:
type: string
description: "The protocols.io doi url pointing the protocol under wich the sample was obtained and/or prepared."
group_uuid:
type: string
description: "The uuid of globus group which the user who created this entity is a member of. This is required on Create/POST if the user creating the Donor is a member of more than one write group. This property cannot be set via PUT (only on Create/POST)."
group_name:
readOnly: true
type: string
description: "The displayname of globus group which the user who created this entity is a member of"
organ:
type: string
enum:
- AO
- BL
- BD
- BM
- BR
- LF
- RF
- HT
- LB
- LE
- LI
- LK
- LL
- LN
- LV
- LY
- LO
- RO
- OT
- PA
- PL
- RB
- RE
- RK
- RL
- RN
- SI
- SK
- SP
- ST
- TH
- TR
- UR
- UT
description: "Organ code specifier, only set if sample_category == organ. Valid values found using [the Ontology API](https://ontology.api.hubmapconsortium.org/organs?application_context=HUBMAP)"
direct_ancestor_uuid:
type: string
writeOnly: true
description: "The uuid of source entity from which this new entity is derived from. Used on creation or edit to create an action and relationship to the ancestor. The direct ancestor must be a Donor or Sample. If the direct ancestor is a Donor, the sample must be of type organ."
direct_ancestor:
readOnly: true
type: object
description: "The entitiy directly above this sample in the provenance graph (direct parent)."
submission_id:
type: string
description: "The hubmap internal id with embedded semantic information e.g.: VAN0003-LK-1-10. This id is generated at creation time which tracks the lab, donor, organ and sample hierarchy per the following: https://docs.google.com/document/d/1DjHgmqWF1VA5-3mfzLFNfabbzmc8KLSG9xWx1DDLlzo/edit?usp=sharing"
metadata:
$ref: '#/components/schemas/SampleMetadata'
rui_location:
type: object
description: "The sample location and orientation in the ancestor organ as specified in the RUI tool. Returned as a json object."
visit:
type: string
description: "The visit id for the donor/patient when the sample was obtained."
image_files:
readOnly: true
type: array
items:
$ref: '#/components/schemas/File'
description: "List of uploaded image files and descriptions of the files. Stored in db as a stringfied json array."
image_files_to_add:
writeOnly: true
type: array
items:
type: string
format: temp_file_id
description: 'List of temporary file ids with an optional description. Provide as a json array with an temp_file_id and description attribute for each element like {"files": [{"temp_file_id":"dzevgd6xjs4d5grmcp4n","description":"This is image file one"},{"temp_file_id":"yrahjadfhadf","description":"This is image file two"}]}'
image_files_to_remove:
writeOnly: true
type: array
items:
type: string
format: file_uuid
description: 'List of image files previously uploaded to delete. Provide as a json array of the file_uuids of the file like: ["232934234234234234234270c0ea6c51d604a850558ef2247d0b4", "230948203482234234234a57bfe9c056d08a0f8e6cd612baa3bfa"]'
Dataset:
type: object
properties:
created_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the node was created. The format is an integer representing milliseconds since midnight Jan 1, 1970"
created_by_user_displayname:
type: string
readOnly: true
description: "The name of the person or process authenticated when creating the object"
created_by_user_email:
type: string
readOnly: true
description: "The email address of the person or process authenticated when creating the object."
created_by_user_sub:
type: string
readOnly: true
description: "The subject id as provided by the authorization mechanism for the person or process authenticated when creating the object."
donor:
$ref: '#/components/schemas/Donor'
description: The donor where the tissue came from for the assay that produced the data in this Dataset.
uuid:
type: string
readOnly: true
description: "The HuBMAP unique identifier, intended for internal software use only. This is a 32 digit hexadecimal uuid e.g. 461bbfdc353a2673e381f632510b0f17"
hubmap_id:
type: string
readOnly: true
description: "A HuBMAP Consortium wide unique identifier randomly generated in the format HBM###.ABCD.### for every entity."
error_message:
type: string
readOnly: false
description: "An open text field that holds the last error message that arose from pipeline validation or analysis."
last_modified_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the object was last modified. The format is an integer representing milliseconds since midnight, Jan 1, 1970"
last_modified_user_sub:
type: string
readOnly: true
description: "The subject id of the user who last modified the entity as provided by the authorization mechanism for the person or process authenticated when the object was modified."
last_modified_user_email:
type: string
readOnly: true
description: "The email address of the person or process which authenticated when the object was last modified."
last_modified_user_displayname:
type: string
readOnly: true
description: "The name of the person or process which authenticated when the object was last modified."
entity_type:
type: string
readOnly: true
description: "One of the normalized entity types: Dataset, Collection, Sample, Donor"
registered_doi:
type: string
description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets."
doi_url:
type: string
readOnly: true
description: "The url from the doi registry for this entity. e.g. https://doi.org/10.35079/hbm289.pcbm.487"
contacts:
type: array
items:
$ref: '#/components/schemas/Person'
description: "A list of the people who are the main contacts to get information about the entity."
antibodies:
type: array
items:
$ref: '#/components/schemas/Antibody'
description: "A list of antibodies used in the assay that created the dataset"
description:
type: string
description: "Free text description of the dataset"
data_access_level:
type: string
readOnly: true
enum:
- public
- consortium
description: "One of the values: public, consortium."
contains_human_genetic_sequences:
type: boolean
description: "True if the data contains any human genetic sequence information. Can only be set at CREATE/POST time"
status:
type: string
enum:
- New
- Processing
- QA
- Published
- Error
- Hold
- Invalid
- Approval
- Retracted
description: "One of: New|Processing|QA|Published|Error|Hold|Invalid|Approval|Retracted"
title:
type: string
description: "The dataset title."
contributors:
readOnly: true
type: array
items:
$ref: '#/components/schemas/Person'
description: "A list of people who contributed to the creation of this dataset. Returned as an array of contributor where the structure of a contributor is"
direct_ancestors:
readOnly: true
type: array
items:
anyOf:
- $ref: '#/components/schemas/Sample'
- $ref: '#/components/schemas/Dataset'
description: "A list of direct parent ancensters (one level above) that the Dataset was derived from."
published_timestamp:
readOnly: true
type: integer
description: "The timestamp of when the dataset was published. The format is an integer representing milliseconds since midnight, Jan 1, 1970."
published_user_displayname:
readOnly: true
type: string
description: "The name of the authenticated user or process that published the data."
published_user_sub:
readOnly: true
type: string
description: "The subject id for the user who published the data as provided by the authorization mechanism for the person or process authenticated when the dataset was publised."
published_user_email:
readOnly: true
type: string
description: "The email address of the user who published the provided by the authorization mechanism for the person or process authenticated when published."
ingest_metadata:
type: object
description: "The metadata returned from the ingest pipeline processing at data submission time. Provided as json. For details on querying metadata see the [Detailed Param Search Docs](https://docs.hubmapconsortium.org/param-search). For details of the metadata schemas by data set types see the [HuBMAP Metadata Attributes Documentation](https://docs.hubmapconsortium.org/assays/metadata/)"
metadata:
type: object
description: "Metadata associated with the ingested experimental data."
files:
type: object
description: "Files associated with the ingested experimental data."
local_directory_rel_path:
type: string
readOnly: true
description: "The path on the local HIVE file system, relative to the base data directory, where the data is stored."
group_uuid:
type: string
description: "The uuid of globus group which the user who created this entity is a member of. This is required on Create/POST if the user creating the Donor is a member of more than one write group. This property cannot be set via PUT (only on Create/POST)."
group_name:
type: string
readOnly: true
description: "The displayname of globus group which the user who created this entity is a member of"
thumbnail_file:
readOnly: true
description: 'The dataset thumbnail file detail. Stored in db as a stringfied json, e.g., {"filename": "thumbnail.jpg", "file_uuid": "c35002f9c3d49f8b77e1e2cd4a01803d"}'
sub_status:
type: string
description: 'A sub-status provided to further define the status. The only current allowable value is "Retracted"'
retraction_reason:
type: string
description: 'Information recorded about why a the dataset was retracted.'
dbgap_sra_experiment_url:
type: string
description: 'A URL linking the dataset to the associated uploaded data at dbGaP.'
dbgap_study_url:
type: string
description: 'A URL linking the dataset to the particular study on dbGap it belongs to'
creation_action:
type: string
description: 'The associated action that represents the creation of that dataset'
Publication:
type: object
properties:
created_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the node was created. The format is an integer representing milliseconds since midnight Jan 1, 1970"
created_by_user_displayname:
type: string
readOnly: true
description: "The name of the person or process authenticated when creating the object"
created_by_user_email:
type: string
readOnly: true
description: "The email address of the person or process authenticated when creating the object."
created_by_user_sub:
type: string
readOnly: true
description: "The subject id as provided by the authorization mechanism for the person or process authenticated when creating the object."
uuid:
type: string
readOnly: true
description: "The HuBMAP unique identifier, intended for internal software use only. This is a 32 digit hexadecimal uuid e.g. 461bbfdc353a2673e381f632510b0f17"
error_message:
type: string
readOnly: false
description: "An open text field that holds the last error message that arose from pipeline validation or analysis."
hubmap_id:
type: string
readOnly: true
description: "A HuBMAP Consortium wide unique identifier randomly generated in the format HBM###.ABCD.### for every entity."
last_modified_timestamp:
type: integer
readOnly: true
description: "The timestamp of when the object was last modified. The format is an integer representing milliseconds since midnight, Jan 1, 1970"
last_modified_user_sub:
type: string
readOnly: true
description: "The subject id of the user who last modified the entity as provided by the authorization mechanism for the person or process authenticated when the object was modified."
last_modified_user_email:
type: string
readOnly: true
description: "The email address of the person or process which authenticated when the object was last modified."
last_modified_user_displayname:
type: string
readOnly: true
description: "The name of the person or process which authenticated when the object was last modified."
entity_type:
type: string
readOnly: true
description: "One of the normalized entity types: Dataset, Collection, Sample, Donor"
registered_doi:
type: string
description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets."
doi_url:
type: string
readOnly: true
description: "The url from the doi registry for this entity. e.g. https://doi.org/10.35079/hbm289.pcbm.487"
contacts:
type: array
items:
$ref: '#/components/schemas/Person'
description: "A list of the people who are the main contacts to get information about the entity."
antibodies:
type: array
items:
$ref: '#/components/schemas/Antibody'
description: "A list of antibodies used in the assay that created the dataset"
description:
type: string
description: "Free text description of the dataset"
data_access_level:
type: string
readOnly: true
enum:
- public
- consortium
description: "One of the values: public, consortium."
contains_human_genetic_sequences:
type: boolean
description: "True if the data contains any human genetic sequence information. Can only be set at CREATE/POST time"
status:
type: string
enum:
- New
- Processing
- QA
- Published
- Error
- Hold
- Invalid
- Approval
- Retracted
description: "One of: New|Processing|QA|Published|Error|Hold|Invalid|Approval|Retracted"
title:
type: string
description: "The Publication title."
contributors:
readOnly: true
type: array
items:
$ref: '#/components/schemas/Person'
description: "A list of people who contributed to the creation of this dataset. Returned as an array of contributor where the structure of a contributor is"
direct_ancestors:
readOnly: true
type: array
items:
anyOf:
- $ref: '#/components/schemas/Sample'
- $ref: '#/components/schemas/Dataset'
description: "A list of direct parent ancensters (one level above) that the Dataset was derived from."
published_timestamp:
readOnly: true
type: integer
description: "The timestamp of when the dataset was published. The format is an integer representing milliseconds since midnight, Jan 1, 1970."
published_user_displayname:
readOnly: true
type: string
description: "The name of the authenticated user or process that published the data."
published_user_sub:
readOnly: true
type: string
description: "The subject id for the user who published the data as provided by the authorization mechanism for the person or process authenticated when the dataset was publised."
published_user_email:
readOnly: true
type: string
description: "The email address of the user who published the provided by the authorization mechanism for the person or process authenticated when published."
ingest_metadata:
type: object
description: "The metadata returned from the ingest pipeline processing at data submission time. Provided as json. For details on querying metadata see the [Detailed Param Search Docs](https://docs.hubmapconsortium.org/param-search). For details of the metadata schemas by data set types see the [HuBMAP Metadata Attributes Documentation](https://docs.hubmapconsortium.org/assays/metadata/)"
metadata:
type: object
description: "Metadata associated with the ingested experimental data."
files:
type: object
description: "Files associated with the ingested experimental data."
local_directory_rel_path:
type: string
readOnly: true
description: "The path on the local HIVE file system, relative to the base data directory, where the data is stored."
group_uuid:
type: string
description: "The uuid of globus group which the user who created this entity is a member of. This is required on Create/POST if the user creating the Donor is a member of more than one write group. This property cannot be set via PUT (only on Create/POST)."
group_name:
type: string
readOnly: true
description: "The displayname of globus group which the user who created this entity is a member of"
previous_revision_uuid:
type: string
description: "The uuid of previous revision dataset. Can only be set at Create/POST time."
next_revision_uuid:
type: string
readOnly: true
description: "The uuid of next revision dataset"
thumbnail_file:
readOnly: true
description: 'The dataset thumbnail file detail. Stored in db as a stringfied json, e.g., {"filename": "thumbnail.jpg", "file_uuid": "c35002f9c3d49f8b77e1e2cd4a01803d"}'
sub_status:
type: string
description: 'A sub-status provided to further define the status. The only current allowable value is "Retracted"'
retraction_reason:
type: string
description: 'Information recorded about why a the dataset was retracted.'
dbgap_sra_experiment_url:
type: string
description: 'A URL linking the dataset to the associated uploaded data at dbGaP.'
dbgap_study_url:
type: string
description: 'A URL linking the dataset to the particular study on dbGap it belongs to'
publication_date:
type: string
description: 'The date of publication'
publication_doi:
type: string
description: 'The doi of the publication. (##.####/[alpha-numeric-string])'
publication_url:
type: string
description: 'he URL at the publishers server for print/pre-print (http(s)://[alpha-numeric-string].[alpha-numeric-string].[...])'
publication_venue:
type: string
description: 'The venue of the publication, journal, conference, preprint server, etc...'
volume:
type: integer
description: 'The volume number of a journal that it was published in.'
issue:
type: integer
description: 'The issue number of the journal that it was published in.'
pages_or_article_num:
type: string
description: 'The pages or the article number in the publication journal e.g., “23”, “23-49”, “e1003424”.'
omap_doi:
type: string
description: 'A DOI pointing to an Organ Mapping Antibody Panel relevant to this publication'
associated_collection_uuid:
type: string
writeOnly: true
description: "The uuid of the associated collection for a given publication."
Collection:
type: object
properties:
created_timestamp:
type: integer
readOnly: true
description: 'The timestamp of when the node was created. The format is an integer representing milliseconds since midnight Jan 1, 1970'
created_by_user_displayname:
type: string
readOnly: true
description: 'The name of the person or process authenticated when creating the object'
created_by_user_email:
type: string
readOnly: true
description: 'The email address of the person or process authenticated when creating the object.'
created_by_user_sub:
type: string
readOnly: true
description: 'The subject id as provided by the authorization mechanism for the person or process authenticated when creating the object.'
uuid:
type: string
readOnly: true
description: 'The HuBMAP unique identifier, intended for internal software use only. This is a 32 digit hexadecimal uuid e.g. 461bbfdc353a2673e381f632510b0f17'
hubmap_id:
type: string
readOnly: true
description: 'A HuBMAP Consortium wide unique identifier randomly generated in the format HBM###.ABCD.### for every entity.'
last_modified_timestamp:
type: integer
readOnly: true
description: 'The timestamp of when the object was last modified. The format is an integer representing milliseconds since midnight, Jan 1, 1970'
last_modified_user_sub:
type: string
readOnly: true
description: 'The subject id of the user who last modified the entity as provided by the authorization mechanism for the person or process authenticated when the object was modified.'
last_modified_user_email:
type: string
readOnly: true
description: 'The email address of the person or process which authenticated when the object was last modified.'
last_modified_user_displayname:
type: string
readOnly: true
description: 'The name of the person or process which authenticated when the object was last modified.'
entity_type:
enum: ['Collection']
type: string
readOnly: true
description: 'Entity type constant'
registered_doi:
type: string
description: 'The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets.'
doi_url:
type: string
readOnly: true
description: 'The url from the doi registry for this entity. e.g. https://doi.org/10.35079/hbm289.pcbm.487'
contributors:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'A list of the people who created the entity with full name, email, ORCID iD, institution, etc.. This is analogus to the author list on a publication.'
contacts:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'A list of the people who are the main contacts to get information about the entity.'
title:
type: string
description: 'The title of the Collection'
datasets:
type: array
readOnly: true
items:
$ref: '#/components/schemas/Dataset'
description: 'The datasets that are contained in the Collection.'
examples:
DocumentExample:
summary: Example of an elasticsearch document
value:
uuid: "abcd1234ef56gh78ij90klmnop123456"
entity_type: "Sample"
sample_category: "organ"
organ: "heart"
donor:
uuid: "abcd1234ef56gh78ij90klmnop123456"
entity_type: "Donor"
ancestors:
- uuid: "abcd1234ef56gh78ij90klmnop123456"
entity_type: "Sample"
descendants:
- uuid: "abcd1234ef56gh78ij90klmnop123456"
entity_type: "Dataset"
immediate_ancestors:
- uuid: "xyz9876-5432-10dc-ba98-76543210fedc"
entity_type: "Sample"
immediate_descendants:
- uuid: "abcd1234ef56gh78ij90klmnop123456"
entity_type: "Dataset"
origin_samples:
- uuid: "abcd1234ef56gh78ij90klmnop123456"
entity_type: "Sample"
organ: "heart"
source_samples:
- uuid: "abcd1234ef56gh78ij90klmnop123456"
entity_type: "Sample"
paths:
'/indices':
get:
summary: Reindex for a given UUID of dataset. Use this method to obtain a list of valid indices within the search-api endpoint. These index names are used in some of the subsequent calls made to the endpoint.
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
indices:
example: ["entities", "portal"]
type: array
items:
type: string
'400':
description: Bad request. A JSON body and appropriate Content-Type header are required in request
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'/search':
post:
summary: Executes an Elasticsearch DSL query JSON via POST and returns hits that match the query.
parameters:
- name: produce-clt-manifest
in: query
description: An optional parameter that, when set to "true", will make the endpoint return a text representation of a manifest file that corresponds with the datasets queried rather than the original response
required: false
schema:
type: string
description: To execute a query, the POST method must provide 1) a request body that specifies an [Elasticsearch Query DSL statement](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html) 2) a bearer token in the Authorization header supplied by HuBMAP. Results are limited to those authorized by the bearer token. Uses the entities index by default.
requestBody:
description: A JSON that describes a [DSL query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). The query will likely be a compound boolean.
required: true
content:
application/json:
schema:
type: object
example: {
"query": {
"bool": {
"must": [
{
"match_phrase": {
"donor.group_name": "Vanderbilt TMC"
}
}
],
"filter": [
{
"match": {
"entity_type.keyword": "Sample"
}
}
]
}
}
}
responses:
'200':
description: Returns search hits from backend Elasticsearch that match the query defined in the request JSON
content:
application/json:
schema:
type: object
'303':
description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket. A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'404':
description: Bad request or no data found. A JSON body and appropriate Content-Type header are required in request, additionally if no data has been found based on the query when the produce-clt-manifest=true option is used.
'504':
description: There is a maximum query and response time of 30 seconds. If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.
'/{index_name}/search':
post:
summary: Executes an Elasticsearch DSL query JSON via POST and returns hits that match the query. The response is limited to hits against the specified index_name parameter. Values for index_name can be obtained by calling the /indices endpoint.
description: To execute a query, the POST method must provide 1) a request body that specifies an [Elasticsearch Query DSL statement](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html) 2) a bearer token in the Authorization header supplied by HuBMAP. Results are limited to those authorized by the bearer token. Uses the entities index by default.
parameters:
- name: index_name
in: path
description: the name of an existing Elasticsearch index (Use the /indices web service call to obtain the list of indices)
required: true
schema:
type: string
- name: produce-clt-manifest
in: query
description: An optional parameter that, when set to "true", will make the endpoint return a text representation of a manifest file that corresponds with the datasets queried rather than the original response
required: false
schema:
type: string
requestBody:
description: A JSON that describes a [DSL query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). The query will likely be a compound boolean.
required: true
content:
application/json:
schema:
type: object
example: {
"query": {
"bool": {
"must": [
{
"match_phrase": {
"donor.group_name": "Vanderbilt TMC"
}
}
],
"filter": [
{
"match": {
"entity_type.keyword": "Sample"
}
}
]
}
}
}
responses:
'200':
description: Returns search hits from backend Elasticsearch that match the query defined in the request JSON
content:
application/json:
schema:
type: object
'303':
description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket. A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
'400':
description: Bad request. A JSON body and appropriate Content-Type header are required in request
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'504':
description: There is a maximum query and response time of 30 seconds. If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.
'/param-search/{entity_type}':
get:
summary: Executes an Elasticsearch DSL query JSON via GET and returns hits that match the query.
parameters:
- name: entity_type
in: path
required: true
description: The entity type to be returned
schema:
type: string
- name: produce-clt-manifest
in: query
description: An optional parameter that, when set to "true", will make the endpoint return a text representation of a manifest file that corresponds with the datasets queried rather than the original response
required: false
schema:
type: string
description: Searches datasets based on the given parameter entity-type ('donor', 'dataset', 'sample', etc). GET method must provide a bearer token in the Authorization header supplied by HuBMAP. Results are limited to those authorized by the bearer token. For more detailed information on using this endpoint see [Detailed Param Search Docs](https://docs.hubmapconsortium.org/param-search)
responses:
'200':
description: Returns search hits from backend Elasticsearch that match the parameter
content:
application/json:
schema:
type: object
'303':
description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket. A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
'400':
description: Bad request. A valid entity-type parameter is required in request
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'504':
description: There is a maximum query and response time of 30 seconds. If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.
'/reindex/{identifier}':
put:
summary: Reindex for a given UUID of dataset
parameters:
- name: identifier
in: path
description: The unique identifier of collection. This must be a UUID.
required: true
schema:
type: string
- name: priority
in: query
description: The priority level of the reindex 1, 2, or 3; defaults to 1. 1 is the highest priority (completed first) and 3 is the lowest (completed last). Subsequent reindexes of associated entities will be enqueued at a priority level of 2 if the initial reindex was a 1. If the initial is a priority 2, the subsequent reindexes will also be priority 2. If the initial is priority 3, the subsequent reindexes will also be priority 3.
required: false
schema:
type: string
enum: ['1', '2', '3']
responses:
'202':
description: The request has been accepted and reindex is in process
'/reindex-status':
get:
summary: Retrieves a json containing information about the current reindex queue status. Including numbers in the queue at different priority levels
description: To retrieve infomration about the current state of the queue, including how many items are in each priority, use this endpoint. To view all current jobs in the queue, include the query parameter all-queued. To view all jobs currently being executed by a worker, include the parameter all-reindexing.
parameters:
- name: all-queued
in: query
description: A boolean that, when set to true, returns data about each item currently in the queue, but not items currently being reindexed (no longer in the queue).
required: false
schema:
type: string
enum: ['true', 'false']
- name: all-reindexed
in: query
description: A boolean that, when set to true, returns data about each item currently being reindexed by a worker, but not items in the queue (not yet being reindexed).
required: false
schema:
type: string
enum: ['true', 'false']
responses:
'200':
description: Returns the status data as a json describing the current state of the queue.
content:
application/json:
type: object
'500':
description: A failure has occurred retrieving the status data from the job queue.
'/reindex-status/{identifier}':
get:
summary: Retrieves a json containing information about a particularitem in the queue including its priority level, and its position in the queue.
description: To retrieve infomration about an individual entity in the queue, include either the id used when submitting the reindex request (uuid or hubmap_id) or the reference_id (returned when submitting the request) as a path variable.
parameters:
- name: identifier
in: path
description: The id of the chosen entity. Either the original id used during reindex submission (uuid or HuBMAP ID, whichever was used) or the reference_id returned when the reindex was submitted.
responses:
'200':
description: Returns the status data as a json describing the current state of the chosen entity.
content:
application/json:
type: object
'500':
description: A failure has occurred retrieving the status data from the job queue.
'/mget':
post:
summary: Retrieves multiple documents by their IDs in a single request.
description: To retrieve multiple documents by their IDs, the POST method must provide 1) a request body containing an array of document IDs in the _mget format, 2) a bearer token in the Authorization header supplied by HuBMAP. Results are limited to those authorized by the bearer token. Uses the entities index by default
requestBody:
description: A JSON object containing a docs property, which is an array of objects, each specifying an _id field corresponding to a document to be retrieved.
required: true
content:
application/json:
schema:
type: object
example: {
"docs": [
{
"_id": "abcd1234ef56gh78ij90klmnop123456"
},
{
"_id": "abcd1234ef56gh78ij90klmnop123456"
}
]
}
responses:
'200':
description: Returns search hits from backend Elasticsearch that match the query defined in the request JSON
content:
application/json:
schema:
type: object
'303':
description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket. A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'404':
description: Bad request or no data found. A JSON body and appropriate Content-Type header are required in request, additionally if no data has been found based on the query when the produce-clt-manifest=true option is used.
'504':
description: There is a maximum query and response time of 30 seconds. If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.
'/{index_name}/mget':
post:
summary: Retrieves multiple documents by their IDs in a single request.
description: To retrieve multiple documents by their IDs, the POST method must provide 1) a request body containing an array of document IDs in the _mget format, 2) a bearer token in the Authorization header supplied by HuBMAP. Results are limited to those authorized by the bearer token. Uses the entities index by default
parameters:
- name: index_name
in: path
description: the name of an existing Elasticsearch index (Use the /indices web service call to obtain the list of indices)
required: true
schema:
type: string
requestBody:
description: A JSON object containing a docs property, which is an array of objects, each specifying an _id field corresponding to a document to be retrieved.
required: true
content:
application/json:
schema:
type: object
example: {
"docs": [
{
"_id": "abcd1234ef56gh78ij90klmnop123456"
},
{
"_id": "abcd1234ef56gh78ij90klmnop123456"
}
]
}
responses:
'200':
description: Returns search hits from backend Elasticsearch that match the query defined in the request JSON
content:
application/json:
schema:
type: object
'303':
description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket. A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'404':
description: Bad request or no data found. A JSON body and appropriate Content-Type header are required in request, additionally if no data has been found based on the query when the produce-clt-manifest=true option is used.
'504':
description: There is a maximum query and response time of 30 seconds. If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.
'/mapping':
get:
summary: Exposes Elasticsearch's `_mapping` endpoint to return details regarding the default index. Defaults to using the consortium index.
description: Retrieve mapping information for the defeault index, which is consortium."
responses:
'200':
description: Returns a json containing mapping information about the default index (consortium)
content:
application/json:
schema:
type: object
'303':
description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket. A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'404':
description: Bad request or no data found. A JSON body and appropriate Content-Type header are required in request, additionally if no data has been found based on the query when the produce-clt-manifest=true option is used.
'504':
description: There is a maximum query and response time of 30 seconds. If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.
'/{index_name}/mapping':
get:
summary: Exposes Elasticsearch's `_mapping` endpoint to return details regarding the specified index.
description: Retrieve mapping information for the specified index
parameters:
- name: index_name
in: path
description: the name of an existing Elasticsearch index (Use the /indices web service call to obtain the list of indices)
required: true
schema:
type: string
responses:
'200':
description: Returns a json containing mapping information about the default index (consortium)
content:
application/json:
schema:
type: object
'303':
description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket. A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
'401':
description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
'400':
description: Bad request. Invalid index name
'403':
description: The globus token used in the `Authorization` header doesn't have the right group access permission
'404':
description: Bad request or no data found. A JSON body and appropriate Content-Type header are required in request, additionally if no data has been found based on the query when the produce-clt-manifest=true option is used.
'504':
description: There is a maximum query and response time of 30 seconds. If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.
'/update/{uuid}':
put:
summary: Update a specific document with the passed in UUID
parameters:
- name: uuid
in: path
required: true
schema:
type: string
requestBody:
description: Takes in a document that will replace the existing one
required: true
content:
application/json:
schema:
type: object
examples:
DocumentExample:
$ref: '#/components/examples/DocumentExample'
responses:
'202':
description: The request has been accepted and update is in process
'/update/{uuid}/{index}':
put:
summary: Update a specific document with the passed in UUID and index
parameters:
- name: uuid
in: path
required: true
schema:
type: string
- name: index
in: path
required: true
schema:
type: string
requestBody:
description: Takes in a document that will replace the existing one
required: true
content:
application/json:
schema:
type: object
examples:
DocumentExample:
$ref: '#/components/examples/DocumentExample'
responses:
'202':
description: The request has been accepted and update is in process
'/update/{uuid}/{index}/{scope}':
put:
summary: Update a specific document with the passed in UUID, Index, and Scope
parameters:
- name: uuid
in: path
required: true
schema:
type: string
- name: index
in: path
required: true
schema:
type: string
- name: scope
in: path
required: true
schema:
type: string
requestBody:
description: Takes in a document that will replace the existing one
required: true
content:
application/json:
schema:
type: object
examples:
DocumentExample:
$ref: '#/components/examples/DocumentExample'
responses:
'202':
description: The request has been accepted and update is in process
'/add/{uuid}':
post:
summary: Add a specific document with the passed in UUID
parameters:
- name: uuid
in: path
required: true
schema:
type: string
requestBody:
description: Takes in an object representation of a document that will be used to create a new document.
required: true
content:
application/json:
schema:
type: object
examples:
DocumentExample:
$ref: '#/components/examples/DocumentExample'
responses:
'202':
description: The request has been accepted and document creation is in process
'/add/{uuid}/{index}':
post:
summary: Create a specific document with the passed in UUID and index
parameters:
- name: uuid
in: path
required: true
schema:
type: string
- name: index
in: path
required: true
schema:
type: string
requestBody:
description: Takes in an object representation of a document that will be used to create a new document.
required: true
content:
application/json:
schema:
type: object
examples:
DocumentExample:
$ref: '#/components/examples/DocumentExample'
responses:
'202':
description: The request has been accepted and creation is in process
'/add/{uuid}/{index}/{scope}':
post:
summary: Update a specific document with the passed in UUID, Index, and Scope
parameters:
- name: uuid
in: path
required: true
schema:
type: string
- name: index
in: path
required: true
schema:
type: string
- name: scope
in: path
required: true
schema:
type: string
requestBody:
description: Takes in an object representation of a document that will be used to create a new document.
required: true
content:
application/json:
schema:
type: object
examples:
DocumentExample:
$ref: '#/components/examples/DocumentExample'
responses:
'202':
description: The request has been accepted and creation is in process
'/clear-docs/{index}':
post:
summary: Clear all docs for the given index
parameters:
- name: index
in: path
required: true
schema:
type: string
responses:
'202':
description: The request has been accepted and document clearing is in process
'/clear-docs/{index}/{uuid}':
post:
summary: Clear all docs for the given uuid within the index
parameters:
- name: index
in: path
required: true
schema:
type: string
- name: uuid
in: path
required: true
schema:
type: string
responses:
'202':
description: The request has been accepted and document clearing is in process
'/clear-docs/{index}/{uuid}/{scope}':
post:
summary: Clear all docs for the given uuid within the index and scope
parameters:
- name: index
in: path
required: true
schema:
type: string
- name: uuid
in: path
required: true
schema:
type: string
- name: scope
in: path
required: true
schema:
type: string
responses:
'202':
description: The request has been accepted and document clearing is in process
'/{index}/scroll-search':
post:
summary: Use the OpenSearch scroll API (https://opensearch.org/docs/latest/api-reference/scroll/) to open a scroll which will be navigated in the specified time when scroll_id is not provided, retrieve more results when a scroll_id is provided, and close a scroll when zero is the specified time.
parameters:
- name: index
in: path
required: true
schema:
type: string
requestBody:
description: A json body, which should at least contain 'scroll_open_minutes'
required: true
content:
application/json:
schema:
type: object
example: {
"scroll_open_minutes": 5,
"scroll_id": abc123
}
responses:
'202':
description: The request has been accepted and document clearing is in process
'400':
description: Unable to recognize scroll_open_minutes as a positive integer