APISpecification.yaml

openapi: 3.0.3
info:
  title: Ensembl Web Metadata API
  description: Metadata API for beta.ensembl.org
  contact:
    email: ensembl-webteam@ebi.ac.uk
  version: 0.0.1
servers:
  - url: https://beta.ensembl.org
tags:
  - name: api
    description: Ensembl Web Metadata API
paths:
  /api/metadata/genome/{genome_id_or_slug}/explain:
    get:
      description: Satisfies client's need to disambiguate a string that is part of url pathname
        and that can be either a genome id, or a genome tag. Genome ids are used to communicate
        with Ensembl apis; but genome tag only serves the purpose of keeping the url pretty and stable.
      parameters:
        - name: genome_id_or_slug
          in: path
          required: true
          schema:
            type: string
            default: grch38
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BriefGenomeDetails'
        '404':
          $ref: '#/components/responses/404NotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/stats:
    get:
      tags:
        - api
      summary: Summary statistics for a genome
      description: Summary statistics for a genome
      parameters:
        - name: genome_id
          in: path
          required: true
          schema:
            type: string
            default: a7335667-93e7-11ec-a39d-005056b38ce3
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  genome_stats:
                    $ref: '#/components/schemas/GenomeStats'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/details:
    get:
      tags:
        - api
      description: Detailed information about a genome
      parameters:
        - name: genome_id
          in: path
          required: true
          schema:
            type: string
            default: a7335667-93e7-11ec-a39d-005056b38ce3
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenomeDetails'
        '404':
          description: Genome not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Could not find details for a7335667-93e7-11ec-a39d-005056b38ce3"
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/example_objects:
    get:
      description: Returns a list of example objects (gene, variant, location, etc.) for a genome.
      parameters:
        - name: genome_id
          in: path
          required: true
          schema:
            type: string
            default: a7335667-93e7-11ec-a39d-005056b38ce3
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExampleObject'
        '404':
          description: Genome not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Could not find example objects for a7335667-93e7-11ec-a39d-005056b38ce3"
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/karyotype:
    get:
      summary: Returns a list of top-level regions included in the organism's karyotype
      parameters:
      - name: genome_id
        in: path
        required: true
        schema:
          type: string
          example: 3704ceb1-948d-11ec-a39d-005056b38ce3
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Karyotype'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/ftplinks:
    get:
      summary: Returns a list of FTP download links for the specified genome
      parameters:
      - name: genome_id
        in: path
        required: true
        schema:
          type: string
          example: 3704ceb1-948d-11ec-a39d-005056b38ce3
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FTPLink'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/checksum/{region_name}:
    get:
      summary: Returns a checksum for the specified top-level region
      parameters:
        - name: genome_id
          in: path
          required: true
          schema:
            type: string
            example: 3704ceb1-948d-11ec-a39d-005056b38ce3
        - name: region_name
          in: path
          required: true
          schema:
            type: string
            example: "13"
      responses:
        '200':
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
                example: 428d56c3fc01ad3a8db49830fb587625
        '404':
          description: Region not found
          content: {}
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/validate_location:
    get:
      summary: Checks validity of genomic location provided by user
      parameters:
      - name: genome_id
        in: query
        required: true
        schema:
          type: string
          example: 3704ceb1-948d-11ec-a39d-005056b38ce3
      - name: location
        in: query
        description: Genomic location for validation
        required: true
        schema:
          type: string
          example: 1:10000-1000000
      responses:
        '200':
          description: location validation information (location can be either valid or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationValidationResponse'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/popular_species:
    get:
      tags:
        - api
      description: List of 42 groups of genomes related to popular species
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  popular_species:
                    type: array
                    items:
                      $ref: '#/components/schemas/PopularSpecies'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/dataset/{dataset_type}/attributes:
    get:
      description: Returns a list of attributes of a given dataset of a genome.
      parameters:
        - in: query
          name: attribute_names
          schema:
            type: array
        - name: genome_id
          in: path
          required: true
          schema:
            type: string
            default: a7335667-93e7-11ec-a39d-005056b38ce3
        - name: dataset_type
          in: path
          required: true
          schema:
            type: string
            default: homologies
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  release_version:
                    type: string
                    example: "110.1"
                  attributes:
                    type: array
                    items:
                      $ref: '#/components/schemas/DatasetAttribute'

        '404':
          description: Genome not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Could not find details for genome 0cbc227a-7179-43c2-8061-a50d94423c4d and dataset homologies.'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genome/{genome_id}/vep/file_paths:
    get:
      summary: Returns the VEP file paths for the specified genome
      parameters:
        - name: genome_id
          in: path
          required: true
          schema:
            type: string
            example: 3704ceb1-948d-11ec-a39d-005056b38ce3
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  faaLocation:
                    type: string
                    example: Homo_sapiens/GCA_018473295.1/vep/genome/softmasked.fa.bgz
                  gffLocation:
                    type: string
                    example: Homo_sapiens/GCA_018473295.1/vep/ensembl/geneset/2022_08/genes.gff3.bgz
        '404':
          description: Genome ID not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Genome ID not found"
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/genomeid/:
    get:
      summary: Returns the latest genome object
      parameters:
      - name: assembly_accession_id
        in: query
        required: true
        schema:
          type: string
          example: GCA_000001405.29
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenomeIDFromAssemblyAccessionResponse'
        '404':
          $ref: '#/components/responses/404NotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /api/metadata/releases:
    get:
      tags:
        - Releases
      summary: Get release information
      description: Retrieve release data with filtering capabilities
      operationId: get_releases
      parameters:
        - name: name
          in: query
          description: Filter by one or more release names
          required: false
          schema:
            type: array
            items:
              type: number
              format: double
          style: form
          explode: false
          example:
            value: [ "2023-10-18", "2024-09" ]
        - name: current_only
          in: query
          description: Return only current partial and integrated releases
          required: false
          schema:
            type: boolean
            default: false
          example:
            value: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
        '404':
          $ref: '#/components/responses/404NotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'

components:
  schemas:
    GenomeIDFromAssemblyAccessionResponse:
      type: object
      properties:
        genome_uuid:
          type: string
          example: "a7335667-93e7-11ec-a39d-005056b38ce3"
        release_version:
          type: number
          example: "110"
        genome_tag:
          type: string
          example: "grch38"
    BriefGenomeDetails:
      type: object
      properties:
        genome_id:
          type: string
          example: a7335667-93e7-11ec-a39d-005056b38ce3
        genome_tag:
          type: string
          example: grch38
          nullable: true
        common_name:
          type: string
          example: Human
          nullable: true
        scientific_name:
          type: string
          example: Homo sapiens
        assembly:
          type: object
          properties:
            accession_id:
              type: string
              example: GCA_000001405.28
            name:
              type: string
              example: GRCh38.p13
        release:
          type: object
          properties:
            name:
              type: string
              example: 2023-10-18
            type:
              type: string
              example: partial
        type:
          $ref: '#/components/schemas/SpeciesTypeInGenome'
          nullable: true
        is_reference:
          type: boolean
      required:
        - genome_id
        - genome_tag
        - common_name
        - scientific_name
        - assembly_accession
        - assembly_name
        - type
        - is_reference
    GenomeStats:
      type: object
      properties:
        assembly_stats:
          type: object
          properties:
            contig_n50:
              type: number
              nullable: true
            total_genome_length:
              type: number
              nullable: true
            total_coding_sequence_length:
              type: number
              nullable: true
            total_gap_length:
              type: number
              nullable: true
            spanned_gaps:
              type: number
              nullable: true
            chromosomes:
              type: number
              nullable: true
            toplevel_sequences:
              type: number
              nullable: true
            component_sequences:
              type: number
              nullable: true
            gc_percentage:
              type: number
              nullable: true
          required:
            - contig_n50
            - total_genome_length
            - total_coding_sequence_length
            - total_gap_length
            - spanned_gaps
            - chromosomes
            - toplevel_sequences
            - component_sequences
            - gc_percentage
          additionalProperties: false
        coding_stats:
          type: object
          properties:
            coding_genes:
              type: number
              nullable: true
            average_genomic_span:
              type: number
              nullable: true
            average_sequence_length:
              type: number
              nullable: true
            average_cds_length:
              type: number
              nullable: true
            shortest_gene_length:
              type: number
              nullable: true
            longest_gene_length:
              type: number
              nullable: true
            total_transcripts:
              type: number
              nullable: true
            coding_transcripts:
              type: number
              nullable: true
            transcripts_per_gene:
              type: number
              nullable: true
            coding_transcripts_per_gene:
              type: number
              nullable: true
            total_exons:
              type: number
              nullable: true
            total_coding_exons:
              type: number
              nullable: true
            average_exon_length:
              type: number
              nullable: true
            average_coding_exon_length:
              type: number
              nullable: true
            average_exons_per_transcript:
              type: number
              nullable: true
            average_coding_exons_per_coding_transcript:
              type: number
              nullable: true
            total_introns:
              type: number
              nullable: true
            average_intron_length:
              type: number
              nullable: true
          required:
            - coding_genes
            - average_genomic_span
            - average_sequence_length
            - average_cds_length
            - shortest_gene_length
            - longest_gene_length
            - total_transcripts
            - coding_transcripts
            - transcripts_per_gene
            - coding_transcripts_per_gene
            - total_exons
            - total_coding_exons
            - average_exon_length
            - average_coding_exon_length
            - average_exons_per_transcript
            - average_coding_exons_per_coding_transcript
            - total_introns
            - average_intron_length
          additionalProperties: false
        non_coding_stats:
          type: object
          properties:
            non_coding_genes:
              type: number
              nullable: true
            small_non_coding_genes:
              type: number
              nullable: true
            long_non_coding_genes:
              type: number
              nullable: true
            misc_non_coding_genes:
              type: number
              nullable: true
            average_genomic_span:
              type: number
              nullable: true
            average_sequence_length:
              type: number
              nullable: true
            shortest_gene_length:
              type: number
              nullable: true
            longest_gene_length:
              type: number
              nullable: true
            total_transcripts:
              type: number
              nullable: true
            transcripts_per_gene:
              type: number
              nullable: true
            total_exons:
              type: number
              nullable: true
            average_exon_length:
              type: number
              nullable: true
            average_exons_per_transcript:
              type: number
              nullable: true
            total_introns:
              type: number
              nullable: true
            average_intron_length:
              type: number
              nullable: true
          required:
            - non_coding_genes
            - small_non_coding_genes
            - long_non_coding_genes
            - misc_non_coding_genes
            - average_genomic_span
            - average_sequence_length
            - shortest_gene_length
            - longest_gene_length
            - total_transcripts
            - transcripts_per_gene
            - total_exons
            - average_exon_length
            - average_exons_per_transcript
            - total_introns
            - average_intron_length
          additionalProperties: false
        pseudogene_stats:
          type: object
          properties:
            pseudogenes:
              type: number
              nullable: true
            average_genomic_span:
              type: number
              nullable: true
            average_sequence_length:
              type: number
              nullable: true
            shortest_gene_length:
              type: number
              nullable: true
            longest_gene_length:
              type: number
              nullable: true
            total_transcripts:
              type: number
              nullable: true
            transcripts_per_gene:
              type: number
              nullable: true
            total_exons:
              type: number
              nullable: true
            average_exon_length:
              type: number
              nullable: true
            average_exons_per_transcript:
              type: number
              nullable: true
            total_introns:
              type: number
              nullable: true
            average_intron_length:
              type: number
              nullable: true
          required:
            - pseudogenes
            - average_genomic_span
            - average_sequence_length
            - shortest_gene_length
            - longest_gene_length
            - total_transcripts
            - transcripts_per_gene
            - total_exons
            - average_exon_length
            - average_exons_per_transcript
            - total_introns
            - average_intron_length
          additionalProperties: false
        homology_stats:
          type: object
          properties:
            coverage:
              type: number
            reference_species_name:
              type: string
              description: Scientific name of the species against which homology was calculated
              example: Homo sapiens
              nullable: true
          required:
            - coverage
            - reference_species_name
          additionalProperties: false
        variation_stats:
          properties:
            short_variants:
              type: number
              nullable: true
            structural_variants:
              type: number
              nullable: true
            short_variants_with_phenotype_assertions:
              type: number
              nullable: true
            short_variants_with_publications:
              type: number
              nullable: true
            short_variants_frequency_studies:
              type: number
              nullable: true
            structural_variants_with_phenotype_assertions:
              type: number
              nullable: true
          required:
            - short_variants
            - structural_variants
            - short_variants_with_phenotype_assertions
            - short_variants_with_publications
            - short_variants_frequency_studies
            - structural_variants_with_phenotype_assertions
          type: object
          nullable: true
        regulation_stats:
          type: object
          properties:
            enhancers:
              type: number
              nullable: true
            promoters:
              type: number
              nullable: true
            open_chromatin_count:
              type: number
              nullable: true
            ctcf_count:
              type: number
              nullable: true
            tfbs_count:
              type: number
              nullable: true
          required:
            - enhancers
            - promoters
            - open_chromatin_count
            - ctcf_count
            - tfbs_count
          nullable: true
      required:
        - assembly_stats
        - coding_stats
        - non_coding_stats
        - pseudogene_stats
        - homology_stats
        - variation_stats
        - regulation_stats
      additionalProperties: false
    DatasetAttribute:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        version:
          type: string
        uuid:
          type: string
        type:
          type: string
    PopularSpecies:
      type: object
      properties:
        species_taxonomy_id:
          anyOf:
            - type: string
            - type: number
        name:
          type: string
          description: Human-friendly text to show in the tooltip ( common_name if exists else scientific_name )
        image:
          type: string
          description: Url of the associated svg
        genomes_count:
          type: number
          description: The number of genomes associated with this species
      required:
        - id
        - name
        - image
        - members_count
    AssemblyInGenome:
      properties:
        accession_id:
          type: string
          example: GCA_018466855.1
        name:
          type: string
          example: HG02559.alt.pat.f1_v2
        url:
          type: string
          example: https://identifiers.org/insdc.gca/GCA_018466855.1
          nullable: true
      required:
        - accession_id
        - name
        - url
      additionalProperties: false
      type: object
    AssemblyProvider:
      type: object
      properties:
        name:
          type: string
          example: UCSC Genomics Institute
        url:
          type: string
          example: https://genomics.ucsc.edu
          nullable: true
      required:
        - name
        - url
    AnnotationProvider:
      type: object
      properties:
        name:
          type: string
          example: UCSC Genomics Institute
        url:
          type: string
          example: https://genomics.ucsc.edu
          nullable: true
      required:
        - name
        - url
    SpeciesTypeInGenome:
      properties:
        kind:
          type: string
          example: population
        value:
          type: string
          example: African Caribbean In Barbados
      required:
        - kind
        - value
      additionalProperties: false
      type: object
    GenomeDetails:
      properties:
        genome_id:
          type: string
          example: a7335667-93e7-11ec-a39d-005056b38ce3
        genome_tag:
          type: string
          example: grch38
          nullable: true
        taxonomy_id:
          type: string
          example: "9606"
          description: Identifier of the taxon that the genome belongs to.
            May be the same as species_taxonomy_id, or different.
        species_taxonomy_id:
          type: string
          example: "1"
          description: required to be able to retrieve a list of related genomes
        common_name:
          type: string
          example: human
          nullable: true
        scientific_name:
          type: string
          example: Homo sapiens
        type:
          $ref: '#/components/schemas/SpeciesTypeInGenome'
          nullable: true
        is_reference:
          type: boolean
        assembly:
          $ref: '#/components/schemas/AssemblyInGenome'
        assembly_provider:
          $ref: '#/components/schemas/AssemblyProvider'
          nullable: true
        assembly_level:
          type: string
          example: complete genome
        assembly_date:
          type: string
          description: ISO date string in the YYYY-MM format
          example: "2019-02"
          nullable: true
        annotation_provider:
          $ref: '#/components/schemas/AnnotationProvider'
          nullable: true
        annotation_method:
          type: string
          example: import
          nullable: true
        annotation_version:
          type: string
          example: GENCODE 34
          nullable: true
        annotation_date:
          type: string
          description: ISO date string in the YYYY-MM format
          example: "2019-02"
          nullable: true
        number_of_genomes_in_group:
          type: number
          description: The number of genomes, including the current one, that share the same species taxonomy id.
            May just mean the number of alternative assemblies; but may also include genomes
            that have the same assembly, but different annotations.
      required:
        - genome_id
        - genome_tag
        - taxonomy_id
        - species_taxonomy_id
        - common_name
        - scientific_name
        - type
        - is_reference
        - assembly
        - assembly_provider
        - assembly_level
        - assembly_date
        - annotation_provider
        - annotation_method
        - annotation_version
        - annotation_date
        - related_genomes_count
      additionalProperties: false
      type: object
    ExampleObject:
      type: object
      properties:
        id:
          type: string
          example: ENSG00000139618
        type:
          type: string
          description: Member of a controlled vocabulary. Examples include "gene", "location", "variant"
          example: gene
    Karyotype:
      type: array
      items:
        $ref: '#/components/schemas/TopLevelRegion'
    TopLevelRegion:
      type: object
      properties:
        name:
          type: string
          example: "1"
        type:
          type: string
          example: "chromosome"
        length:
          type: integer
          example: 248956422
        is_circular:
          type: boolean
          example: false
    LocationValidationResponse:
      type: object
      properties:
        start:
          type: object
          properties:
            value:
              type: integer
              example: 32272495
            is_valid:
              type: boolean
            error_code:
              type: string
              nullable: true
              description: error code for programmatic response; null if the start coordinate is valid
            error_message:
              type: string
              nullable: true
              description: human-readable description of error; null if the start coordinate is valid
        end:
          type: object
          properties:
            value:
              type: integer
              example: 32442859
            is_valid:
              type: boolean
            error_code:
              type: string
              nullable: true
              description: error code for programmatic response; null if the end coordinate is valid
            error_message:
              type: string
              nullable: true
              description: human-readable description of error; null if the end coordinate is valid
        region:
          type: object
          properties:
            region_name:
              type: string
              example: "13"
              description: Name of the region as it is used at Ensembl.
                If we support other region formats in user input (e.g. UCSC region name, such as "chr13"),
                then this field will normalise user input to Ensembl region name
            is_valid:
              type: boolean
            error_code:
              type: string
              nullable: true
              description: error code for programmatic response; null if region name is valid
            error_message:
              type: string
              nullable: true
              description: human-readable description of error; null if region name is valid
        location:
          type: string
          example: "13:32272495-32442859"
          nullable: true
          description: >
            Contains Ensembl-formatted location string that will make sense to the genome browser.
            Is set to null if the location is invalid.
            (Note that if we support other region formats in user input, such as UCSC region name,
            then the region segment of the location string will be normalised to Ensembl region names,
            e.g. instead of chr13:32272495-32442859, it will say 13:32272495-32442859.)
    FTPLink:
      type: object
      properties:
        dataset:
          type: string
          enum:
            - genebuild
            - assembly
            - homologies
            - regulation
            - variation
        url:
          type: string
          example: https://ftp.ebi.ac.uk/pub/ensemblorganisms/Homo_sapiens/GCA_000001405.29/ensembl/genome
      required:
        - dataset
        - url
      additionalProperties: false
      description: FTP link to a dataset directory for a genome
    Release:
      type: object
      properties:
        name:
          type: string
          example: "2023-10-18"
        type:
          type: string
          enum: [ integrated, partial ]
          example: "partial"
        is_current:
          type: boolean
          example: true
      required:
        - name
        - type
        - is_current
  responses:
    404NotFound:
      description: The specified resource was not found
      content:
        text/plain:
          schema:
            type: string
            example: '{"status_code": 404, "details": "Not Found"}'
    500InternalServerError:
      description: Internal server error
      content:
        text/plain:
          schema:
            type: string
            example: '{"status_code": 500, "details": "Internal Server Error"}'