search-api-spec.yaml

openapi: 3.0.0
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
              description: "One of: New|Processing|QA|Published|Error|Hold|Invalid"
        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
          description: "One of: New|Processing|QA|Published|Error|Hold|Invalid"
        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."
    requestJsonBody:
      type: object
      description: JSON that describes an Elasticsearch [DSL query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
    AssayTypeQueryDict:
      type: object
      properties:
        name:
          type: string
    AssayTypeReturnDict:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        primary:
          type: boolean
        vitessce-hints:
          type: array
          items:
            type: string
    SearchResponse:
      type: object
      description: The response from calls to /search will include objects from indices related for entities, files, or antibodies. Schema elements are documented in [entity-api](https://smart-api.info/ui/0065e419668f3336a40d1f5ab89c6ba3).
tags:
  - name: 'Search API, Elasticsearch'
    description: Operations pertaining to datasets indexed in Elasticsearch
  - name: assaytype
    description: Operations pertaining to assay types



paths:
  '/indices':
    get:
      tags:
        - indices
      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.
      operationId: get-indices
      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:
      tags:
        - search
      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 <strong>hm_consortium_entities</strong> index by default.
      operationId: search-post
      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:
              $ref: '#/components/schemas/requestJsonBody'
            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:
                  $ref: '#/components/schemas/SearchResponse'
        '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:
      tags:
        - search_by_index
      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 <strong>hm_consortium_entities</strong> index by default.
      operationId: search-post-by-index
      parameters:
        - name: index_name
          in: path
          description: the name of an existing Elasticsearch index (Use the <i>/indices</i> 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:
              $ref: '#/components/schemas/requestJsonBody'
            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:
                  $ref: '#/components/schemas/SearchResponse'
        '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:
      tags:
        - parameterized_search
      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)
      operationId: param-search-get
      responses:
        '200':
          description: Returns search hits from backend Elasticsearch that match the parameter
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/SearchResponse'
        '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:
      tags:
        - reindex
      summary: Reindex for a given UUID of dataset
      operationId: reindex
      parameters:
        - name: identifier
          in: path
          description: The unique identifier of collection.  This must be a UUID.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: The request has been accepted and reindex is in process