openapi: 3.0.3
info:
  title: HRA-API
  description: |
    This API provides programmatic access to data registered to the Human Reference Atlas (HRA).
    See the [HuBMAP HRA Portal](https://humanatlas.io/) for details.
  version: 0.19.0
  contact:
    name: HuBMAP Help Desk
    email: help@hubmapconsortium.org
  license:
    name: MIT License
    url: https://spdx.org/licenses/MIT.html
servers:
  - description: HRA-API Production
    url: https://apps.humanatlas.io/api
  - description: HRA-API Staging
    url: https://apps.humanatlas.io/api--staging
  - description: CCF-API (deprecated) Production
    url: https://apps.humanatlas.io/hra-api
  - description: Local Server
    url: /
security: []
tags:
  - name: v1
    description: HRA-API v1 Routes
  - name: ds-graph
    description: Dataset Graph Routes
  - name: hra-kg
    description: HRA KG Routes
  - name: hra-pop
    description: HRApop Routes
externalDocs:
  description: API Documentation
  url: https://github.com/x-atlas-consortia/hra-api#readme
paths:
  /v1/aggregate-results:
    get:
      summary: Get aggregate results / statistics
      operationId: aggregate-results
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/AggregateResults'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/anatomical-systems-tree-model:
    get:
      summary: Get anatomical systems partonomy tree nodes
      operationId: anatomical-systems-tree-model
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/OntologyTree'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/asctb-omap-sheet-config:
    get:
      summary: Get OMAP sheet config data for the ASCT+B Reporter
      operationId: asctb-omap-sheet-config
      tags:
        - v1
      responses:
        '200':
          $ref: '#/components/responses/AsctbReferenceData'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/asctb-sheet-config:
    get:
      summary: Get sheet config data for the ASCT+B Reporter
      operationId: asctb-sheet-config
      tags:
        - v1
      responses:
        '200':
          $ref: '#/components/responses/AsctbReferenceData'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/biomarker-term-occurences:
    get:
      summary: Get number of biomarker type term occurrences for a search
      operationId: biomarker-term-occurences
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/TermOccurences'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/biomarker-tree-model:
    get:
      summary: Get biomarker tree nodes
      operationId: biomarker-tree-model
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/OntologyTree'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/cell-type-term-occurences:
    get:
      summary: Get number of cell type term occurrences for a search
      operationId: cell-type-term-occurences
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/TermOccurences'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/cell-type-tree-model:
    get:
      summary: Get cell type tree nodes
      operationId: cell-type-tree-model
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/OntologyTree'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/collisions:
    post:
      summary: Given an extraction site, get mesh-based collisions with the reference organ.
      operationId: collisions
      tags:
        - v1
      requestBody:
        $ref: '#/components/requestBodies/ExtractionSite'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '400':
          $ref: '#/components/responses/ErrorMessage'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /v1/consortium-names:
    get:
      summary: Get consortium names (for filtering)
      operationId: consortium-names
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/Strings'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/corridor:
    post:
      summary: Given an extraction site, generate a corridor with the reference organ.
      operationId: corridor
      tags:
        - v1
      requestBody:
        $ref: '#/components/requestBodies/ExtractionSite'
      responses:
        '200':
          description: Successful operation
          content:
            model/gltf-binary:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/ErrorMessage'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /v1/db-status:
    get:
      summary: Get current status of database
      operationId: db-status
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/DatabaseStatus'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/ds-graph:
    get:
      summary: Get dataset graph
      description: Get potentially filtered experimental data in dataset graph format (previously referred to as rui_locations.jsonld format)
      operationId: ds-graph
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/extraction-site:
    get:
      summary: Lookup Extraction Site
      operationId: extraction-site
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/ExtractionSiteIri'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/ftu-illustrations:
    get:
      summary: Get 2D FTU Illustration data
      operationId: ftu-illustrations
      tags:
        - v1
      responses:
        '200':
          $ref: '#/components/responses/FtuIllustrations'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/get-spatial-placement:
    post:
      summary: Given a SpatialEntity already placed relative to a reference SpatialEntity, retrieve a new direct SpatialPlacement to the given SpatialEntity IRI
      operationId: get-spatial-placement
      tags:
        - v1
      requestBody:
        $ref: '#/components/requestBodies/GetSpatialPlacement'
      responses:
        '200':
          $ref: '#/components/responses/SpatialPlacement'
        '400':
          $ref: '#/components/responses/ErrorMessage'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /v1/gtex/rui_locations.jsonld:
    get:
      summary: Get all GTEx rui locations (if enabled)
      description: This option is only enabled if GTEX_ROUTES=true in the environment
      operationId: gtex-rui-locations
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found due to option being disabled
  /v1/hubmap/rui_locations.jsonld:
    get:
      summary: Get all hubmap rui locations (if enabled)
      description: This option is only enabled if XCONSORTIA_ROUTES=true in the environment
      operationId: hubmap-rui-locations
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found due to option being disabled
  /v1/mesh-3d-cell-population:
    post:
      summary: Given a reference organ, 3d scene node, and cell population,  generate cells in that distribution to fit in that 3d scene node.
      operationId: mesh-3d-cell-population
      tags:
        - v1
      requestBody:
        $ref: '#/components/requestBodies/Mesh3dCellPopulation'
      responses:
        '200':
          description: Successful response with CSV file
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/ErrorMessage'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /v1/ontology-term-occurences:
    get:
      summary: Get number of ontology term occurrences for a search
      operationId: ontology-term-occurences
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/TermOccurences'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/ontology-tree-model:
    get:
      summary: Get ontology term tree nodes
      operationId: ontology-tree-model
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/OntologyTree'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/provider-names:
    get:
      summary: Get tissue provider names (for filtering)
      operationId: provider-names
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/Strings'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/reference-organ-scene:
    get:
      summary: Get all nodes to form the 3D scene for an organ
      operationId: reference-organ-scene
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/OrganIri'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/SpatialSceneNodes'
        '400':
          $ref: '#/components/responses/ErrorMessage'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/reference-organs:
    get:
      summary: Get all reference organs
      operationId: reference-organs
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/SpatialEntities'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/rui-reference-data:
    get:
      summary: Get reference data for the RUI tool
      operationId: rui-reference-data
      tags:
        - v1
      responses:
        '200':
          $ref: '#/components/responses/RuiReferenceData'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/scene:
    get:
      summary: Get all nodes to form the 3D scene of reference body, organs, and tissues
      operationId: scene
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/SpatialSceneNodes'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/sennet/rui_locations.jsonld:
    get:
      summary: Get all sennet rui locations (if enabled)
      description: This option is only enabled if XCONSORTIA_ROUTES=true in the environment
      operationId: sennet-rui-locations
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found due to option being disabled
  /v1/session-token:
    post:
      summary: Get a session token
      operationId: session-token
      tags:
        - v1
      requestBody:
        $ref: '#/components/requestBodies/SessionToken'
      responses:
        '200':
          $ref: '#/components/responses/SessionToken'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '405':
          $ref: '#/components/responses/ErrorMessage'
  /v1/sparql:
    get:
      summary: Run a SPARQL query
      operationId: sparql
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/SparqlResponse'
        '404':
          $ref: '#/components/responses/ErrorMessage'
    post:
      summary: Run a SPARQL query (POST)
      operationId: sparql-post
      tags:
        - v1
      requestBody:
        $ref: '#/components/requestBodies/SparqlQuery'
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/SparqlResponse'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/technology-names:
    get:
      summary: Get technology names (for filtering)
      operationId: technology-names
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/Strings'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /v1/tissue-blocks:
    get:
      summary: Get Tissue Block Results
      operationId: tissue-blocks
      tags:
        - v1
      parameters:
        - $ref: '#/components/parameters/Age'
        - $ref: '#/components/parameters/AgeRange'
        - $ref: '#/components/parameters/Bmi'
        - $ref: '#/components/parameters/BmiRange'
        - $ref: '#/components/parameters/Cache'
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/Consortiums'
        - $ref: '#/components/parameters/Providers'
        - $ref: '#/components/parameters/Sex'
        - $ref: '#/components/parameters/SpatialSearches'
        - $ref: '#/components/parameters/Technologies'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/TissueBlocks'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /ds-graph/atlas-d2k:
    get:
      summary: Get Atlas D2K Dataset Graph
      operationId: atlas-d2k
      tags:
        - ds-graph
      parameters:
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /ds-graph/gtex:
    get:
      summary: Get GTEx Dataset Graph
      operationId: gtex
      tags:
        - ds-graph
      parameters:
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /ds-graph/hubmap:
    get:
      summary: Get HuBMAP Dataset Graph
      operationId: hubmap
      tags:
        - ds-graph
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/Primary'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /ds-graph/sennet:
    get:
      summary: Get SenNet Dataset Graph
      operationId: sennet
      tags:
        - ds-graph
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/Primary'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /hra-pop/cell-summary-report:
    post:
      summary: Given a cell summary in csv format, retrieve a predicted cell summary report from HRApop showing relative anatomical structures, datasets, and rui locations.
      operationId: cell-summary-report
      tags:
        - hra-pop
      requestBody:
        $ref: '#/components/requestBodies/GetCellSummaryReport'
      responses:
        '200':
          $ref: '#/components/responses/CellSummaryReportResponse'
        '400':
          $ref: '#/components/responses/ErrorMessage'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /hra-pop/rui-location-cell-summary:
    post:
      summary: Given a SpatialEntity already placed relative to a reference SpatialEntity, retrieve a predicted cell summary from HRApop
      operationId: rui-location-cell-summary
      tags:
        - hra-pop
      requestBody:
        $ref: '#/components/requestBodies/GetRuiLocationCellSummary'
      responses:
        '200':
          $ref: '#/components/responses/RuiLocationCellSummaryResponse'
        '400':
          $ref: '#/components/responses/ErrorMessage'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /hra-pop/supported-organs:
    get:
      summary: Get all organs supported by HRApop
      operationId: supported-organs
      tags:
        - hra-pop
      responses:
        '200':
          $ref: '#/components/responses/IdLabelsResponse'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /hra-pop/supported-reference-organs:
    get:
      summary: Get all reference organs supported by HRApop
      operationId: supported-reference-organs
      tags:
        - hra-pop
      responses:
        '200':
          $ref: '#/components/responses/IdLabelsResponse'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /hra-pop/supported-tools:
    get:
      summary: Get all tools supported by HRApop
      operationId: supported-tools
      tags:
        - hra-pop
      responses:
        '200':
          $ref: '#/components/responses/IdLabelsResponse'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /kg/asctb-term-occurences:
    get:
      summary: Get number of ASCT+B term occurrences for a search
      operationId: asctb-term-occurences
      tags:
        - hra-kg
      parameters:
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
      responses:
        '200':
          $ref: '#/components/responses/TermOccurences'
        '404':
          $ref: '#/components/responses/ErrorMessage'
  /kg/digital-objects:
    get:
      summary: List all digital objects in the HRA KG
      operationId: digital-objects
      tags:
        - hra-kg
      responses:
        '200':
          $ref: '#/components/responses/DigitalObjectsResponse'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
  /kg/do-search:
    get:
      summary: Search for Digital Object PURLs
      operationId: do-search
      tags:
        - hra-kg
      parameters:
        - $ref: '#/components/parameters/OntologyTerms'
        - $ref: '#/components/parameters/CellTypeTerms'
        - $ref: '#/components/parameters/BiomarkerTerms'
        - $ref: '#/components/parameters/HraVersions'
      responses:
        '200':
          $ref: '#/components/responses/Strings'
        '404':
          $ref: '#/components/responses/ErrorMessage'
        '500':
          $ref: '#/components/responses/ErrorMessage'
components:
  schemas:
    MinMax:
      title: Number Range
      description: |
        Represents a range of numbers using a minimum and maximum.
        Either end may be omitted to indicate an unlimited/infinite range in that direction.
        `min` should be less than or equal to `max` but this is not strictly enforced.
      type: object
      properties:
        min:
          type: number
        max:
          type: number
    SpatialSearch:
      title: Probing Sphere
      description: |
        Specification for a Spatial Search via Probing Sphere
      type: object
      properties:
        x:
          title: X coordinate relative to target in millimeters
          type: number
        'y':
          title: Y coordinate relative to target in millimeters
          type: number
        z:
          title: Z coordinate relative to target in millimeters
          type: number
        radius:
          title: Size of the probing sphere in millimeters
          type: number
        target:
          title: The target spatial entity IRI
          type: string
      required:
        - x
        - 'y'
        - z
        - radius
        - target
      additionalProperties: false
    AggregateCount:
      title: Aggregated Count \w Label
      type: object
      required:
        - label
        - count
      properties:
        label:
          title: Aggregate Name/Field
          type: string
        count:
          title: AggregatedCountValue
          type: number
    ErrorMessage:
      title: Error Message
      oneOf:
        - type: string
          title: Error message
          description: Human readable description of the error
        - type: object
          title: ErrorMessageObject
          required:
            - error
          properties:
            error:
              type: string
              description: Human readable description of the error
    JsonLdObject:
      title: JSON-LD Object
      description: Base object for all json-ld objects.
      type: object
      required:
        - '@id'
        - '@type'
      additionalProperties: true
      properties:
        '@id':
          title: Unique Identifier
          type: string
          format: uri
          example: http://purl.obolibrary.org/obo/UBERON_0013702
        '@type':
          title: Object Type
          description: Contains the name of object class/interface
          type: string
          example: Sample
    OntologyTreeNode:
      title: Ontology Node
      description: A node in the ontology tree.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
      required:
        - '@type'
      properties:
        '@type':
          type: string
          enum:
            - OntologyTreeNode
        id:
          title: Identifier
          description: Unique identifier for the node.
          type: string
          format: uri
        label:
          title: Label
          description: Main descriptive label for the node.
          type: string
        synonymLabels:
          title: Synonym Labels
          description: Additional label for the node.
          type: array
          items:
            type: string
        parent:
          title: Parent Node Identifier
          description: Reference to the parent node.
          type: string
          format: uri
        children:
          title: Child Node Identifiers
          description: References to all child nodes.
          type: array
          items:
            type: string
            format: uri
    OntologyTree:
      title: Ontology Tree
      description: An ontology tree.
      type: object
      required:
        - root
        - nodes
      properties:
        root:
          title: Root Node
          description: Reference to the root node.
          type: string
          format: url
        nodes:
          title: All Nodes
          description: A mapping of identifiers to each node object.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OntologyTreeNode'
    SpatialEntityCommon:
      title: Spatial Entity Common
      description: Properties available in all spatial entity objects.
      type: object
      properties:
        entityId:
          title: Entity Identifier
          description: Identifier of the entity the spatial object represents.
          type: string
          format: uri
        ccf_annotations:
          title: Annotations
          description: Annotations attached to the entity.
          type: array
          items:
            type: string
            format: uri
        representation_of:
          title: Representation
          description: Identifier for the item the spatial object represents.
          type: string
          format: uri
        reference_organ:
          title: Organ
          description: Identifier for the organ the spatial object represents.
          type: string
          format: uri
        sex:
          title: Sex
          type: string
          enum:
            - Female
            - Male
    SpatialEntityCreator:
      title: Spatial Entity Creator
      description: Describes by whom and when an entity object was created.
      type: object
      properties:
        creator:
          title: Full Name
          type: string
        creator_first_name:
          title: First Name
          type: string
        creator_last_name:
          title: Last Name
          type: string
        creator_orcid:
          title: Creator's Identifier
          type: string
        creation_date:
          title: Creation Date
          type: string
          format: date
    SpatialEntityDimensions:
      title: Spatial Entity Dimensions
      description: The dimensions of a spatial entity.
      type: object
      required:
        - x_dimension
        - y_dimension
        - z_dimension
        - dimension_units
      properties:
        x_dimension:
          title: X-Dimension
          type: number
        y_dimension:
          title: Y-Dimension
          type: number
        z_dimension:
          title: Z-Dimension
          type: number
        dimension_units:
          title: Dimension Units
          description: Length units of dimensional values.
          type: string
          default: millimeter
    SpatialPlacementTranslation:
      title: Spatial Placement Translation
      description: The properties to define the Translation aspect of Spatial Placements.
      type: object
      required:
        - x_translation
        - y_translation
        - z_translation
        - translation_units
      properties:
        x_translation:
          title: X-Translation
          type: number
        y_translation:
          title: Y-Translation
          type: number
        z_translation:
          title: Z-Translation
          type: number
        translation_units:
          title: Translation Units
          description: Length units of translation values.
          type: string
          default: millimeter
          enum:
            - millimeter
    SpatialPlacementRotation:
      title: Spatial Placement Rotation
      description: The properties to define the Rotation aspect of Spatial Placements.
      type: object
      required:
        - x_rotation
        - y_rotation
        - z_rotation
        - rotation_units
      properties:
        x_rotation:
          title: X-Rotation
          type: number
        y_rotation:
          title: Y-Rotation
          type: number
        z_rotation:
          title: Z-Rotation
          type: number
        rotation_units:
          title: Rotation Units
          description: Units of rotation values.
          type: string
          default: degree
          enum:
            - degree
    SpatialPlacementScaling:
      title: Spatial Placement Scaling
      description: The properties to define the Scaling aspect of Spatial Placements.
      type: object
      required:
        - x_scaling
        - y_scaling
        - z_scaling
        - scaling_units
      properties:
        x_scaling:
          title: X-Scaling
          type: number
        y_scaling:
          title: Y-Scaling
          type: number
        z_scaling:
          title: Z-Scaling
          type: number
        scaling_units:
          title: Scaling Units
          description: Units of scaling values.
          type: string
          default: ratio
          enum:
            - ratio
    SpatialPlacementCommon:
      title: Spatial Placement common fields
      description: A Spatial Placement defines how to place a Spatial Entity or Spatial Object Reference relative to another Spatial Entity. It says how to scale, rotate, and translate (in that order) a Spatial Entity or Spatial Object Reference so that it is placed relative to another Spatial Entity.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
        - $ref: '#/components/schemas/SpatialPlacementTranslation'
        - $ref: '#/components/schemas/SpatialPlacementRotation'
        - $ref: '#/components/schemas/SpatialPlacementScaling'
      required:
        - '@type'
        - target
      properties:
        '@type':
          type: string
          enum:
            - SpatialPlacement
        target:
          type: string
          format: uri
        placement_date:
          title: Date placement was made
          type: string
          format: date
    SpatialEntity:
      title: Spatial Entity
      description: A Spatial Entity defines a bounded cartesian space and the units it is measured in. It typically represents a real world thing, e.g., a human body, a human kidney, a tissue section, or an individual cell.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
        - $ref: '#/components/schemas/SpatialEntityCommon'
        - $ref: '#/components/schemas/SpatialEntityCreator'
        - $ref: '#/components/schemas/SpatialEntityDimensions'
      required:
        - '@type'
      properties:
        '@type':
          type: string
          enum:
            - SpatialEntity
        label:
          title: Label
          type: string
        comment:
          title: Comment
          type: string
        rui_rank:
          title: RUI Rank
          description: Ranking used to order lists in the RUI.
          type: integer
        sex:
          title: Sex
          type: string
          enum:
            - Female
            - Male
        side:
          title: Side
          description: Used for organs that come in pairs to distinguish between them, i.e. kidneys, etc.
          type: string
          enum:
            - Left
            - Right
        slice_count:
          title: Slice Count
          type: integer
        slice_thickness:
          title: Slice Thickness
          type: number
        placement:
          title: SpatialEntityPlacement
          oneOf:
            - $ref: '#/components/schemas/SpatialPlacement'
            - $ref: '#/components/schemas/SpatialPlacements'
        object:
          $ref: '#/components/schemas/SpatialObjectReference'
        color:
          $ref: '#/components/schemas/Rgba'
    SpatialObjectReference:
      title: Spatial Object Reference
      description: A Spatial Object Reference provides a reference to an external representation of a Spatial Entity.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
      required:
        - '@type'
      properties:
        '@type':
          type: string
          enum:
            - SpatialObjectReference
        file:
          title: File
          type: string
          format: uri
        file_format:
          title: File Format
          type: string
          example: model/gltf-binary
        file_subpath:
          title: File Subpath
          type: string
    SpatialPlacement:
      title: Spatial Placement
      description: A Spatial Placement defines how to place a Spatial Entity or Spatial Object Reference relative to another Spatial Entity. It says how to scale, rotate, and translate (in that order) a Spatial Entity or Spatial Object Reference so that it is placed relative to another Spatial Entity.
      type: object
      allOf:
        - $ref: '#/components/schemas/SpatialPlacementCommon'
      properties:
        source:
          title: SpacialPlacementSource
          oneOf:
            - $ref: '#/components/schemas/SpatialEntity'
            - $ref: '#/components/schemas/SpatialObjectReference'
        target:
          title: SpacialPlacementTarget
          oneOf:
            - title: Target Sptial Entity IRI
              type: string
              format: uri
              example: http://purl.org/ccf/latest/ccf.owl#VHMLeftKidney
            - $ref: '#/components/schemas/SpatialEntity'
    SpatialPlacements:
      title: Spatial Placements
      type: array
      items:
        $ref: '#/components/schemas/SpatialPlacement'
    Rgba:
      title: RGBA Color Tuple
      type: array
      minItems: 4
      maxItems: 4
      items:
        title: 8-Bit Value
        type: number
        minimum: 0
        maximum: 255
    DatabaseStatus:
      title: Database Status
      type: object
      required:
        - status
      properties:
        status:
          title: Current status of the database
          type: string
          enum:
            - Loading
            - Ready
            - Error
        checkback:
          title: How long to wait (in milliseconds) before checking status again
          type: integer
          minimum: 0
        loadTime:
          title: The amount of time (in milliseconds) taken to load the database
          type: integer
          minimum: 0
        message:
          title: Human readable description of the current status
          type: string
    GetSpatialPlacementRequest:
      title: get-spatial-placement request body
      type: object
      required:
        - target_iri
        - rui_location
      properties:
        target_iri:
          type: string
          format: uri
        rui_location:
          $ref: '#/components/schemas/SpatialEntity'
    FlatSpatialPlacement:
      title: Spatial Placement
      description: A Spatial Placement defines how to place a Spatial Entity or Spatial Object Reference relative to another Spatial Entity. It says how to scale, rotate, and translate (in that order) a Spatial Entity or Spatial Object Reference so that it is placed relative to another Spatial Entity.
      type: object
      allOf:
        - $ref: '#/components/schemas/SpatialPlacementCommon'
      properties:
        source:
          title: Source Spatial Entity or Spatial Object Reference IRI
          type: string
          format: uri
        target:
          title: Target Spatial Entity IRI
          type: string
          format: uri
    Mesh3dCellPopulationRequest:
      title: mesh-3d-cell-population request body
      type: object
      required:
        - file
        - file_subpath
        - num_nodes
        - node_distribution
      properties:
        file:
          type: string
          format: uri
        file_subpath:
          type: string
        num_nodes:
          type: integer
        node_distribution:
          type: object
          additionalProperties:
            type: number
    SpatialSceneNode:
      title: Spatial Scene Node
      description: Specification for a node that can be displayed in the scene.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
        - $ref: '#/components/schemas/SpatialEntityCommon'
      properties:
        name:
          title: Label
          type: string
        tooltip:
          title: Tooltip Label
          type: string
        unpickable:
          title: Unpickable
          description: Whether the node should selectable by the user in interfaces.
          type: boolean
        geometry:
          title: Geometry
          description: Geometry to draw, if it is not using a GLTF file.
          type: string
          enum:
            - sphere
            - cube
            - wireframe
            - text
            - cone
            - cylinder
        text:
          title: Text
          description: Text to draw for the `text` geometry
          type: string
        _lighting:
          title: Lighting
          type: string
        zoomBasedOpacity:
          title: Zoom Based Opacity
          description: Whether the opacity of the node changes based on the zoom level.
          type: boolean
        zoomToOnLoad:
          title: Focus
          description: Focus this node when loaded in an interface.
          type: boolean
        scenegraph:
          title: Scenegraph
          type: string
          format: uri
        scenegraphNode:
          title: Scenegraph Node
          type: string
        color:
          $ref: '#/components/schemas/Rgba'
        opacity:
          title: Opacity
          type: number
        transformMatrix:
          title: Transformation
          description: Additional transformations to be applied.
          type: array
          minItems: 16
          maxItems: 16
          items:
            type: number
        priority:
          title: Priority
          type: number
    MinMaxArray:
      title: Number Range
      description: |
        Represents a range of numbers using a minimum and maximum. First element should be less than or equal to the second element.
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: number
    Filter:
      title: Filter
      description: Filter object
      type: object
      properties:
        sex:
          type: string
          enum:
            - Both
            - Male
            - Female
        ageRange:
          $ref: '#/components/schemas/MinMaxArray'
        bmiRange:
          $ref: '#/components/schemas/MinMaxArray'
        consortiums:
          type: array
          items:
            type: string
        tmc:
          type: array
          items:
            type: string
        technologies:
          type: array
          items:
            type: string
        ontologyTerms:
          type: array
          items:
            type: string
            format: uri
        cellTypeTerms:
          type: array
          items:
            type: string
            format: uri
        biomarkerTerms:
          type: array
          items:
            type: string
            format: uri
        spatialSearches:
          type: array
          items:
            $ref: '#/components/schemas/SpatialSearch'
      additionalProperties: false
    SessionTokenRequest:
      title: session-token request body
      type: object
      required:
        - dataSources
      properties:
        dataSources:
          type: array
          items:
            type: string
        filter:
          $ref: '#/components/schemas/Filter'
    SessionToken:
      title: Session Token
      type: object
      required:
        - token
      properties:
        token:
          title: Session token
          type: string
    SparqlQueryRequest:
      title: SPARQL query request body
      type: object
      required:
        - query
      properties:
        query:
          type: string
    TissueCommon:
      title: Common Tissue Data Properties
      description: Properties available in all tissue data objects.
      type: object
      required:
        - label
        - link
      properties:
        label:
          type: string
        description:
          type: string
        link:
          title: Associated URL
          type: string
          format: uri
    TissueDataset:
      title: Tissue Dataset
      description: Describes a single tissue dataset.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
        - $ref: '#/components/schemas/TissueCommon'
      required:
        - '@type'
      properties:
        '@type':
          type: string
          enum:
            - Dataset
        technology:
          title: Technology Used
          type: string
        thumbnail:
          title: Representative Thumbnail URL
          type: string
          format: uri
    TissueSampleCommon:
      title: Common Tissue Sample Properties
      description: Properties available in all tissue sample objects.
      type: object
      required:
        - '@type'
        - sampleType
        - datasets
      properties:
        '@type':
          type: string
          enum:
            - Sample
        sampleType:
          title: Object Type
          type: string
        datasets:
          title: Associated Datasets
          type: array
          items:
            $ref: '#/components/schemas/TissueDataset'
    TissueDonor:
      title: Tissue Donor
      description: Contains generic information about a tissue donor.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
        - $ref: '#/components/schemas/TissueCommon'
      required:
        - '@type'
      properties:
        '@type':
          type: string
          enum:
            - Donor
        providerName:
          title: Provider of Donor
          type: string
    TissueSection:
      title: Tissue Section
      description: A single section sample.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
        - $ref: '#/components/schemas/TissueCommon'
        - $ref: '#/components/schemas/TissueSampleCommon'
      required:
        - sampleType
      properties:
        sampleType:
          type: string
          enum:
            - Tissue Section
            - Non-Standard
        sectionNumber:
          title: Section Index
          description: Index of the section in the parent block.
          type: integer
          minimum: 0
    TissueBlock:
      title: Tissue Block
      description: Information about a collection of tissue sections.
      type: object
      allOf:
        - $ref: '#/components/schemas/JsonLdObject'
        - $ref: '#/components/schemas/TissueCommon'
        - $ref: '#/components/schemas/TissueSampleCommon'
      required:
        - sampleType
      properties:
        sampleType:
          type: string
          enum:
            - Tissue Block
            - Non-Standard
        spatialEntityId:
          title: Associated Spatial Entity
          description: The associated spatial entity (rui_location) for the block.
          type: string
          format: uri
        donor:
          $ref: '#/components/schemas/TissueDonor'
        sectionCount:
          title: Number of Sections
          description: Number of sections contained in the block.
          type: integer
          minimum: 0
        sectionSize:
          title: Section Size
          description: Size of each section in the block.
          type: number
          minimum: 0
        sectionUnits:
          title: Section Size Unit
          description: Length unit `sectionSize` is in (generally, millimeters)
          type: string
          default: millimeter
        sections:
          title: Contained Sections
          description: All sections in the block.
          type: array
          items:
            $ref: '#/components/schemas/TissueSection'
    CellSummaryReportRequest:
      title: Cell summary report request body
      type: object
      required:
        - csvString
      properties:
        csvString:
          title: Csv data
          type: string
        organ:
          title: Organ
          type: string
          format: uri
        tool:
          title: Tool
          type: string
    SourceSimilarityRow:
      title: Source Similarity Row
      type: object
      required:
        - tool
        - modality
        - cell_source
        - cell_source_type
        - cell_source_label
        - cell_source_link
        - similarity
      properties:
        tool:
          title: Tool
          type: string
        modality:
          title: Modality
          type: string
        cell_source:
          title: Cell Source
          type: string
          format: uri
        cell_source_type:
          title: Cell Source Type
          type: string
        cell_source_label:
          title: Cell Source Label
          type: string
        cell_source_link:
          title: Cell Source Link
          type: string
          format: uri
        similarity:
          title: Similarity
          type: number
    CellSummaryReport:
      title: Cell Summary Report
      type: object
      required:
        - sources
        - rui_locations
      properties:
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceSimilarityRow'
        rui_locations:
          title: RUI Locations
          type: array
          items: {}
        error:
          title: Error Message
          type: object
          additionalProperties: true
    CellSummaryRow:
      title: Cell Summary Row
      type: object
      required:
        - tool
        - modality
        - cell_id
        - cell_label
        - count
        - percentage
      properties:
        tool:
          title: Tool
          type: string
        modality:
          title: Modality
          type: string
        cell_id:
          title: Cell ID
          type: string
          format: uri
        cell_label:
          title: Cell Label
          type: string
        count:
          title: Count
          type: number
        percentage:
          title: Percentage
          type: number
    IdLabelPair:
      title: ID - Label pair
      type: object
      required:
        - id
        - label
      properties:
        id:
          title: ID (iri) of the entity
          type: string
          format: uri
        label:
          title: Label of the entity
          type: string
    DigitalObjectInfo:
      title: Digital Object Information
      type: object
      required:
        - '@id'
        - '@type'
        - title
        - doType
        - doName
        - doVersion
        - lastUpdated
        - hraVersions
        - versions
        - purl
        - datasets
        - lod
      properties:
        '@id':
          type: string
          format: uri
          description: Unique identifier of the digital object dataset
          example: https://lod.humanatlas.io/2d-ftu/kidney-nephron
        '@type':
          type: string
          enum:
            - dcat:Catalog
          example: dcat:Catalog
        title:
          type: string
          example: 2D Nephron Functional Tissue Unit (FTU) for Kidney
        doType:
          type: string
          description: Digital object type (e.g., “2d-ftu”)
          example: 2d-ftu
        doName:
          type: string
          description: Name of the digital object
          example: kidney-nephron
        doVersion:
          type: string
          description: Current version of the digital object
          example: v1.2
        lastUpdated:
          type: string
          format: date
          description: Date the object was last updated
          example: '2023-12-15'
        hraVersions:
          type: array
          items:
            type: string
          description: All versions of the HRA this digital object was published in
          example:
            - v2.3
            - v2.1
            - v2.0
        versions:
          type: array
          items:
            type: string
          description: All available versions of the digital object
          example:
            - v1.2
            - v1.1
            - v1.0
        purl:
          type: string
          format: uri
          description: Persistent URL for the digital object
          example: https://purl.humanatlas.io/2d-ftu/kidney-nephron
        datasets:
          type: array
          items:
            type: string
            format: uri
          description: Dataset URLs for each version
          example:
            - https://lod.humanatlas.io/2d-ftu/kidney-nephron/v1.2
            - https://lod.humanatlas.io/2d-ftu/kidney-nephron/v1.1
            - https://lod.humanatlas.io/2d-ftu/kidney-nephron/v1.0
        lod:
          type: string
          format: uri
          description: Unique identifier of the digital object dataset (same as @id)
          example: https://lod.humanatlas.io/2d-ftu/kidney-nephron/v1.2
        cell_count:
          type: integer
          description: Number of cells in the DO (if applicable)
          example: 16
        biomarker_count:
          type: integer
          description: Number of biomarkers in the DO (if applicable)
          example: 0
        organs:
          type: array
          items:
            type: string
          description: Organs in the DO (if applicable)
          example:
            - kidney
        organIds:
          type: array
          items:
            type: string
            format: uri
          description: Ontology IDs for associated organs (if applicable)
          example:
            - http://purl.obolibrary.org/obo/UBERON_0002113
    DigitalObjectsJsonLd:
      title: Digital Objects JSON-LD response
      type: object
      properties:
        '@context':
          type: object
          additionalProperties: true
        '@graph':
          type: array
          items:
            $ref: '#/components/schemas/DigitalObjectInfo'
  parameters:
    Age:
      name: age
      description: Filter result by age.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/MinMax'
    AgeRange:
      name: age-range
      description: Filter result by age.
      in: query
      deprecated: true
      required: false
      schema:
        type: string
        example: 10,100
    Bmi:
      name: bmi
      description: Filter result by bmi.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/MinMax'
    BmiRange:
      name: bmi-range
      description: Filter result by bmi.
      in: query
      deprecated: true
      required: false
      schema:
        type: string
        example: 0,40
    Cache:
      name: cache
      description: Hint to cache (or not) the response of this request
      in: query
      required: false
      schema:
        type: boolean
        default: true
    OntologyTerms:
      name: ontology-terms
      description: Filter result by ontology terms.
      in: query
      required: false
      schema:
        title: Terms
        type: array
        items:
          type: string
    CellTypeTerms:
      name: cell-type-terms
      description: Filter result by ontology terms.
      in: query
      required: false
      schema:
        title: Terms
        type: array
        items:
          type: string
    BiomarkerTerms:
      name: biomarker-terms
      description: Filter result by ontology terms.
      in: query
      required: false
      schema:
        title: Terms
        type: array
        items:
          type: string
    Consortiums:
      name: consortiums
      description: Filter result by consortiums.
      in: query
      required: false
      schema:
        title: Consortiums
        type: array
        items:
          type: string
    Providers:
      name: providers
      description: Filter result by providers.
      in: query
      required: false
      schema:
        title: Providers
        type: array
        items:
          type: string
    Sex:
      name: sex
      description: Filter result by sex.
      in: query
      required: false
      schema:
        type: string
        enum:
          - both
          - female
          - male
    SpatialSearches:
      name: spatial
      description: Filter result by spatial searches.
      in: query
      required: false
      schema:
        title: SpatialSearches
        type: array
        items:
          $ref: '#/components/schemas/SpatialSearch'
    Technologies:
      name: technologies
      description: Filter result by technologies.
      in: query
      required: false
      schema:
        title: Technologies
        type: array
        items:
          type: string
    Token:
      name: token
      description: Authentication token to use for authenticated searches
      in: query
      required: false
      schema:
        type: string
    ExtractionSiteIri:
      name: iri
      description: extraction site iri to search for
      in: query
      required: true
      schema:
        type: string
        format: uri
    OrganIri:
      name: organ-iri
      description: Filter result by organ.
      in: query
      required: true
      schema:
        type: string
    Query:
      name: query
      description: SPARQL query to use
      in: query
      required: true
      schema:
        type: string
        example: SELECT * WHERE { ?sub ?pred ?obj . } LIMIT 10
    Format:
      name: format
      description: Override SPARQL response format (Note that not all formats are supported for all SPARQL query types)
      in: query
      required: false
      schema:
        type: string
        enum:
          - application/json
          - application/ld+json
          - application/n-quads
          - application/n-triples
          - application/sparql-results+json
          - application/sparql-results+xml
          - application/trig
          - simple
          - stats
          - table
          - text/csv
          - text/n3
          - text/tab-separated-values
          - text/turtle
          - tree
    Primary:
      name: primary
      description: Limit results to primary datasets only
      in: query
      required: false
      schema:
        type: boolean
        default: false
    HraVersions:
      name: hra-versions
      description: Filter result by hra versions.
      in: query
      required: false
      schema:
        title: HRA Versions
        type: array
        items:
          type: string
        example:
          - v2.3
          - v2.2
          - v2.1
          - v2.0
          - v1.4
          - v1.3
          - v1.2
          - v1.1
          - v1.0
  responses:
    AggregateResults:
      description: Successful operation
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AggregateCount'
    ErrorMessage:
      description: Successful operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    OntologyTree:
      description: Successful operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OntologyTree'
    AsctbReferenceData:
      description: Successful operation. ASCT+B Reference Data.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              additionalProperties: true
    TermOccurences:
      description: Successful operation
      content:
        application/json:
          schema:
            type: object
            additionalProperties:
              type: integer
    Strings:
      description: Successful operation
      content:
        application/json:
          schema:
            type: array
            items:
              type: string
    DatabaseStatus:
      description: Successful operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DatabaseStatus'
    FtuIllustrations:
      description: Successful operation. 2D FTU Illustration Data.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              additionalProperties: true
    SpatialPlacement:
      description: Successful operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FlatSpatialPlacement'
    SpatialSceneNodes:
      description: Successful operation
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SpatialSceneNode'
    SpatialEntities:
      description: Successful operation
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SpatialEntity'
    RuiReferenceData:
      description: Successful operation. RUI Reference Data.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              additionalProperties: true
    SessionToken:
      description: Successful operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionToken'
    SparqlResponse:
      description: Successful operation. SPARQL responses vary by format/content negotiation.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
        text/csv:
          schema:
            type: string
    TissueBlocks:
      description: Successful operation
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TissueBlock'
    CellSummaryReportResponse:
      description: Successful operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CellSummaryReport'
    RuiLocationCellSummaryResponse:
      description: Successful operation
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/CellSummaryRow'
    IdLabelsResponse:
      description: Successful operation
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/IdLabelPair'
    DigitalObjectsResponse:
      description: Successful operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DigitalObjectsJsonLd'
  requestBodies:
    ExtractionSite:
      description: |
        Request format for routes using posted extraction sites
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SpatialEntity'
          example:
            '@context': https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld
            '@id': http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5
            '@type': SpatialEntity
            creator: demo demo
            creator_first_name: demo
            creator_last_name: demo
            creation_date: '2024-08-20'
            ccf_annotations:
              - http://purl.obolibrary.org/obo/UBERON_0002015
              - http://purl.obolibrary.org/obo/UBERON_0002189
            x_dimension: 10
            y_dimension: 10
            z_dimension: 10
            dimension_units: millimeter
            placement:
              '@context': https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld
              '@id': http://purl.org/ccf/1.5/cc837df1-2788-4510-9c21-9eb0e9b310a5_placement
              '@type': SpatialPlacement
              target: https://purl.humanatlas.io/ref-organ/kidney-female-right/v1.3#primary
              placement_date: '2024-08-20'
              x_scaling: 1
              y_scaling: 1
              z_scaling: 1
              scaling_units: ratio
              x_rotation: 0
              y_rotation: 0
              z_rotation: 0
              rotation_order: XYZ
              rotation_units: degree
              x_translation: 72.366
              y_translation: 79.067
              z_translation: 34.77
              translation_units: millimeter
    GetSpatialPlacement:
      description: Request format for requesting a spatial placement for a given spatial entity IRI and RUI location
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetSpatialPlacementRequest'
          example:
            target_iri: https://purl.humanatlas.io/graph/hra-ccf-body#VHFemale
            rui_location:
              '@context': https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld
              '@id': http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869
              '@type': SpatialEntity
              creator: Bruce Herr
              creator_first_name: Bruce
              creator_last_name: Herr
              creation_date: '2022-04-27'
              ccf_annotations:
                - http://purl.obolibrary.org/obo/UBERON_0002015
                - http://purl.obolibrary.org/obo/UBERON_0000362
                - http://purl.obolibrary.org/obo/UBERON_0004200
                - http://purl.obolibrary.org/obo/UBERON_0001225
                - http://purl.obolibrary.org/obo/UBERON_0001284
                - http://purl.obolibrary.org/obo/UBERON_0002189
              x_dimension: 11
              y_dimension: 12
              z_dimension: 13
              dimension_units: millimeter
              placement:
                '@context': https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld
                '@id': http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869_placement
                '@type': SpatialPlacement
                target: http://purl.org/ccf/latest/ccf.owl#VHFLeftKidneyV1.1
                placement_date: '2022-04-27'
                x_scaling: 1
                y_scaling: 1
                z_scaling: 1
                scaling_units: ratio
                x_rotation: -61
                y_rotation: 50
                z_rotation: -84
                rotation_order: XYZ
                rotation_units: degree
                x_translation: 20.149
                y_translation: 109.963
                z_translation: 38.79
                translation_units: millimeter
    Mesh3dCellPopulation:
      description: |
        Request format for requesting a mesh-based 3d cell population.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Mesh3dCellPopulationRequest'
          example:
            file: https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb
            file_subpath: VH_F_renal_pyramid_L_a
            num_nodes: 10
            node_distribution:
              KEY1: 0.1
              KEY2: 0.3
    SessionToken:
      description: |
        Request format for requesting a session token
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionTokenRequest'
          example:
            dataSources:
              - https://purl.humanatlas.io/ds-graph/hubmap
            filter:
              sex: Female
    SparqlQuery:
      description: Request format for a SPARQL query
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SparqlQueryRequest'
          example:
            query: SELECT * WHERE { ?sub ?pred ?obj . } LIMIT 10
        application/x-www-form-urlencoded:
          schema:
            $ref: '#/components/schemas/SparqlQueryRequest'
    GetCellSummaryReport:
      description: Request format for requesting a cell summary report for a given csv file. Must provide a minimum of cell_id and percentage columns.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CellSummaryReportRequest'
          example:
            organ: http://purl.obolibrary.org/obo/UBERON_0000948
            csvString: |-
              cell_id,cell_label,count,percentage
              http://purl.obolibrary.org/obo/CL_0002131,regular ventricular cardiac myocyte,49273.09543,0.332091136333487
              http://purl.obolibrary.org/obo/CL_0000669,pericyte,24587.941957,0.16571797475566
              http://purl.obolibrary.org/obo/CL_0002144,capillary endothelial cell,20134.675085,0.13570381706955
              http://purl.obolibrary.org/obo/CL_0000057,fibroblast,14931.592835,0.10063604871118
              http://purl.obolibrary.org/obo/CL_0000003,native cell,11003.040295,0.0741583641701745
              http://purl.obolibrary.org/obo/CL_1000413,endothelial cell of artery,6976.051286,0.0470172368606237
              http://purl.obolibrary.org/obo/CL_0000192,smooth muscle cell,4553.526495,0.0306898881601113
              http://purl.obolibrary.org/obo/CL_0000235,macrophage,3870.474525,0.0260862499491858
              http://purl.obolibrary.org/obo/CL_0000115,endothelial cell,2564.473475,0.0172840553851487
              http://purl.obolibrary.org/obo/CL_0002543,vein endothelial cell,1949.697045,0.0131405811128699
              http://purl.obolibrary.org/obo/CL_0000623,natural killer cell,1175.948771,0.00792566734895222
              http://purl.obolibrary.org/obo/CL_0002397,"CD14-positive, CD16-positive monocyte",939.527765,0.00633223548009011
              http://purl.obolibrary.org/obo/CL_0000934,"CD4-positive, alpha-beta cytotoxic T cell",893.222763,0.00602014871959927
              http://purl.obolibrary.org/obo/CL_0002319,neural cell,826.561462,0.00557086443970238
              http://purl.obolibrary.org/obo/CL_0000906,"activated CD8-positive, alpha-beta T cell",603.03561,0.00406434341554534
              http://purl.obolibrary.org/obo/CL_0000794,"CD8-positive, alpha-beta cytotoxic T cell",598.710396,0.00403519230945772
              http://purl.obolibrary.org/obo/CL_1000309,epicardial adipocyte,576.599013,0.003886165863234
              http://purl.obolibrary.org/obo/CL_0001054,CD14-positive monocyte,512.948563,0.00345717413693446
              http://purl.obolibrary.org/obo/CL_0000097,mast cell,507.054682,0.00341745051856579
              http://purl.obolibrary.org/obo/CL_0000576,monocyte,437.848941,0.00295101720503181
              http://purl.obolibrary.org/obo/CL_0000814,mature NK T cell,428.888686,0.00289062681878106
              http://purl.obolibrary.org/obo/CL_0000896,"activated CD4-positive, alpha-beta T cell",314.404462,0.00211902528434063
              http://purl.obolibrary.org/obo/CL_0002138,endothelial cell of lymphatic vessel,253.169304,0.00170631215912871
              http://purl.obolibrary.org/obo/CL_0000236,B cell,239.189975,0.00161209418454692
              http://purl.obolibrary.org/obo/CL_0000451,dendritic cell,200.812358,0.0013534364662104
              http://purl.obolibrary.org/obo/CL_0000077,mesothelial cell,19.717649,0.000132893141887896
    GetRuiLocationCellSummary:
      description: Request format for requesting a cell summary for a given RUI location
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SpatialEntity'
          example:
            '@context': https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld
            '@id': http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869
            '@type': SpatialEntity
            creator: Bruce Herr
            creator_first_name: Bruce
            creator_last_name: Herr
            creation_date: '2022-04-27'
            ccf_annotations:
              - http://purl.obolibrary.org/obo/UBERON_0002015
              - http://purl.obolibrary.org/obo/UBERON_0000362
              - http://purl.obolibrary.org/obo/UBERON_0004200
              - http://purl.obolibrary.org/obo/UBERON_0001225
              - http://purl.obolibrary.org/obo/UBERON_0001284
              - http://purl.obolibrary.org/obo/UBERON_0002189
            x_dimension: 11
            y_dimension: 12
            z_dimension: 13
            dimension_units: millimeter
            placement:
              '@context': https://hubmapconsortium.github.io/ccf-ontology/ccf-context.jsonld
              '@id': http://purl.org/ccf/1.5/f7130161-ad0a-4801-b5a4-f6297e0f1869_placement
              '@type': SpatialPlacement
              target: http://purl.org/ccf/latest/ccf.owl#VHFLeftKidneyV1.1
              placement_date: '2022-04-27'
              x_scaling: 1
              y_scaling: 1
              z_scaling: 1
              scaling_units: ratio
              x_rotation: -61
              y_rotation: 50
              z_rotation: -84
              rotation_order: XYZ
              rotation_units: degree
              x_translation: 20.149
              y_translation: 109.963
              z_translation: 38.79
              translation_units: millimeter
x-preprocessor:
  description: |
    For some openapi-generator-cli generators our custom preprocessor
    has to be employed to "fix" this specification to circumvent
    inconsistencies/bugs in the generated code.
    The preprocessor uses `x-preprocessor-` properties to determine
    which operation to apply and where to apply it.
  operations:
    delete: |
      Delete one or more properties at the specified paths.
      Will also delete the property from the `required` list if applicable.