openapi: 3.0.0
info:
  description: ToppGene API
  version: 1.0.0
  title: ToppGene API
servers:
  - url: 'https://toppgene.cchmc.org/API'
paths:
  /enrich:
    post:
      summary: Perform Functional Enrichment
      parameters:
        - in: query
          name: pretty
          required: false
          schema:
            type: boolean
            enum:
              - true
          description: Optional. If `true` ToppGene will indent output
        - in: query
          name: as
          required: false
          schema:
            type: string
            enum:
              - json
              - xml
          description: >-
            Override defaults and/or HTTP request headers for return format. The
            XML result is not described in this definition file, but it is
            substantially similar to the JSON format.
      requestBody:
        description: JSON Payload of Entrez genes and which categories needed.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentRequest'
      responses:
        '200':
          description: A list of features grouped by Category ordered by ascending p-Value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentResponse'
        '500':
          description: Any Error
  /lookup:
    post:
      summary: Convert genes to Human Entrez IDs
      parameters:
        - in: query
          name: pretty
          required: false
          schema:
            type: boolean
            enum:
              - true
          description: Optional. If `true` ToppGene will indent output
        - in: query
          name: as
          required: false
          schema:
            type: string
            enum:
              - json
              - xml
          description: >-
            Override defaults and/or HTTP request headers for return format. The
            XML result is not described in this definition file, but it is
            substantially similar to the JSON format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupRequest'
      responses:
        '200':
          description: A list of features grouped by Category ordered by ascending p-Value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupResponse'
        '500':
          description: Any Error
components:
  schemas:
    EnrichmentRequest:
      type: object
      properties:
        Genes:
          description: A list of Human Entrez ID that need functional enrichment.
          type: array
          items:
            minLength: 1
            description: Entrez ID
            type: integer
            format: int
        Background:
            description: An optional list of Human Entrez ID used as a background set. May be empty, null, or omitted.
            type: array
            items:
              minLength: 0
              description: Entrez ID
              type: integer
              format: int
        Categories:
          description: >-
            The Categories list is optional. If omitted, ToppGene will run on
            all categories with default values. Otherwise, ToppGene will only
            return the requested categories.
          nullable: true
          type: array
          items:
            description: >-
              A category specification. All properties should be specified.
              ToppGene will *not* provide defaults for missing values
            type: object
            nullable: true
            properties:
              Type:
                type: string
                enum:
                  - GeneOntologyMolecularFunction
                  - GeneOntologyBiologicalProcess
                  - GeneOntologyCellularComponent
                  - HumanPheno
                  - MousePheno
                  - Domain
                  - Pathway
                  - Pubmed
                  - Interaction
                  - Cytoband
                  - TFBS
                  - GeneFamily
                  - Coexpression
                  - CoexpressionAtlas
                  - ToppCell
                  - Computational
                  - Drug
                  - Disease
              PValue:
                type: number
                format: double
                default: 0.05
                minimum: 0
                exclusiveMinimum: false
                maximum: 1
              MinGenes:
                type: integer
                default: 2
                minimum: 1
                exclusiveMinimum: true
                maximum: 5000
              MaxGenes:
                type: integer
                default: 1500
                minimum: 1
                exclusiveMinimum: true
                maximum: 5000
              MaxResults:
                type: integer
                default: 50
                minimum: 1
                exclusiveMinimum: true
                maximum: 5000
              Correction:
                default: FDR
                type: string
                enum:
                  - None
                  - FDR
                  - Bonferroni
    EnrichmentResponse:
      type: object
      properties:
        Annotations:
          type: array
          items:
            type: object
            properties:
              Category:
                type: string
                enum:
                  - GeneOntologyMolecularFunction
                  - GeneOntologyBiologicalProcess
                  - GeneOntologyCellularComponent
                  - HumanPheno
                  - MousePheno
                  - Domain
                  - Pathway
                  - Pubmed
                  - Interaction
                  - Cytoband
                  - TFBS
                  - GeneFamily
                  - Coexpression
                  - CoexpressionAtlas
                  - ToppCell
                  - Computational
                  - Drug
                  - Disease
              ID:
                type: string
              Name:
                type: string
              PValue:
                type: number
                format: double
              QValueFDRBH:
                type: number
                format: double
              QValueFDRBY:
                type: number
                format: double
              QValueBonferroni:
                type: number
                format: double
              TotalGenes:
                type: integer
                format: double
              GenesInTerm:
                type: integer
                format: int64
              GenesInQuery:
                type: integer
                format: int64
              GenesInTermInQuery:
                type: integer
                format: int64
              Source:
                type: string
              URL:
                type: string
              Genes:
                type: array
                items:
                  type: object
                  properties:
                    Entrez:
                      type: integer
                      format: int64
                    Symbol:
                      type: string
    LookupRequest:
      type: object
      properties:
        Symbols:
          type: array
          items:
            type: string
    LookupResponse:
      type: object
      properties:
        Genes:
          description: >-
            An array of one or more genes. Unresolvable genes are *not*
            returned. If no genes are found, ToppGene returns `null` rather than
            an empty array. No guarentee is made that the array order matches
            the input order.
          minLength: 1
          nullable: true
          type: array
          items:
            type: object
            properties:
              OfficialSymbol:
                description: The official HGNC gene symbol.
                type: string
              Entrez:
                type: integer
                format: int64
              SubmittedSymbol:
                description: >-
                  The symbol as provided in the request body. Useful to
                  reconnect results to requests.
                type: string