entity-api-spec.yaml

openapi: 3.0.0
info:
  description: 'The SenNet Entity API is a standard RESTful web service with create, update and read operations for the standard SenNet provenance graph entities.'
  version: 1.10.4
  title: SenNet Entity API
  contact:
    name: SenNet Help Desk
    email: help@sennetconsortium.org
  license:
    name: MIT License
    url: 'https://github.com/sennetconsortium/entity-api/blob/main/license.txt'
servers:
  - url: 'https://entity.api.sennetconsortium.org'
security:
  - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Globus Bearer token to authorize requests
  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.
    SourceMetadata:
      type: object
      properties:
        code:
          type: string
          description: "This is a Code from a source vocabulary in the SenNet Knowledge Graph, currently limited to UMLS source vocabulary terms."
        sab:
          type: string
          description: "This is the source vocabulary in the SenNet Knowledge Graph.  Currently limited to UMLS source vocabularies."
        concept_id:
          type: string
          description: "This is the Concept ID from the SenNet 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 SenNet 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 SenNet 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 SenNet 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 SenNet 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 source-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 source-level data). An empty of zero value designates missing data or that this field is not applicable for the concept"
    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 SenNet unique identifier for the file.

    Source:
      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 SenNet unique identifier, intended for internal software use only. This is a 32 digit hexadecimal uuid e.g. 461bbfdc353a2673e381f632510b0f17
        sennet_id:
          type: string
          readOnly: true
          description: A SenNet Consortium wide unique identifier randomly generated in the format SNT###.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, Source, Upload'
        registered_doi:
          type: string
          description: The doi of a the registered entity. e.g. 10.35079/snt289.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/snt289.pcbm.487
        creators:
          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.
        description:
          type: string
          description: Free text description of the source
        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.
        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"]'
        lab_source_id:
          type: string
          description: A lab specific identifier for the source.
        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 Source 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 source
        source_type:
          type: string
          enum:
            - Human
            - Human Organoid
            - Mouse
            - Mouse Organoid
          description: "A high level description of where this source originates from. Valid values found in: [source types](https://ontology.api.hubmapconsortium.org/valueset?parent_sab=SENNET&parent_code=C050020&child_sabs=SENNET)"

    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 SenNet unique identifier, intended for internal software use only. This is a 32 digit hexadecimal UUID e.g. 461bbfdc353a2673e381f632510b0f17
        sennet_id:
          type: string
          readOnly: true
          description: A SenNet Consortium wide unique identifier randomly generated in the format SNT###.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, Source'
        registered_doi:
          type: string
          description: The doi of a the registered entity. e.g. 10.35079/snt289.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/snt289.pcbm.487
        creators:
          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.
        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.'
        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 Source 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
        sample_category:
          type: string
          enum:
            - Block
            - Organ
            - Section
            - Suspension
          description: "The category of the sample. Valid values found in: [sample categories](https://ontology.api.hubmapconsortium.org/valueset?parent_sab=SENNET&parent_code=C020076&child_sabs=SENNET)"
        organ:
          type: string
          enum:
            - UBERON:0001013  # Adipose Tissue
            - UBERON:0000178  # Blood
            - UBERON:0001474  # Bone
            - UBERON:0002371  # Bone Marrow
            - UBERON:0000955  # Brain
            - UBERON:0000948  # Heart
            - UBERON:0004538  # Kidney (Left)
            - UBERON:0004539  # Kidney (Right)
            - UBERON:0000059  # Large Intestine
            - UBERON:0002107  # Liver
            - UBERON:0002168  # Lung (Left)
            - UBERON:0002167  # Lung (Right)
            - UBERON:0000029  # Lymph Node 
            - UBERON:0001911  # Mammary Gland
            - FMA:57991  # Mammary Gland (Left)
            - FMA:57987  # Mammary Gland (Right)
            - UBERON:0005090  # Muscle
            - UBERON:0010000  # Other
            - UBERON:0002119  # Ovary (Left)
            - UBERON:0002118  # Ovary (Right)
            - UBERON:0001264  # Pancreas
            - UBERON:0001987  # Placenta
            - UBERON:0002097  # Skin
            - UBERON:0002240  # Spinal Cord
            - UBERON:0002106  # Spleen
            - UBERON:0002370  # Thymus
            - FMA:54974  # Tonsil (Left)
            - FMA:54973  # Tonsil (Right)
            - UBERON:0003126  # Trachea
          description: "Organ code specifier, only set if sample_type == organ. Valid values found in: [organ types](https://ontology.api.hubmapconsortium.org/organs?application_context=sennet)"
        organ_other:
          type: string
          description: The organ type provided by the user if "other" organ type is selected
        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 Source or Sample.  If the direct ancestor is a Source, 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).
        lab_tissue_sample_id:
          type: string
          description: Lab specific id for the sample.
        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 source/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"]'
        metadata_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_files_to_add:
          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"}]}'
        metadata_files_to_remove:
          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.
        uuid:
          type: string
          readOnly: true
          description: The SenNet unique identifier, intended for internal software use only. This is a 32 digit hexadecimal UUID e.g. 461bbfdc353a2673e381f632510b0f17
        sennet_id:
          type: string
          readOnly: true
          description: A SenNet Consortium wide unique identifier randomly generated in the format SNT###.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, Source'
        registered_doi:
          type: string
          description: The doi of a the registered entity. e.g. 10.35079/snt289.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/snt289.pcbm.487
        creators:
          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.
        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.
        dataset_type:
          type: string
          enum:
            - Visium
            - seqFISH
            - RNAseq
            - ATACseq
            - 10X Multiome
            - SNARE-seq2
            - CODEX
            - PhenoCycler
            - CyCIF
            - MERFISH
            - Cell Dive
            - Histology
            - MALDI
            - SIMS
            - DESI
            - MIBI
            - 2D Imaging Mass Cytometry
            - LC-MS
            - nanoSPLITS
            - Auto-fluorescence
            - Light Sheet
            - Confocal
            - Thick section Multiphoton MxIF
            - Second Harmonic Generation (SHG)
            - Enhanced Stimulated Raman Spectroscopy (SRS)
            - Molecular Cartography
            - DARTfish
            - WGS
            - 3D Imaging Mass Cytometry
          description: The data or assay type contained in this dataset.
        collections:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/Collection'
          description: A list of collections that this dataset belongs to.
        upload:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/Upload'
          description: "The Data Upload that this dataset is associated with."
        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.
        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 Source 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"}'
        thumbnail_file_to_add:
          writeOnly: true
          type: string
          format: temp_file_id
          description: Just a temporary file id. Provide as a json object with an temp_file_id like {"temp_file_id":"dzevgd6xjs4d5grmcp4n"}
        thumbnail_file_to_remove:
          writeOnly: true
          type: string
          format: file_uuid
          description: 'The thumbnail image file previously uploaded to delete. Provide as a string of the file_uuid like: "c35002f9c3d49f8b77e1e2cd4a01803d"'
        creation_action:
          type: string
          description: 'The associated action that represents the creation of that dataset'
        intended_dataset_type:
          type: string
          description: 'The dataset type of the intended datasets that will be uploaded as part of the Upload.'
        intended_organ:
          type: string
          description: 'The organ code representing the organ type that the data contained in the upload will be registered/associated with.'

    Upload:
      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 SenNet unique identifier, intended for internal software use only. This is a 32 digit hexadecimal UUID e.g. 461bbfdc353a2673e381f632510b0f17
        sennet_id:
          type: string
          readOnly: true
          description: A SenNet Consortium wide unique identifier randomly generated in the format SNT###.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, Source, Upload'
        description:
          type: string
          description: Free text description of the data being submitted.
        title:
          type: string
          description: Title of the datasets, a sentance or less
        status:
          type: string
          description: 'One of: New|Valid|Invalid|Error|Submitted'
        validation_message:
          type: string
          description: A message from the validataion tools describing what is invalid with the upload.
        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 Source 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
        dataset_uuids_to_link:
          type: array
          items:
            type: string
          writeOnly: true
          description: 'List of datasets to add to the Upload. Provide as a json array of the dataset UUIDs like: ["232934234234234234234270c0ea6c51d604a850558ef2247d0b4", "230948203482234234234a57bfe9c056d08a0f8e6cd612baa3bfa"]'
        dataset_uuids_to_unlink:
          type: array
          items:
            type: string
          writeOnly: true
          description: 'List of datasets to remove from a Upload. Provide as a json array of the dataset UUIDs like: ["232934234234234234234270c0ea6c51d604a850558ef2247d0b4", "230948203482234234234a57bfe9c056d08a0f8e6cd612baa3bfa"]'
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/Dataset'
          readOnly: true
          description: The datasets that are contained in this Upload.

    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 SenNet unique identifier, intended for internal software use only. This is a 32 digit hexadecimal UUID e.g. 461bbfdc353a2673e381f632510b0f17
        sennet_id:
          type: string
          readOnly: true
          description: A SenNet Consortium wide unique identifier randomly generated in the format SNT###.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, Source'
        registered_doi:
          type: string
          description: The doi of a the registered entity. e.g. 10.35079/snt289.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/snt289.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.

    Instanceof:
      type: object
      description: "Returned by /entities/type/{type_a}/instanceof/{type_b}"
      properties:
        instanceof:
          type: boolean
          description: "True of False depending on whether the Entity id is an instance of the type"

paths:
  /entities/{id}:
    get:
      tags:
        - entities
      summary: Retrieve a provenance entity by id. Entity types of Source, Sample, Dataset, and Upload.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID (32 digit hexadecimal number)
          required: true
          schema:
            type: string
        - name: exclude
          in: query
          description: The properties to not be included in the JSON response of the entity.
          required: false
          schema:
            type: string
        - name: property
          in: query
          description: Specifies a single property to be returned from the entity JSON.
          required: false
          schema:
            type: string
            enum:
              - 'data_access_level'
              - 'status'
      responses:
        '200':
          description: The json of the **[Source](http://somewhere.org)**, **[Sample](http://somewhere.org)**, **[Dataset](http://somewhere.org)**, or **[Upload](http://somewhere.org)**
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Source'
                  - $ref: '#/components/schemas/Sample'
                  - $ref: '#/components/schemas/Dataset'
                  - $ref: '#/components/schemas/Upload'
        '400':
          description: Invalid or misformatted entity identifier was provided.
        '401':
          description: The user's bearer token has expired or the user did not supply a valid token.
        '403':
          description: The user is not authorized to retrieve the referenced entity.
        '404':
          description: The target entity could not be found.
        '500':
          description: An unexpected error occurred.
    put:
      tags:
        - entities
      summary: Update the properties of a given Source, Sample, Dataset or Upload
      parameters:
        - name: id
          in: path
          description: The SenNet ID (e.g. SNT123.ABCD.456) or UUID of target entity
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Source'
                - $ref: '#/components/schemas/Sample'
                - $ref: '#/components/schemas/Dataset'
                - $ref: '#/components/schemas/Upload'
      responses:
        '200':
          description: The entity was successfully updated and is returned
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Source'
                  - $ref: '#/components/schemas/Sample'
                  - $ref: '#/components/schemas/Dataset'
                  - $ref: '#/components/schemas/Upload'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entity-types:
    get:
      tags:
        - entities types
      summary: Get a list of all the available entity types defined in the schema yaml
      responses:
        '200':
          description: An array of entity types is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to use this method
        '500':
          description: Internal error

  /ancestors/{id}:
    get:
      tags:
        - ancestors
      summary: Get the ancestor list for an Entity. The ancestors are the nodes connected "upstream" from the current node. This list traverses all the levels in the graph.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An array of ancestors is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Source'
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error
    post:
      tags:
        - ancestors
      summary: Get the ancestor list for an Entity. The ancestors are the nodes connected "upstream" from the current node. This list traverses all the levels in the graph.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with "filter_properties" (a list of properties to include or exclude) and "is_include"
          (a boolean value for if the list provided is inclusion or exclusion).
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_properties:
                  type: array
                  items:
                    type: string
                  description: A list of properties to include or exclude
                is_include:
                  type: boolean
                  description: Used to determine if the list provided is inclusion or exclusion
      responses:
        '200':
          description: An array of ancestors is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Source'
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /descendants/{id}:
    get:
      tags:
        - descendants
      summary: Get the descendant list for an Entity. The descendants are the nodes "downstream" from the current node.  This list traverses all the levels in the graph. Returns all descendants as an array of Entities.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An array of descendants is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error
    post:
      tags:
        - descendants
      summary: Get the descendant list for an Entity. The descendants are the nodes "downstream" from the current node.  This list traverses all the levels in the graph. Returns all descendants as an array of Entities.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with "filter_properties" (a list of properties to include or exclude) and "is_include"
          (a boolean value for if the list provided is inclusion or exclusion).
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_properties:
                  type: array
                  items:
                    type: string
                  description: A list of properties to include or exclude
                is_include:
                  type: boolean
                  description: Used to determine if the list provided is inclusion or exclusion
      responses:
        '200':
          description: An array of ancestors is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /parents/{id}:
    get:
      tags:
        - parents
      summary: Get the immediate parent list for an Entity. The parents are the nodes connected one level "upstream" from the current node.  This list only goes to the next higher level in the graph.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An array of parent entities is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Source'
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error
    post:
      tags:
        - parents
      summary: Get the immediate parent list for an Entity. The parents are the nodes connected one level "upstream" from the current node.  This list only goes to the next higher level in the graph.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with "filter_properties" (a list of properties to include or exclude) and "is_include"
          (a boolean value for if the list provided is inclusion or exclusion).
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_properties:
                  type: array
                  items:
                    type: string
                  description: A list of properties to include or exclude
                is_include:
                  type: boolean
                  description: Used to determine if the list provided is inclusion or exclusion
      responses:
        '200':
          description: An array of ancestors is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Source'
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /children/{id}:
    get:
      tags:
        - children
      summary: Get the list of children directly connected to an Entity. The children are the nodes one level below the current node. This list only returns the items one level below in the graph.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An array of children entities is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error
    post:
      tags:
        - children
      summary: Get the list of children directly connected to an Entity. The children are the nodes one level below the current node. This list only returns the items one level below in the graph.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with "filter_properties" (a list of properties to include or exclude) and "is_include"
          (a boolean value for if the list provided is inclusion or exclusion).
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_properties:
                  type: array
                  items:
                    type: string
                  description: A list of properties to include or exclude
                is_include:
                  type: boolean
                  description: Used to determine if the list provided is inclusion or exclusion
      responses:
        '200':
          description: An array of ancestors is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/{id}/siblings:
    get:
      tags:
        - entities
      summary: Get the siblings list for an Entity.  The siblings have the same direct ancestor.  This list does not include all nodes whom have common ancestors, only the direct ancestor.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
        - name: include-old-revisions
          in: query
          description: A case insensitive string. Any value besides true will have no effect. If the string is 'true', datasets that are have newer revisions will be included, otherwise by default they are not included.
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: status
          in: query
          description: A case insensitive string. Any value besides 'new', 'qa', and 'published' will raise an error. If a valid status is provided, only results matching that status (if they are datasets) will be returned
          required: false
          schema:
            type: string
            enum:
              - 'new'
              - 'qa'
              - 'published'
        - name: property_key
          in: query
          description: A case insensitive string. Any value besides 'uuid' will raise an error. If property_key=uuid is provided, rather than entire dictionary representations of each node, only the list of matching uuid's will be returned
          required: false
          schema:
            type: string
            enum: 
              - 'uuid'
      responses:
        '200':
          description: An array of sibling entities is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/{id}/tuplets:
    get:
      tags:
        - entities
      summary: Get the tuplets list for an Entity.  The tuplets have the same parent activity node.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: A case insensitive string. Any value besides 'new', 'qa', and 'published' will raise an error. If a valid status is provided, only results matching that status (if they are datasets) will be returned
          required: false
          schema:
            type: string
            enum:
              - 'new'
              - 'qa'
              - 'published'
        - name: property_key
          in: query
          description: A case insensitive string. Any value besides 'uuid' will raise an error. If property_key=uuid is provided, rather than entire dictionary representations of each node, only the list of matching uuid's will be returned
          required: false
          schema:
            type: string
            enum:
              - 'uuid'
      responses:
        '200':
          description: An array of tuplet entities is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/{id}/provenance:
    get:
      tags:
        - entities
      summary: Get Provenance Data for Entity. This returns a PROV JSON compliant representation of the entity's provenance. Refer to this document for more information regarding [PROV JSON format](https://www.w3.org/Submission/2013/SUBM-prov-json-20130424/)
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
        - name: filter
          in: query
          description: Determines which node labels are allowed or not allowed to be returned in the provenance result. Formatting of filter follows the syntax of 'labelFilter' config param of the neo4j subgraph method. (e.g. -Publication|-Collection)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json: {}
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the provenance of the given entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/type/{type_a}/instanceof/{type_b}:
    get:
      tags:
        - entities
      summary: Determines if the Entity type type_a is an instance of type_b
      parameters:
        - name: type_a
          in: path
          description: The unique identifier of entity (e.g. Published)
          required: true
          schema:
            type: string
        - name: type_b
          in: path
          description: The Entity Type Class as defined in entity-api-spec.yaml (e.g. Dataset)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An object with the attribute 'instanceof' that has a value of either 'true' of 'false'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instanceof'
        '400':
          description: Invalid or misformatted entity identifie
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to retrieve the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/{id}/ancestor-organs:
    get:
      tags:
        - entities
      summary: Retrieve a list of ancestor organ(s) of a given UUID
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An array of Samples (sub-type organ) are returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sample'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to retrieve the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/{entity_type}:
    post:
      tags:
        - entities
      summary: Create a new entity of the target type
      parameters:
        - name: entity_type
          in: path
          description: 'One of the target entity types (case-insensitive since will be normalized): Source, Sample, Dataset, Upload'
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Source'
                - $ref: '#/components/schemas/Sample'
                - $ref: '#/components/schemas/Dataset'
                - $ref: '#/components/schemas/Upload'
      responses:
        '200':
          description: The entity was successfully created and is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Source'
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
                    - $ref: '#/components/schemas/Upload'
        '400':
          description: Invalid entity type provided
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to create the entity
        '500':
          description: Internal error

  /entities/multiple-samples/{count}:
    post:
      tags:
        - entities
      summary: Create multiple samples from the same source entity. 'count' samples will be generated each with individual UUIDs and SenNet IDs.
      parameters:
        - name: count
          in: path
          description: The number of samples to be created
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The samples were successfully created. An array of objects each containing a UUID and SenNet ID associated with each newly created sample.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sennet_id:
                      type: string
                    uuid:
                      type: string
        '400':
          description: Invalid json input
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '500':
          description: Internal error

  /doi/redirect/{id}:
    get:
      tags:
        - doi
      summary: Redirect a request from a doi service
      parameters:
        - name: id
          in: path
          description: The SenNet ID (e.g. SNT123.ABCD.456) or UUID of the target collection
          required: true
          schema:
            type: string
      responses:
        '307':
          description: Redirect to the entities landing page
        '400':
          description: Invalid or misformatted collection identifier
        '500':
          description: Internal error

  /entities/{id}/globus-url:
    get:
      tags:
        - entities
      summary: Get the Globus URL to the given Dataset or Upload entity
      parameters:
        - name: id
          in: path
          description: The ID (e.g. SNT123.ABCD.456) or UUID of the given entity
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns the Globus service URL pointing to the Dataset or Upload data is returned
          content:
            text/plain:
              schema:
                type: string
                format: url
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the data
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/{id}/pipeline-message:
    get:
      tags:
        - entities
      summary: Get the pipeline message for the given Dataset
      parameters:
        - name: id
          in: path
          description: The ID (e.g. SNT123.ABCD.456) or UUID of the given entity
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns the pipeline message for the given Dataset
          content:
            text/plain:
              schema:
                type: string
                format: text
        '400':
          description: Invalid or misformatted entity identifier or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the data
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /entities/{id}/validation-message:
    get:
      tags:
        - entities
      summary: Get the validation message for the given Upload
      parameters:
        - name: id
          in: path
          description: The ID (e.g. SNT123.ABCD.456) or UUID of the given entity
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns the validation message for the given Upload
          content:
            text/plain:
              schema:
                type: string
                format: text
        '400':
          description: Invalid or misformatted entity identifier or the given entity is not an Upload
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the data
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /datasets/{id}/latest-revision:
    get:
      tags:
        - datasets
      summary: Retrieve the latest (newest) revision of a given Dataset. Public/Consortium access rules apply - if no token/consortium access then must be for a public dataset and the returned Dataset must be the latest public version. If the given dataset itself is the latest revision, meaning it has no next revisions, this dataset gets returned.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the latest revision of the given dataset.
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error

  /datasets/{id}/revision:
    get:
      tags:
        - datasets
      summary: Retrieve the calculated revision number of a Dataset. The calculated revision is number is based on the [:REVISION_OF] relationships to the oldest dataset in a revision chain. Where the oldest dataset = 1 and each newer version is incremented by one (1, 2, 3 ...). Public/Consortium access rules apply, if is for a non-public dataset and no token or a token without membership in SenNet-Read group is sent with the request then a 403 response should be returned.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The revision number (integer) on successful operation
        '400':
          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the revision number of the given dataset.
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error

  /datasets/{id}/revisions:
    get:
      tags:
        - datasets
      summary: From a given ID of a versioned dataset, retrieve a list of every dataset in the chain ordered from most recent to oldest. The revision number, as well as the dataset UUID will be included. An optional parameter ?include_dataset=true will include the full dataset for each revision as well. Public/Consortium access rules apply, if is for a non-public dataset and no token or a token without membership in SenNet-Read group is sent with the request then a 403 response should be returned. If the given id is published, but later revisions are not and the user is not in SenNet-Read group, only published revisions will be returned. The field next_revision_uuid will not be returned if the next revision is unpublished
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
        - name: include_dataset
          in: query
          description: A case insensitive string. Any value besides true will have no effect. If the string is 'true', the full dataset for each revision will be included in the response
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
      responses:
        '200':
          description: The list of revised datasets that the referenced dataset is a member of including the index number of the revision, where 1 is the oldest version of any revision chain
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    description: The uuid of a dataset
                  revision_number:
                    type: integer
                    description: The number in the revision chain of this dataset where 1 is the oldest revision
                  dataset:
                    $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the revision number of the given dataset.
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error

  /datasets/{id}/retract:
    put:
      tags:
        - datasets
      summary: 'Retracts a dataset after it has been published. Requires a json body with a single field {retraction_reason: string}. The dataset for the given id is modified to include this new retraction_reason field and sets the dataset property sub_status to Retracted. The complete modified dataset is returned. Requires that the dataset being retracted has already been published (dataset.status == Published. Requires a user token with membership in the SenNet-Data-Admin group otherwise then a 403 will be returned.'
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either a SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with a single, required retraction_reason parameter contianing the reason why the dataset is being retracted.
        content:
          application/json:
            schema:
              type: object
              properties:
                retraction_reason:
                  type: string
                  description: Free text describing why the dataset was retracted
      responses:
        '200':
          description: The complete dataset with modified sub_status and retraction_reason
        '400':
          description: Invalid or misformatted entity identifier, the given entity is not a Dataset, is not published or the required retraction_reason was not included in a json body
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the retract the given dataset. The user must be a member of the SenNet-Data-Admin group
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error

  /datasets/prov-info:
    get:
      tags:
        - datasets
      summary: Returns ALL provenance information for ALL datasets in a default table/tsv format or optionally a json format when an optional ?format=json parameter is provided
      parameters:
        - name: format
          in: query
          description: A case insensitive string. Any value besides 'json' will have no effect. If the string is 'json', provenance info will be returned as a json. Otherwise, it will be returned as a tsv file
          required: false
          schema:
            type: string
            enum:
              - json
              - tsv
        - name: group_uuid
          in: query
          description: The UUID of the group
          required: false
          schema:
            type: string
        - name: has_rui_info
          in: query
          description: A case insensitive string. Any value besides true or false will cause a 400 exception.
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: organ
          in: query
          description: Case insensitive string for 2 character organ code. Values must be present on organ yaml or a 400 exception is raised
          required: false
          schema:
            type: string
        - name: dataset_status
          in: query
          description: Case insensitive string indicating the current status of a dataset
          required: false
          schema:
            type: string
            enum:
              - qa
              - new
              - published
      responses:
        '200':
          description: All provenance information for every dataset in the database either as a json list or as a tsv file to be downloaded
          content:
            text/tsv:
              schema:
                type: string
            application/json:
              schema:
                type: object
                properties:
                  dataset_uuid:
                    type: string
                    description: The UUID of the dataset
                  dataset_sennet_id:
                    type: string
                    description: The SenNet ID of the dataset like SNT123.ABCD.456
                  dataset_status:
                    type: string
                    description: The status of the dataset New, QA, Published, etc ...
                  dataset_group_name:
                    type: string
                    description: The name of the data provider group who created the dataset
                  dataset_group_uuid:
                    type: string
                    description: The internal id for the data provider group
                  dataset_date_time_created:
                    type: string
                    description: The date/time that the dataset was created
                  dataset_created_by_email:
                    type: string
                    description: The email address of the person who created the dataset
                  dataset_date_time_modified:
                    type: string
                    description: The date/time that the dataset was last modified
                  dataset_modified_by_email:
                    type: string
                    description: The email address of the person who last modified the dataset
                  dataset_lab_id:
                    type: string
                    description: The identifier used by the data provider
                  dataset_data_types:
                    type: string
                    description: The data/assay types (can be multiple types for pipeline derived data, so a comma separated list for tsv output or a json array for json output)
                  dataset_portl_url:
                    type: string
                    description: The url to open the dataset in the data portal
                  first_sample_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the tissue sample nearest to this dataset in the provenance chain
                  first_sample_submission_id:
                    type: array
                    items:
                      type: string
                      description: The Submission ID of the tissue sample nearest to this dataset in the provenance chain
                  first_sample_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the tissue sample nearest to this dataset in the provenance chain
                  first_sample_type:
                    type: array
                    items:
                      type: string
                      description: The tissue type of the sample nearest to this dataset in the provenance chain
                  first_sample_portal_url:
                    type: array
                    items:
                      type: string
                      description: The URL to the data portal for this sample nearest to this dataset in the provenance chain
                  organ_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the organ associated to this dataset in the provenance chain
                  organ_submission_id:
                    type: array
                    items:
                      type: string
                      description: The submission ID of the organ associated to this dataset in the provenance chain
                  organ_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the organ associated to this dataset in the provenance chain
                  organ_type:
                    type: array
                    items:
                      type: string
                      description: The organ type of the organ associated to this dataset in the provenance chain (return the organ code resolved to the organ name via the organ.yaml file)
                  source_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the source associated to this dataset in the provenance chain
                  source:submission_id:
                    type: array
                    items:
                      type: string
                      description: The Submission ID of the source associated to this dataset in the provenance chain
                  source_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the source associated to this dataset in the provenance chain
                  source_group_name:
                    type: array
                    items:
                      type: string
                      description: The name of the SenNet group where this source originated (resolved to the group name from the group_uuid property resolved to displayname via the groups mapping file
                  rui_location_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the tissue sample that contains RUI location json for this dataset
                  rui_location_submission_id:
                    type: array
                    items:
                      type: string
                      description: The Submission ID of the tissue sample that contains RUI location json for this dataset
                  rui_location_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the tissue sample that contains RUI location json for this dataset
                  sample_metadata_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of tissue sample(s) containing sample metadata
                  sample_metadata_submission_id:
                    type: array
                    items:
                      type: string
                      description: The Submission ID of the tissue sample(s) containing sample metadata
                  sample_metadata_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the tissue sample(s) containing sample metadata
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to use this method
        '500':
          description: Internal error

  /datasets/{id}/prov-info:
    get:
      tags:
        - datasets
      summary: Returns ALL provenance information for a single dataset in a default table/tsv format or optionally a json format when an optional ?format=json parameter is provided
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID (32 digit hexadecimal number)
          required: true
          schema:
            type: string
        - name: format
          in: query
          description: A case insensitive string. Any value besides 'json' will have no effect. If the string is 'json', provenance info will be returned as a json. Otherwise, it will be returned as a tsv file
          required: false
          schema:
            type: string
            enum:
              - json
              - tsv
      responses:
        '200':
          description: All provenance information for the given dataset either as a json list or as a tsv file to be downloaded
          content:
            text/tsv:
              schema:
                type: string
            application/json:
              schema:
                type: object
                properties:
                  dataset_uuid:
                    type: string
                    description: The UUID of the dataset
                  dataset_sennet_id:
                    type: string
                    description: The SenNet ID of the dataset like SNT123.ABCD.456
                  dataset_status:
                    type: string
                    description: All status of the dataset New, QA, Published, etc ...
                  dataset_group_name:
                    type: string
                    description: The name of the data provider group who created the dataset
                  dataset_group_uuid:
                    type: string
                    description: The internal id for the data provider group
                  dataset_date_time_created:
                    type: string
                    description: The date/time that the dataset was created
                  dataset_created_by_email:
                    type: string
                    description: The email address of the person who created the dataset
                  dataset_date_time_modified:
                    type: string
                    description: The date/time that the dataset was last modified
                  dataset_modified_by_email:
                    type: string
                    description: The email address of the person who last modified the dataset
                  dataset_lab_id:
                    type: string
                    description: Identifier used by the data provider
                  dataset_data_types:
                    type: string
                    description: The data/assay types (can be multiple types for pipeline derived data, so a comma separated list for tsv output or a json array for json output)
                  dataset_portl_url:
                    type: string
                    description: The url to open the dataset in the data portal
                  first_sample_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the tissue sample nearest to this dataset in the provenance chain
                  first_sample_submission_id:
                    type: array
                    items:
                      type: string
                      description: The Submission ID of the tissue sample nearest to this dataset in the provenance chain
                  first_sample_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the tissue sample nearest to this dataset in the provenance chain
                  first_sample_type:
                    type: array
                    items:
                      type: string
                      description: The tissue type of the sample nearest to this dataset in the provenance chain
                  first_sample_portal_url:
                    type: array
                    items:
                      type: string
                      description: The URL to the data portal for this sample nearest to this dataset in the provenance chain
                  organ_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the organ associated to this dataset in the provenance chain
                  organ_submission_id:
                    type: array
                    items:
                      type: string
                      description: The submission ID of the organ associated to this dataset in the provenance chain
                  organ_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the organ associated to this dataset in the provenance chain
                  organ_type:
                    type: array
                    items:
                      type: string
                      description: The organ type of the organ associated to this dataset in the provenance chain (return the organ code resolved to the organ name via the organ.yaml file)
                  source_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the source associated to this dataset in the provenance chain
                  source:submission_id:
                    type: array
                    items:
                      type: string
                      description: The submission ID of the source associated to this dataset in the provenance chain
                  source_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the source associated to this dataset in the provenance chain
                  source_group_name:
                    type: array
                    items:
                      type: string
                      description: The name of the SenNet group where this source originated (resolved to the group name from the group_uuid property resolved to displayname via the groups mapping file
                  rui_location_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of the tissue sample that contains RUI location json for this dataset
                  rui_location_submission_id:
                    type: array
                    items:
                      type: string
                      description: The Submission ID of the tissue sample that contains RUI location json for this dataset
                  rui_location_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the tissue sample that contains RUI location json for this dataset
                  sample_metadata_sennet_id:
                    type: array
                    items:
                      type: string
                      description: The SenNet ID of tissue sample(s) containing sample metadata
                  sample_metadata_submission_id:
                    type: array
                    items:
                      type: string
                      description: The Submission ID of the tissue sample(s) containing sample metadata
                  sample_metadata_uuid:
                    type: array
                    items:
                      type: string
                      description: The UUID of the tissue sample(s) containing sample metadata
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to use this method
        '500':
          description: Internal error

  /samples/prov-info:
    get:
      tags:
        - samples
      summary: Returns all provenance information for a each sample in a json format
      parameters:
        - name: group_uuid
          in: query
          description: The UUID of the group
          required: false
          schema:
            type: string
      responses:
        '200':
          description: All provenance information for the every sample given as a json list
          content:
            application/json:
              schema:
                type: object
                properties:
                  sample_uuid:
                    type: string
                    description: The UUID of the sample
                  sample_group_name:
                    type: string
                    description: The name of the data provider group who created the sample
                  sample_created_by_email:
                    type: string
                    description: The email address of the person who created the sample
                  lab_tissue_sample_id:
                    type: string
                    description: The identifier used by the data provider
                  sample_ancestor_id:
                    type: string
                    description: The UUID of the source or sample nearest to this dataset in the provenance chain
                  sample_ancestor_entity:
                    type: string
                    description: The entity type of the nearest ancestor to the sample. Will be a source or another sample
                  organ_uuid:
                    type: string
                    description: The UUID of the organ associated to this sample in the provenance chain. If the sample is itself an organ, the id will be the same as sample UUID.
                  organ_type:
                    type: string
                    description: The organ type of the organ associated to this sample in the provenance chain (return the organ code resolved to the organ name via the organ.yaml file)
                  source_uuid:
                    type: string
                    description: The UUID of the source associated to this sample in the provenance chain
                  sample_has_rui_info:
                    type: boolean
                    description: True or false value corresponding to whether the sample has rui_location info.
                  sample_has_metadata:
                    type: string
                    description: True or false value corresponding to whether the sample has metadata info
                  organ_has_metadata:
                    type: string
                    description: True or false value corresponding to whether the organ has metadata info
                  source_has_metadata:
                    type: string
                    description: True or false value corresponding to whether the source has metadata info
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to use this method
        '500':
          description: Internal error

  /datasets/components:
    post:
      tags:
        - datasets
      summary: Create multiple component datasets from a single Multi-Assay ancestor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                creation_action:
                  type: string
                  description: The action event that will describe the activity node. Allowed values are "Multi-Assay Split"
                group_uuid:
                  type: string
                  description: The group UUID for the new component datasets
                direct_ancestor_uuids:
                  type: string
                  description: The UUID for the parent multi assay dataset
                datasets:
                  type: array
                  items:
                    $ref: '#/components/schemas/Dataset'
      responses:
        '200':
          description: The entities were successfully created and are returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid input.
        '404':
          description: Not found. No matching datasets were found, or the none were found that the user is authorized to see.
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The given dataset is unpublished and the user does not have the authorization to view it.
        '500':
          description: Internal error

  /datasets/{id}/organs:
    get:
      tags:
        - datasets
      summary: Retrieve a list of all of the samples that are organs that are associated with the dataset id
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of entity_type == Sample with sample_category == organ associated with the dataset id
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sample'
        '400':
          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the revision number of the given dataset.
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error

  /datasets/{id}/samples:
    get:
      tags:
        - datasets
      summary: Retrieve a list of all of the samples that are not organs that are associated with the dataset id
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of entity_type == Sample with sample_category != organ associated with the dataset id
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sample'
        '400':
          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the revision number of the given dataset.
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error

  /datasets/{id}/sources:
    get:
      tags:
        - datasets
      summary: Retrieve a list of all of the sources that are associated with the dataset id
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of entity_type == Source that are associated with the dataset id
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Source'
        '400':
          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the revision number of the given dataset.
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error

  /entities/{id}/uploads:
    get:
      tags:
        - uploads
      summary: Get the list of all uploads the Entity belongs to.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
        - name: property
          in: query
          description: A case insensitive string. Any value besides 'uuid' will raise an error. If property=uuid is provided, rather than entire dictionary representations of each node, only the list of matching uuid's will be returned
          required: false
          schema:
            type: string
            enum: [ 'uuid' ]
      responses:
        '200':
          description: An array of upload entities is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Upload'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /uploads/{id}/datasets:
    get:
      tags:
        - uploads
      summary: Retrieve a list of all of the datasets that are associated with the upload id
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of entity_type == Dataset that are associated with the upload id
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to query the revision number of the given dataset.
        '404':
          description: The target dataset could not be found
        '500':
          description: Internal error
    post:
      tags:
        - uploads
      summary: Retrieve a list of all of the datasets that are associated with the upload id
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with "filter_properties" (a list of properties to include or exclude) and "is_include"
          (a boolean value for if the list provided is inclusion or exclusion).
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_properties:
                  type: array
                  items:
                    type: string
                  description: A list of properties to include or exclude
                is_include:
                  type: boolean
                  description: Used to determine if the list provided is inclusion or exclusion
      responses:
        '200':
          description: An array of ancestors is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'

        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error


  /entities/dashboard/{entity_type}:
    put:
      tags:
        - entities
      summary: Retrieve specific fields for either Sources or Samples given a list of either SenNet IDs or UUIDs for the dashboard in the Data Sharing Portal
      parameters:
        - name: entity_type
          in: path
          description: One of the normalized entity types either Sample or Source
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with a single, required entity_uuids parameter containing a list of entity UUIDs
        content:
          application/json:
            schema:
              type: object
              properties:
                entity_ids:
                  type: string
                  description: List of entity UUIDs
      responses:
        '200':
          description: A list of objects containing only specific fields required for the dashboard in the Data Sharing Portal
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Invalid or misformatted entity identifier was provided.
        '401':
          description: The user's bearer token has expired or the user did not supply a valid token.
        '403':
          description: The user is not authorized to retrieve the referenced entity.
        '404':
          description: The target entity could not be found.
        '500':
          description: An unexpected error occurred.

  /entities/{id}/collections:
    get:
      tags:
        - collections
      summary: Get the list of all collections the Entity belongs to.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. HBM123.ABCD.456) or UUID
          required: true
          schema:
            type: string
        - name: property
          in: query
          description: A case insensitive string. Any value besides 'uuid' will raise an error. If property=uuid is provided, rather than entire dictionary representations of each node, only the list of matching uuid's will be returned
          required: false
          schema:
            type: string
            enum: [ 'uuid' ]
      responses:
        '200':
          description: An array of collection entities is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Collection'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error

  /collections/{id}/entities:
    get:
      tags:
        - collections
      summary: Get the list of all entities the Collection contains.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity.  This identifier can be either an SenNet ID (e.g. HBM123.ABCD.456) or UUID
          required: true
          schema:
            type: string
        - name: property
          in: query
          description: A case insensitive string. Any value besides 'uuid' will raise an error. If property=uuid is provided, rather than entire dictionary representations of each node, only the list of matching uuid's will be returned
          required: false
          schema:
            type: string
            enum: [ 'uuid' ]
      responses:
        '200':
          description: An array of collection entities is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Source'
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity.
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error
    post:
      tags:
        - collections
      summary: Get the list of all entities the Collection contains.
      parameters:
        - name: id
          in: path
          description: The unique identifier of entity. This identifier can be either an SenNet ID (e.g. SNT123.ABCD.456) or UUID
          required: true
          schema:
            type: string
      requestBody:
        description: A json body with "filter_properties" (a list of properties to include or exclude) and "is_include"
          (a boolean value for if the list provided is inclusion or exclusion).
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_properties:
                  type: array
                  items:
                    type: string
                  description: A list of properties to include or exclude
                is_include:
                  type: boolean
                  description: Used to determine if the list provided is inclusion or exclusion
      responses:
        '200':
          description: An array of ancestors is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/Source'
                    - $ref: '#/components/schemas/Sample'
                    - $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid or misformatted entity identifier
        '401':
          description: The user's token has expired or the user did not supply a valid token
        '403':
          description: The user is not authorized to access the entity
        '404':
          description: The target entity could not be found
        '500':
          description: Internal error