annotrieve-api-specs.yaml

openapi: 3.1.0

info:
  version: "1.0.0"
  title: "Annotrieve API"
  description: "API for retrieving and managing eukaryotic genome annotations"
  contact:
    email: "emilio.righi@crg.eu"

servers:
  - url: https://genome.crg.es/annotrieve/api/v0
    description: Production server

tags:
  - name: "annotations"
    description: "Genome annotation endpoints"
  - name: "assemblies"
    description: "Assembly information endpoints"
  - name: "organisms"
    description: "Organism information endpoints"
  - name: "taxons"
    description: "Taxonomy information endpoints"
  - name: "bioprojects"
    description: "BioProject information endpoints"
  - name: "analytics"
    description: "Public usage analytics endpoints"

paths:
  /annotations:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotations"
      summary: "Get annotations"
      description: "Returns annotation metadata filtered, sorted, and paginated via query parameters."
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_order"
        - $ref: "#/components/parameters/fields"
      responses:
        "200":
          description: "Annotations page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedAnnotationsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postAnnotations"
      summary: "Get annotations via POST"
      description: "Same as GET /annotations, but accepts filters in the request body."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "Annotations page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedAnnotationsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/report:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationsReport"
      summary: "Download annotation metadata as TSV"
      description: "Streams a TSV file with annotation metadata columns. By default exports annotation_id, assembly_accession, assembly_name, organism_name, taxid, database, provider, source_url, bgzip_path, and csi_path. Use selected_fields to append additional extended columns, including assembly-derived fields (assembly_refseq_category, assembly_download_url, assembly_gc_percent) resolved via a join on assembly_accession."
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/selected_fields"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_order"
      responses:
        "200":
          description: "TSV stream"
          content:
            text/tab-separated-values:
              schema:
                type: string
                description: "TSV payload streamed line by line"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postAnnotationsReport"
      summary: "Download annotation metadata via POST"
      description: "Same as GET /annotations/report, but accepts filters in the request body. Omit selected_fields to preserve the default production column set; provide it to append extended columns after the defaults, including assembly-derived fields (assembly_refseq_category, assembly_download_url, assembly_gc_percent) resolved via a join on assembly_accession."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "TSV stream"
          content:
            text/tab-separated-values:
              schema:
                type: string
                description: "TSV payload streamed line by line"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/frequencies:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationFrequencyFields"
      summary: "List allowed annotation frequency fields"
      responses:
        "200":
          description: "Frequency-capable fields"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FrequencyFieldList"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/frequencies/{field}:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationFrequencies"
      summary: "Get annotation field frequencies"
      description: "Returns frequency counts for the selected field across filtered annotations."
      parameters:
        - name: field
          in: path
          required: true
          description: "Field to aggregate. Allowed values: taxid, organism_name, database, release_date, assembly_accession, assembly_name, feature_type, feature_source, biotype, pipeline, provider."
          schema:
            type: string
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Frequency counts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FrequencyCounts"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postAnnotationFrequencies"
      summary: "Get annotation field frequencies via POST"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "Frequency counts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FrequencyCounts"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/errors:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationErrors"
      summary: "List annotation import errors"
      parameters:
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: "Annotation errors"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedAnnotationErrorsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/aggregates/taxons:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationsAggregatesByTaxonRank"
      summary: "Get annotation aggregates grouped by taxon rank"
      description: "Returns one record per taxon at the given rank with average coding/non-coding/pseudogene gene counts and annotation count."
      parameters:
        - name: rank
          in: query
          required: true
          description: "Taxonomic rank to aggregate by."
          schema:
            type: string
            enum: ["domain", "kingdom", "phylum", "class", "order", "family", "genus"]
      responses:
        "200":
          description: "Aggregates by taxon"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnnotationsAggregatesByTaxonResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/gene-stats:
    get:
      tags:
        - "annotations"
      operationId: "getGeneStats"
      summary: "Get gene stats summary"
      description: "Returns gene stats summary with aggregated statistics across all categories (coding, non_coding, pseudogene)."
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Gene stats summary"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneStatsSummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postGeneStats"
      summary: "Get gene stats summary via POST"
      description: "Same as GET /annotations/gene-stats, but accepts filters in the request body."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "Gene stats summary"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneStatsSummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/gene-stats/{category}:
    get:
      tags:
        - "annotations"
      operationId: "getGeneCategoryDetails"
      summary: "Get detailed statistics for a specific gene category"
      description: "Returns detailed statistics for a specific gene category (coding, non_coding, or pseudogene)."
      parameters:
        - name: category
          in: path
          required: true
          description: "Gene category name (coding, non_coding, or pseudogene)"
          schema:
            type: string
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Gene category details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneCategoryDetailsResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postGeneCategoryDetails"
      summary: "Get gene category details via POST"
      description: "Same as GET /annotations/gene-stats/{category}, but accepts filters in the request body."
      parameters:
        - name: category
          in: path
          required: true
          description: "Gene category name (coding, non_coding, or pseudogene)"
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "Gene category details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneCategoryDetailsResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/gene-stats/{category}/{metric}:
    get:
      tags:
        - "annotations"
      operationId: "getGeneCategoryMetricValues"
      summary: "Get raw values for a specific metric in a gene category"
      description: "Returns raw values for a specific metric in a specific gene category (for plotting histograms)."
      parameters:
        - name: category
          in: path
          required: true
          description: "Gene category name (coding, non_coding, or pseudogene)"
          schema:
            type: string
        - name: metric
          in: path
          required: true
          description: "Metric name (total_count or average_mean_length)"
          schema:
            type: string
        - name: include_annotations
          in: query
          description: "If true, include annotation_ids list in response"
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Metric values"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneCategoryMetricValuesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postGeneCategoryMetricValues"
      summary: "Get gene category metric values via POST"
      description: "Same as GET /annotations/gene-stats/{category}/{metric}, but accepts filters in the request body."
      parameters:
        - name: category
          in: path
          required: true
          description: "Gene category name (coding, non_coding, or pseudogene)"
          schema:
            type: string
        - name: metric
          in: path
          required: true
          description: "Metric name (total_count or average_mean_length)"
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AnnotationQueryParams"
                - type: object
                  properties:
                    include_annotations:
                      type: boolean
                      description: "If true, include annotation_ids list in response"
                      default: false
      responses:
        "200":
          description: "Metric values"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneCategoryMetricValuesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/transcript-stats:
    get:
      tags:
        - "annotations"
      operationId: "getTranscriptStats"
      summary: "Get transcript stats summary"
      description: "Returns transcript stats summary with aggregated statistics across all transcript types."
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Transcript stats summary"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranscriptStatsSummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postTranscriptStats"
      summary: "Get transcript stats summary via POST"
      description: "Same as GET /annotations/transcript-stats, but accepts filters in the request body."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "Transcript stats summary"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranscriptStatsSummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/transcript-stats/{type}:
    get:
      tags:
        - "annotations"
      operationId: "getTranscriptTypeDetails"
      summary: "Get detailed statistics for a specific transcript type"
      description: "Returns detailed statistics for a specific transcript type."
      parameters:
        - name: type
          in: path
          required: true
          description: "Transcript type name"
          schema:
            type: string
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Transcript type details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranscriptTypeDetailsResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postTranscriptTypeDetails"
      summary: "Get transcript type details via POST"
      description: "Same as GET /annotations/transcript-stats/{type}, but accepts filters in the request body."
      parameters:
        - name: type
          in: path
          required: true
          description: "Transcript type name"
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "Transcript type details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranscriptTypeDetailsResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/transcript-stats/{type}/{metric}:
    get:
      tags:
        - "annotations"
      operationId: "getTranscriptTypeMetricValues"
      summary: "Get raw values for a specific metric in a transcript type"
      description: "Returns raw values for a specific metric in a specific transcript type (for plotting histograms)."
      parameters:
        - name: type
          in: path
          required: true
          description: "Transcript type name"
          schema:
            type: string
        - name: metric
          in: path
          required: true
          description: "Metric name (e.g., total_count, average_mean_length, exon_total_count, cds_total_count, etc.)"
          schema:
            type: string
        - name: include_annotations
          in: query
          description: "If true, include annotation_ids list in response"
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Metric values"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranscriptTypeMetricValuesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postTranscriptTypeMetricValues"
      summary: "Get transcript type metric values via POST"
      description: "Same as GET /annotations/transcript-stats/{type}/{metric}, but accepts filters in the request body."
      parameters:
        - name: type
          in: path
          required: true
          description: "Transcript type name"
          schema:
            type: string
        - name: metric
          in: path
          required: true
          description: "Metric name (e.g., total_count, average_mean_length, exon_total_count, cds_total_count, etc.)"
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AnnotationQueryParams"
                - type: object
                  properties:
                    include_annotations:
                      type: boolean
                      description: "If true, include annotation_ids list in response"
                      default: false
      responses:
        "200":
          description: "Metric values"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranscriptTypeMetricValuesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/busco-stats:
    get:
      tags:
        - "annotations"
      operationId: "getBuscoStats"
      summary: "Get BUSCO stats summary"
      description: "Returns BUSCO stats summary with aggregated statistics for metrics only (complete, single_copy, duplicated, fragmented, missing). No categories."
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "BUSCO stats summary"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BuscoStatsSummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postBuscoStats"
      summary: "Get BUSCO stats summary via POST"
      description: "Same as GET /annotations/busco-stats, but accepts filters in the request body."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationQueryParams"
      responses:
        "200":
          description: "BUSCO stats summary"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BuscoStatsSummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/busco-stats/{metric}:
    get:
      tags:
        - "annotations"
      operationId: "getBuscoMetricValues"
      summary: "Get raw values for a specific BUSCO metric"
      description: "Returns raw values for a specific BUSCO metric (for plotting histograms)."
      parameters:
        - name: metric
          in: path
          required: true
          description: "BUSCO metric name (complete, single_copy, duplicated, fragmented, or missing)"
          schema:
            type: string
            enum: ["complete", "single_copy", "duplicated", "fragmented", "missing"]
        - name: include_annotations
          in: query
          description: "If true, include annotation_ids list in response"
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/bioproject_accessions"
        - $ref: "#/components/parameters/db_sources"
        - $ref: "#/components/parameters/feature_sources"
        - $ref: "#/components/parameters/biotypes"
        - $ref: "#/components/parameters/feature_types"
        - $ref: "#/components/parameters/pipelines"
        - $ref: "#/components/parameters/providers"
        - $ref: "#/components/parameters/md5_checksums"
        - $ref: "#/components/parameters/has_stats"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/release_date_from"
        - $ref: "#/components/parameters/release_date_to"
      responses:
        "200":
          description: "Metric values"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BuscoMetricValuesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "annotations"
      operationId: "postBuscoMetricValues"
      summary: "Get BUSCO metric values via POST"
      description: "Same as GET /annotations/busco-stats/{metric}, but accepts filters in the request body."
      parameters:
        - name: metric
          in: path
          required: true
          description: "BUSCO metric name (complete, single_copy, duplicated, fragmented, or missing)"
          schema:
            type: string
            enum: ["complete", "single_copy", "duplicated", "fragmented", "missing"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AnnotationQueryParams"
                - type: object
                  properties:
                    include_annotations:
                      type: boolean
                      description: "If true, include annotation_ids list in response"
                      default: false
      responses:
        "200":
          description: "Metric values"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BuscoMetricValuesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/upload-gff:
    post:
      tags:
        - "annotations"
      operationId: "uploadCustomGff"
      summary: "Upload a custom GFF/GFF3 file"
      description: "Upload a custom GFF/GFF3 file and enqueue a background job to compute feature summary and statistics. Subject to a per-client daily rate limit."
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - custom_name
              properties:
                file:
                  type: string
                  format: binary
                  description: "GFF/GFF3 file (.gff, .gff3, .gff.gz, or .gff3.gz)"
                custom_name:
                  type: string
                  description: "Display name for the uploaded annotation"
      responses:
        "200":
          description: "Upload accepted and job enqueued"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadGffResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "413":
          description: "Uploaded file is too large"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: "Daily upload limit reached"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/upload-gff/jobs/{task_id}:
    get:
      tags:
        - "annotations"
      operationId: "getUploadGffJobStatus"
      summary: "Get custom GFF upload job status"
      description: "Returns the status of a custom GFF upload background job."
      parameters:
        - name: task_id
          in: path
          required: true
          description: "Celery task ID returned by POST /annotations/upload-gff"
          schema:
            type: string
      responses:
        "200":
          description: "Job status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadJobStatusResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/upload-gff/rate-limit:
    get:
      tags:
        - "annotations"
      operationId: "getUploadGffRateLimit"
      summary: "Get custom GFF upload rate-limit status"
      description: "Returns how many uploads were used in the last 24 hours and remaining quota for the calling client."
      responses:
        "200":
          description: "Rate-limit status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadRateLimitResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/{md5_checksum}:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationById"
      summary: "Get annotation by checksum"
      parameters:
        - name: md5_checksum
          in: path
          required: true
          description: "MD5 checksum of the annotation (32 lowercase hex characters)."
          schema:
            type: string
            pattern: '^[a-f0-9]{32}$'
      responses:
        "200":
          description: "Annotation details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Annotation"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/{md5_checksum}/gff:
    get:
      tags:
        - "annotations"
      operationId: "streamAnnotationGff"
      summary: "Stream filtered GFF3 for an annotation"
      description: "Streams GFF3 lines for the given annotation. At least one filter (region, feature_type, feature_source, or biotype) must be provided."
      parameters:
        - name: md5_checksum
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{32}$'
        - name: region
          in: query
          description: "Sequence/contig identifier or alias."
          schema:
            type: string
        - name: start
          in: query
          description: "Start position (0-based)."
          schema:
            type: integer
            minimum: 0
        - name: end
          in: query
          description: "End position (inclusive)."
          schema:
            type: integer
            minimum: 0
        - name: feature_type
          in: query
          description: "Filter by GFF feature type (column 3)."
          schema:
            type: string
        - name: feature_source
          in: query
          description: "Filter by GFF feature source (column 2)."
          schema:
            type: string
        - name: biotype
          in: query
          description: "Filter by feature biotype (attribute)."
          schema:
            type: string
      responses:
        "200":
          description: "GFF3 stream"
          content:
            text/plain:
              schema:
                type: string
                description: "GFF3 lines streamed as plain text"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/{md5_checksum}/contigs:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationContigs"
      summary: "List contigs available for an annotation"
      description: "Streams newline-separated contig identifiers from the annotation's Tabix index."
      parameters:
        - name: md5_checksum
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{32}$'
      responses:
        "200":
          description: "Contig IDs"
          content:
            text/plain:
              schema:
                type: string
                description: "Newline-separated contig identifiers"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /annotations/{md5_checksum}/contigs/aliases:
    get:
      tags:
        - "annotations"
      operationId: "getAnnotationContigAliases"
      summary: "Get contig alias mappings"
      parameters:
        - name: md5_checksum
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{32}$'
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: "Sequence alias mappings"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSequenceAliasesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies:
    get:
      tags:
        - "assemblies"
      operationId: "getAssemblies"
      summary: "Get assemblies"
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/submitters"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_order"
      responses:
        "200":
          description: "Assemblies page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedAssembliesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "assemblies"
      operationId: "postAssemblies"
      summary: "Get assemblies via POST"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssemblyQueryParams"
      responses:
        "200":
          description: "Assemblies page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedAssembliesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies/frequencies/{field}:
    get:
      tags:
        - "assemblies"
      operationId: "getAssemblyFrequencies"
      summary: "Get assembly field frequencies"
      parameters:
        - name: field
          in: path
          required: true
          description: "Field to aggregate. Allowed values: organism_name, submitter, source_database, assembly_level, refseq_category, assembly_status, assembly_type."
          schema:
            type: string
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/assembly_accessions"
        - $ref: "#/components/parameters/refseq_categories"
        - $ref: "#/components/parameters/assembly_levels"
        - $ref: "#/components/parameters/assembly_statuses"
        - $ref: "#/components/parameters/assembly_types"
        - $ref: "#/components/parameters/submitters"
      responses:
        "200":
          description: "Frequency counts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FrequencyCounts"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "assemblies"
      operationId: "postAssemblyFrequencies"
      summary: "Get assembly field frequencies via POST"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssemblyQueryParams"
      responses:
        "200":
          description: "Frequency counts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FrequencyCounts"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies/{assembly_accession}:
    get:
      tags:
        - "assemblies"
      operationId: "getAssemblyById"
      summary: "Get assembly by accession"
      parameters:
        - name: assembly_accession
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Assembly details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Assembly"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies/{assembly_accession}/chr-aliases:
    get:
      tags:
        - "assemblies"
      operationId: "getChromosomeAliases"
      summary: "Download chromosome alias table"
      description: "Streams a TSV file listing chromosome aliases for the assembly (chr_name, sequence_name, GenBank accession, RefSeq accession, UCSC name, aliases)."
      parameters:
        - name: assembly_accession
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "TSV stream"
          content:
            text/tab-separated-values:
              schema:
                type: string
                description: "Tab-separated alias table"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies/{assembly_accession}/chr_aliases:
    get:
      tags:
        - "assemblies"
      operationId: "getChromosomeAliasesDeprecated"
      summary: "Download chromosome alias table (deprecated)"
      deprecated: true
      description: "Deprecated. Use /assemblies/{assembly_accession}/chr-aliases instead. Streams a TSV file listing chromosome aliases for the assembly (chr_name, sequence_name, GenBank accession, RefSeq accession, UCSC name, aliases)."
      parameters:
        - name: assembly_accession
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "TSV stream"
          content:
            text/tab-separated-values:
              schema:
                type: string
                description: "Tab-separated alias table"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies/{assembly_accession}/assembled-molecules:
    get:
      tags:
        - "assemblies"
      operationId: "getAssembledMolecules"
      summary: "Download chromosomes.json for an assembly"
      description: "Streams chromosomes.json from LOCAL_ANNOTATIONS_DIR ({taxid}/{assembly_accession}/chromosomes.json), or from the paired assembly when the primary file is missing."
      parameters:
        - name: assembly_accession
          in: path
          required: true
          schema:
            type: string
        - name: offset
          in: query
          deprecated: true
          description: "Deprecated; ignored. Kept for backward compatibility."
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          deprecated: true
          description: "Deprecated; ignored. Kept for backward compatibility."
          schema:
            type: integer
            minimum: 1
            default: 20
      responses:
        "200":
          description: "chromosomes.json (array of NCBI assembly report molecules)"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ChromosomeReportEntry"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies/{assembly_accession}/assembled_molecules:
    get:
      tags:
        - "assemblies"
      operationId: "getAssembledMoleculesDeprecatedUnderscore"
      summary: "Download chromosomes.json for an assembly (deprecated)"
      deprecated: true
      description: "Deprecated. Use /assemblies/{assembly_accession}/assembled-molecules instead. Streams chromosomes.json from LOCAL_ANNOTATIONS_DIR."
      parameters:
        - name: assembly_accession
          in: path
          required: true
          schema:
            type: string
        - name: offset
          in: query
          deprecated: true
          description: "Deprecated; ignored. Kept for backward compatibility."
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          deprecated: true
          description: "Deprecated; ignored. Kept for backward compatibility."
          schema:
            type: integer
            minimum: 1
            default: 20
      responses:
        "200":
          description: "chromosomes.json (array of NCBI assembly report molecules)"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ChromosomeReportEntry"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /assemblies/{assembly_accession}/paired:
    get:
      tags:
        - "assemblies"
      operationId: "getPairedAssembly"
      summary: "Get the paired assembly"
      description: "Returns the paired RefSeq/GenBank assembly when available."
      parameters:
        - name: assembly_accession
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Paired assembly"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Assembly"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /organisms:
    get:
      tags:
        - "organisms"
      operationId: "getOrganisms"
      summary: "Get organisms"
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_order"
      responses:
        "200":
          description: "Organisms page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedOrganismsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "organisms"
      operationId: "postOrganisms"
      summary: "Get organisms via POST"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrganismQueryParams"
      responses:
        "200":
          description: "Organisms page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedOrganismsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /organisms/{taxid}:
    get:
      tags:
        - "organisms"
      operationId: "getOrganismById"
      summary: "Get organism by taxid"
      parameters:
        - name: taxid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Organism details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organism"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /taxons:
    get:
      tags:
        - "taxons"
      operationId: "getTaxons"
      summary: "Get taxonomy nodes"
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/taxids"
        - $ref: "#/components/parameters/rank"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_order"
      responses:
        "200":
          description: "Taxon nodes"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedTaxonsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "taxons"
      operationId: "postTaxons"
      summary: "Get taxonomy nodes via POST"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TaxonQueryParams"
      responses:
        "200":
          description: "Taxon nodes"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedTaxonsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /taxons/flattened-tree:
    get:
      tags:
        - "taxons"
      operationId: "getFlattenedTree"
      summary: "Get flattened taxonomy tree"
      description: "Returns a flattened taxonomy tree. When a prebuilt export exists, responds with a 307 redirect to the static file under /annotrieve/files/taxonomy/. Otherwise returns an on-the-fly aggregation as JSON ({fields, rows}) or a TSV stream depending on format."
      parameters:
        - name: format
          in: query
          description: "Response format: json (default) or tsv."
          schema:
            type: string
            enum: ["json", "tsv"]
            default: "json"
      responses:
        "200":
          description: "Flattened taxonomy tree"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlattenedTreeResponse"
            text/tab-separated-values:
              schema:
                type: string
                description: "TSV payload streamed line by line"
        "307":
          description: "Redirect to prebuilt static flattened-tree file when available"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /taxons/{taxid}:
    get:
      tags:
        - "taxons"
      operationId: "getTaxonById"
      summary: "Get taxon node by taxid"
      parameters:
        - name: taxid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Taxon node details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaxonNode"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /taxons/frequencies/rank:
    get:
      tags:
        - "taxons"
      operationId: "getTaxonRankFrequencies"
      summary: "Get rank frequencies"
      responses:
        "200":
          description: "Rank frequency counts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RankFrequencies"
        "500":
          $ref: "#/components/responses/InternalError"

  /taxons/{taxid}/children:
    get:
      tags:
        - "taxons"
      operationId: "getTaxonChildren"
      summary: "List children of a taxon"
      parameters:
        - name: taxid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Children taxon nodes"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedTaxonsResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /taxons/{taxid}/ancestors:
    get:
      tags:
        - "taxons"
      operationId: "getTaxonAncestors"
      summary: "Get ancestor lineage"
      parameters:
        - name: taxid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Ancestor lineage"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaxonAncestorsResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /bioprojects:
    get:
      tags:
        - "bioprojects"
      operationId: "getBioprojects"
      summary: "Get BioProjects"
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_order"
      responses:
        "200":
          description: "BioProjects page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedBioprojectsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - "bioprojects"
      operationId: "postBioprojects"
      summary: "Get BioProjects via POST"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BioprojectQueryParams"
      responses:
        "200":
          description: "BioProjects page"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedBioprojectsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /bioprojects/{accession}:
    get:
      tags:
        - "bioprojects"
      operationId: "getBioprojectById"
      summary: "Get BioProject by accession"
      parameters:
        - name: accession
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "BioProject details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BioProject"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /analytics/frequencies/country:
    get:
      tags:
        - "analytics"
      operationId: "getCountryFrequencies"
      summary: "Get unique users by country"
      description: "Returns frequency counts of unique users by country. Each user is identified by an anonymous fingerprint (HMAC of IP)."
      responses:
        "200":
          description: "Country frequency counts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FrequencyCounts"
        "500":
          $ref: "#/components/responses/InternalError"

  /analytics/top-visitors:
    get:
      tags:
        - "analytics"
      operationId: "getTopVisitors"
      summary: "Get top anonymous visitors by visit days"
      deprecated: true
      description: "Top anonymous visitors by distinct visit days. Prefer /analytics/top-countries for public usage UI. Never returns fingerprints or IPs."
      parameters:
        - name: limit
          in: query
          description: "Maximum number of visitors to return (capped at 5)"
          schema:
            type: integer
            minimum: 1
            maximum: 5
            default: 5
      responses:
        "200":
          description: "Top visitors"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopVisitorsResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /analytics/summary:
    get:
      tags:
        - "analytics"
      operationId: "getUsageSummary"
      summary: "Get public usage summary metrics"
      description: "Public usage hero metrics from UserAnalytics (API-activity users). Never returns fingerprints or IPs."
      responses:
        "200":
          description: "Usage summary"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageSummaryResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /analytics/top-countries:
    get:
      tags:
        - "analytics"
      operationId: "getTopCountries"
      summary: "Get top countries by unique users"
      description: "Top countries by unique users (fingerprints), not visit-day counts."
      parameters:
        - name: limit
          in: query
          description: "Maximum number of countries to return"
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        "200":
          description: "Top countries"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopCountriesResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /analytics/capabilities:
    get:
      tags:
        - "analytics"
      operationId: "getUsageCapabilities"
      summary: "Get product-capability usage"
      description: "Product-capability usage from UsageRollup (unique users who touched each bucket). Empty items if the daily rollup has not run yet."
      responses:
        "200":
          description: "Capability usage"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageCapabilitiesResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /analytics/top-entities:
    get:
      tags:
        - "analytics"
      operationId: "getTopEntities"
      summary: "Get top opened entities"
      description: "Top-10 opened assemblies, annotations, and taxons by unique users."
      responses:
        "200":
          description: "Top entities"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopEntitiesResponse"
        "500":
          $ref: "#/components/responses/InternalError"

components:
  parameters:
    filter:
      name: "filter"
      in: "query"
      description: "Text search filter across multiple fields"
      schema:
        type: "string"
    limit:
      name: "limit"
      in: "query"
      description: "Maximum number of results to return"
      schema:
        type: "integer"
        minimum: 1
        maximum: 1000
        default: 20
    offset:
      name: "offset"
      in: "query"
      description: "Number of results to skip"
      schema:
        type: "integer"
        minimum: 0
        default: 0
    taxids:
      name: "taxids"
      in: "query"
      description: "Comma-separated list of taxonomy IDs"
      schema:
        type: "string"
      example: "9606,10090,7227"
    bioproject_accessions:
      name: "bioproject_accessions"
      in: "query"
      description: "Comma-separated list of BioProject accessions"
      schema:
        type: "string"
      example: "PRJNA123456,PRJNA123457"
    assembly_accessions:
      name: "assembly_accessions"
      in: "query"
      description: "Comma-separated list of assembly accessions"
      schema:
        type: "string"
      example: "GCA_000001405.29,GCF_000001405.40"
    db_sources:
      name: "db_sources"
      in: "query"
      description: "Comma-separated list of source databases (RefSeq, Ensembl, GenBank, CommunityRegistry)"
      schema:
        type: "string"
    feature_sources:
      name: "feature_sources"
      in: "query"
      description: "Comma-separated list of GFF feature sources (column 2)"
      schema:
        type: "string"
    biotypes:
      name: "biotypes"
      in: "query"
      description: "Comma-separated list of feature biotypes"
      schema:
        type: "string"
    feature_types:
      name: "feature_types"
      in: "query"
      description: "Comma-separated list of GFF feature types (column 3)"
      schema:
        type: "string"
    pipelines:
      name: "pipelines"
      in: "query"
      description: "Comma-separated list of annotation pipeline names"
      schema:
        type: "string"
    providers:
      name: "providers"
      in: "query"
      description: "Comma-separated list of annotation providers"
      schema:
        type: "string"
    md5_checksums:
      name: "md5_checksums"
      in: "query"
      description: "Comma-separated list of annotation MD5 checksums"
      schema:
        type: "string"
    has_stats:
      name: "has_stats"
      in: "query"
      description: "Filter annotations that have computed statistics"
      schema:
        type: "boolean"
    latest_release_by:
      name: "latest_release_by"
      in: "query"
      description: "Return only the latest release per group"
      schema:
        type: "string"
        enum: ["organism", "assembly"]
    refseq_categories:
      name: "refseq_categories"
      in: "query"
      description: "Comma-separated list of RefSeq categories"
      schema:
        type: "string"
    assembly_levels:
      name: "assembly_levels"
      in: "query"
      description: "Comma-separated list of assembly levels"
      schema:
        type: "string"
    assembly_statuses:
      name: "assembly_statuses"
      in: "query"
      description: "Comma-separated list of assembly statuses"
      schema:
        type: "string"
    assembly_types:
      name: "assembly_types"
      in: "query"
      description: "Comma-separated list of assembly types"
      schema:
        type: "string"
    submitters:
      name: "submitters"
      in: "query"
      description: "Comma-separated list of assembly submitter names"
      schema:
        type: "string"
    release_date_from:
      name: "release_date_from"
      in: "query"
      description: "Filter annotations released on or after this ISO date"
      schema:
        type: "string"
        format: "date"
    release_date_to:
      name: "release_date_to"
      in: "query"
      description: "Filter annotations released on or before this ISO date"
      schema:
        type: "string"
        format: "date"
    sort_by:
      name: "sort_by"
      in: "query"
      description: "Field to sort results by"
      schema:
        type: "string"
    sort_order:
      name: "sort_order"
      in: "query"
      description: "Sort order"
      schema:
        type: "string"
        enum: ["asc", "desc"]
    fields:
      name: "fields"
      in: "query"
      description: "Comma-separated list of dot-notation fields to include in the response"
      schema:
        type: "string"
    selected_fields:
      name: "selected_fields"
      in: "query"
      description: "Comma-separated list of extended TSV column keys to append after the default export columns. Only applies to /annotations/report. Omit to keep the production default column set. Assembly-derived columns (assembly_refseq_category, assembly_download_url, assembly_gc_percent) are resolved via a join on assembly_accession; assembly_download_url is left empty when the URL is still a localhost placeholder."
      schema:
        type: "string"
        example: "release_date,taxon_lineage,busco_complete,assembly_gc_percent"
    rank:
      name: "rank"
      in: "query"
      description: "Filter taxonomy nodes by rank"
      schema:
        type: "string"

  responses:
    BadRequest:
      description: "Bad request"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: "Resource not found"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Forbidden:
      description: "Forbidden"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: "Internal server error"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  schemas:
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail

    AnnotationQueryParams:
      type: object
      properties:
        filter:
          type: string
        taxids:
          type: string
        bioproject_accessions:
          type: string
        assembly_accessions:
          type: string
        db_sources:
          type: string
        feature_sources:
          type: string
        biotypes:
          type: string
        feature_types:
          type: string
        pipelines:
          type: string
        providers:
          type: string
        md5_checksums:
          type: string
        has_stats:
          type: boolean
        latest_release_by:
          type: string
          enum: ["organism", "assembly"]
        refseq_categories:
          type: string
        assembly_levels:
          type: string
        assembly_statuses:
          type: string
        assembly_types:
          type: string
        release_date_from:
          type: string
          format: date
        release_date_to:
          type: string
          format: date
        sort_by:
          type: string
        sort_order:
          type: string
          enum: ["asc", "desc"]
        offset:
          type: integer
          default: 0
        limit:
          type: integer
          default: 20
        fields:
          type: string
        selected_fields:
          type: string
          description: "Comma-separated extended TSV column keys to append after default columns (report export only). Includes annotation extended fields and assembly-derived columns (assembly_refseq_category, assembly_download_url, assembly_gc_percent)."

    AssemblyQueryParams:
      type: object
      properties:
        filter:
          type: string
        taxids:
          type: string
        bioproject_accessions:
          type: string
        assembly_accessions:
          type: string
        refseq_categories:
          type: string
        assembly_levels:
          type: string
        assembly_statuses:
          type: string
        assembly_types:
          type: string
        submitters:
          type: string
        sort_by:
          type: string
        sort_order:
          type: string
          enum: ["asc", "desc"]
        offset:
          type: integer
          default: 0
        limit:
          type: integer
          default: 20

    OrganismQueryParams:
      type: object
      properties:
        filter:
          type: string
        taxids:
          type: string
        bioproject_accessions:
          type: string
        sort_by:
          type: string
        sort_order:
          type: string
          enum: ["asc", "desc"]
        offset:
          type: integer
          default: 0
        limit:
          type: integer
          default: 20

    TaxonQueryParams:
      type: object
      properties:
        filter:
          type: string
        taxids:
          type: string
        rank:
          type: string
        sort_by:
          type: string
        sort_order:
          type: string
          enum: ["asc", "desc"]
        offset:
          type: integer
          default: 0
        limit:
          type: integer
          default: 20

    BioprojectQueryParams:
      type: object
      properties:
        filter:
          type: string
        sort_by:
          type: string
        sort_order:
          type: string
          enum: ["asc", "desc"]
        offset:
          type: integer
          default: 0
        limit:
          type: integer
          default: 20

    Annotation:
      type: object
      properties:
        annotation_id:
          type: string
          description: "MD5 checksum of the annotation"
        assembly_accession:
          type: string
        assembly_name:
          type: string
        organism_name:
          type: string
        taxid:
          type: string
        taxon_lineage:
          type: array
          items:
            type: string
        mapped_regions:
          type: array
          deprecated: true
          description: Deprecated; use GET /annotations/{md5}/contigs/aliases (AnnotationSequenceMap).
          items:
            type: string
        source_file_info:
          $ref: "#/components/schemas/SourceFileInfo"
        indexed_file_info:
          $ref: "#/components/schemas/IndexedFileInfo"
        features_summary:
          $ref: "#/components/schemas/FeatureSummary"
        features_statistics:
          $ref: "#/components/schemas/GFFStats"
      required:
        - annotation_id
        - assembly_accession
        - assembly_name
        - organism_name
        - taxid

    SourceFileInfo:
      type: object
      properties:
        database:
          type: string
        provider:
          type: string
        release_date:
          type: string
          format: date-time
        url_path:
          type: string
          format: uri
        last_modified:
          type: string
          format: date-time
        uncompressed_md5:
          type: string
        pipeline:
          $ref: "#/components/schemas/PipelineInfo"
      required:
        - database
        - release_date
        - url_path
        - last_modified
        - uncompressed_md5

    PipelineInfo:
      type: object
      properties:
        name:
          type: string
        version:
          type: string
        method:
          type: string

    IndexedFileInfo:
      type: object
      properties:
        bgzipped_path:
          type: string
        csi_path:
          type: string
        uncompressed_md5:
          type: string
        file_size:
          type: integer
        processed_at:
          type: string
          format: date-time
        pipeline:
          $ref: "#/components/schemas/PipelineInfo"
      required:
        - bgzipped_path
        - csi_path
        - uncompressed_md5
        - file_size

    FeatureSummary:
      type: object
      properties:
        attribute_keys:
          type: array
          items:
            type: string
        types:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: string
        biotypes:
          type: array
          items:
            type: string
        types_missing_id:
          type: array
          items:
            type: string
        root_type_counts:
          type: object
          additionalProperties:
            type: integer
        has_biotype:
          type: boolean
        has_cds:
          type: boolean
        has_exon:
          type: boolean

    GFFStats:
      type: object
      properties:
        gene_category_stats:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/GeneCategoryFeatureStats"
        transcript_type_stats:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/GenericTranscriptTypeStats"

    GeneStats:
      type: object
      properties:
        count:
          type: integer
        length_stats:
          $ref: "#/components/schemas/GeneLengthStats"
        transcripts:
          $ref: "#/components/schemas/TranscriptStats"
        features:
          $ref: "#/components/schemas/FeatureStats"

    GeneLengthStats:
      type: object
      properties:
        min:
          type: integer
        max:
          type: integer
        mean:
          type: number
        median:
          type: number

    TranscriptStats:
      type: object
      properties:
        count:
          type: integer
        per_gene:
          type: number
        types:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TranscriptTypeStats"

    TranscriptTypeStats:
      type: object
      properties:
        count:
          type: integer
        per_gene:
          type: number
        exons_per_transcript:
          type: number
        length_stats:
          $ref: "#/components/schemas/LengthStats"
        spliced_length_stats:
          $ref: "#/components/schemas/LengthStats"
        exon_length_stats:
          $ref: "#/components/schemas/LengthStats"

    FeatureStats:
      type: object
      properties:
        exons:
          $ref: "#/components/schemas/FeatureTypeStats"
        cds:
          $ref: "#/components/schemas/FeatureTypeStats"
        introns:
          $ref: "#/components/schemas/FeatureTypeStats"

    FeatureTypeStats:
      type: object
      properties:
        count:
          type: integer
        length_stats:
          $ref: "#/components/schemas/LengthStats"

    LengthStats:
      type: object
      properties:
        mean:
          type: number
        median:
          type: number

    GenericLengthStats:
      type: object
      properties:
        min:
          type: integer
        max:
          type: integer
        mean:
          type: number

    GeneCategoryFeatureStats:
      type: object
      properties:
        total_count:
          type: integer
        length_stats:
          $ref: "#/components/schemas/GenericLengthStats"
        biotype_counts:
          type: object
          additionalProperties:
            type: integer
        transcript_type_counts:
          type: object
          additionalProperties:
            type: integer

    AssociatedGenesStats:
      type: object
      properties:
        total_count:
          type: integer
        gene_categories:
          type: object
          additionalProperties:
            type: integer

    SubFeatureStats:
      type: object
      properties:
        total_count:
          type: integer
        length:
          $ref: "#/components/schemas/GenericLengthStats"
        concatenated_length:
          $ref: "#/components/schemas/GenericLengthStats"

    GenericTranscriptTypeStats:
      type: object
      properties:
        length_stats:
          $ref: "#/components/schemas/GenericLengthStats"
        total_count:
          type: integer
        biotype_counts:
          type: object
          additionalProperties:
            type: integer
        associated_genes:
          $ref: "#/components/schemas/AssociatedGenesStats"
        exon_stats:
          $ref: "#/components/schemas/SubFeatureStats"
        cds_stats:
          $ref: "#/components/schemas/SubFeatureStats"

    AnnotationsSummaryStats:
      type: object
      properties:
        annotations:
          type: object
          properties:
            total_count:
              type: integer
            related_organisms_count:
              type: integer
            related_assemblies_count:
              type: integer
        genes:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/GeneAggregateStats"
        transcripts:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TranscriptAggregateStats"
        features:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/FeatureAggregateStats"

    GeneAggregateStats:
      type: object
      properties:
        total_count:
          type: integer
        mean_count:
          type: number
        median_count:
          type: number
        mean_length:
          type: number
        median_length:
          type: number

    TranscriptAggregateStats:
      type: object
      properties:
        total_count:
          type: integer
        mean_count:
          type: number
        median_count:
          type: number
        mean_length:
          type: number
        median_length:
          type: number

    FeatureAggregateStats:
      type: object
      properties:
        mean_length:
          type: number
        median_length:
          type: number

    AnnotationError:
      type: object
      properties:
        assembly_accession:
          type: string
        taxid:
          type: string
        organism_name:
          type: string
        error_message:
          type: string
        url_path:
          type: string
          format: uri
        source_md5:
          type: string
        source_database:
          type: string
        release_date:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - assembly_accession
        - taxid
        - organism_name
        - error_message
        - url_path
        - source_md5
        - source_database

    Assembly:
      type: object
      properties:
        assembly_accession:
          type: string
        paired_assembly_accession:
          type: string
        assembly_name:
          type: string
        source_database:
          type: string
        assembly_level:
          type: string
        assembly_status:
          type: string
        assembly_type:
          type: string
        refseq_category:
          type: string
        taxid:
          type: string
        organism_name:
          type: string
        taxon_lineage:
          type: array
          items:
            type: string
        release_date:
          type: string
          format: date-time
        submitter:
          type: string
        annotations_count:
          type: integer
        download_url:
          type: string
          format: uri
        assembly_stats:
          $ref: "#/components/schemas/AssemblyStats"
      required:
        - assembly_accession
        - assembly_name
        - organism_name
        - taxid
        - download_url

    AssemblyStats:
      type: object
      properties:
        total_number_of_chromosomes:
          type: integer
        total_sequence_length:
          type: string
        total_ungapped_length:
          type: string
        number_of_contigs:
          type: integer
        contig_n50:
          type: integer
        contig_l50:
          type: integer
        number_of_scaffolds:
          type: integer
        scaffold_n50:
          type: integer
        scaffold_l50:
          type: integer
        gaps_between_scaffolds_count:
          type: integer
        number_of_component_sequences:
          type: integer
        atgc_count:
          type: string
        gc_count:
          type: string
        gc_percent:
          type: integer
        genome_coverage:
          type: string
        number_of_organelles:
          type: integer

    ChromosomeReportEntry:
      type: object
      description: "One molecule row from chromosomes.json (NCBI assembly report)."
      properties:
        canonical_id:
          type: string
        chr_name:
          type: string
          description: "NCBI assembly report Assigned-Molecule (e.g. 1, 2, MT)"
        sequence_name:
          type: string
        ucsc_style_name:
          type: string
        genbank_accession:
          type: string
        refseq_accession:
          type: string
        sequence_role:
          type: string
          description: "NCBI assembly report Sequence-Role (e.g. assembled-molecule)"
        length:
          type: integer

    GenomicSequence:
      type: object
      properties:
        assembly_accession:
          type: string
        assembly_name:
          type: string
        chr_name:
          type: string
          description: NCBI assembly report Assigned-Molecule (e.g. 1, 2, MT)
        sequence_role:
          type: string
          description: NCBI assembly report Sequence-Role (e.g. assembled-molecule, alt-scaffold)
        sequence_name:
          type: string
        ucsc_style_name:
          type: string
        genbank_accession:
          type: string
        refseq_accession:
          type: string
        length:
          type: integer
        aliases:
          type: array
          items:
            type: string
      required:
        - assembly_accession
        - assembly_name
        - sequence_name
        - aliases

    Organism:
      type: object
      properties:
        taxid:
          type: string
        organism_name:
          type: string
        common_name:
          type: string
        taxon_lineage:
          type: array
          items:
            type: string
        annotations_count:
          type: integer
        assemblies_count:
          type: integer
      required:
        - taxid
        - organism_name

    TaxonNode:
      type: object
      properties:
        taxid:
          type: string
        scientific_name:
          type: string
        rank:
          type: string
        children:
          type: array
          items:
            type: string
        assemblies_count:
          type: integer
        annotations_count:
          type: integer
        organisms_count:
          type: integer
      required:
        - taxid
        - scientific_name

    SequenceAlias:
      type: object
      properties:
        sequence_id:
          type: string
        annotation_id:
          type: string
        aliases:
          type: array
          items:
            type: string
      required:
        - sequence_id
        - annotation_id
        - aliases

    FrequencyFieldList:
      type: object
      properties:
        fields:
          type: array
          items:
            type: string

    FrequencyCounts:
      type: object
      additionalProperties:
        type: integer

    RankFrequencies:
      type: object
      additionalProperties:
        type: integer

    PaginatedAnnotationsResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/Annotation"

    PaginatedAssembliesResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/Assembly"

    PaginatedOrganismsResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/Organism"

    PaginatedTaxonsResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/TaxonNode"

    PaginatedAnnotationErrorsResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/AnnotationError"

    PaginatedSequenceAliasesResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/SequenceAlias"

    PaginatedGenomicSequencesResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/GenomicSequence"

    TaxonAncestorsResponse:
      type: object
      properties:
        total:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/TaxonNode"

    BioProject:
      type: object
      properties:
        accession:
          type: string
        title:
          type: string
        assemblies_count:
          type: integer
        species_count:
          type: integer
        annotations_count:
          type: integer
      required:
        - accession
        - title

    PaginatedBioprojectsResponse:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/BioProject"

    GeneStatsSummaryResponse:
      type: object
      properties:
        total_annotations:
          type: integer
          description: "Total number of annotations in queryset"
        summary:
          type: object
          properties:
            genes:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/GeneCategorySummary"
        categories:
          type: array
          items:
            type: string
          description: "List of available gene categories (coding, non_coding, pseudogene)"
        metrics:
          type: array
          items:
            type: string
          description: "List of available metrics (total_count, average_mean_length)"
      required:
        - total_annotations
        - summary
        - categories
        - metrics

    GeneCategorySummary:
      type: object
      properties:
        annotations_count:
          type: integer
          description: "Number of annotations with this category"
        missing_annotations_count:
          type: integer
          description: "Number of annotations missing this category"
        average_count:
          type: number
          nullable: true
          description: "Average number of genes of this category per annotation"
        average_mean_length:
          type: number
          nullable: true
          description: "Average mean length of genes in this category"
      required:
        - annotations_count
        - missing_annotations_count

    GeneCategoryDetailsResponse:
      type: object
      properties:
        category:
          type: string
          description: "The gene category name"
        annotations_count:
          type: integer
          description: "Number of annotations with this category"
        missing_annotations_count:
          type: integer
          description: "Number of annotations missing this category"
        summary:
          type: object
          description: "Aggregated statistics (mean) for all metrics"
          additionalProperties:
            type: object
            properties:
              mean:
                type: number
        metrics:
          type: array
          items:
            type: string
          description: "List of metrics available for this category"
      required:
        - category
        - annotations_count
        - missing_annotations_count
        - summary
        - metrics

    GeneCategoryMetricValuesResponse:
      type: object
      properties:
        category:
          type: string
          description: "The gene category name"
        metric:
          type: string
          description: "The metric name"
        values:
          type: array
          items:
            type: number
          description: "List of values (ordered by annotation_id)"
        annotation_ids:
          type: array
          items:
            type: string
          description: "List of annotation_ids (only if include_annotations=true, ordered to match values)"
        missing:
          type: array
          items:
            type: string
          description: "List of annotation_ids missing this metric"
      required:
        - category
        - metric
        - values
        - missing

    TranscriptStatsSummaryResponse:
      type: object
      properties:
        total_annotations:
          type: integer
          description: "Total number of annotations in queryset"
        summary:
          type: object
          properties:
            types:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/TranscriptTypeSummary"
        types:
          type: array
          items:
            type: string
          description: "List of available transcript types"
        metrics:
          type: array
          items:
            type: string
          description: "List of available metrics (varies by transcript type)"
      required:
        - total_annotations
        - summary
        - types
        - metrics

    TranscriptTypeSummary:
      type: object
      properties:
        annotations_count:
          type: integer
          description: "Number of annotations with this transcript type"
        missing_annotations_count:
          type: integer
          description: "Number of annotations missing this transcript type"
        average_count:
          type: number
          nullable: true
          description: "Average number of transcripts of this type per annotation"
        average_mean_length:
          type: number
          nullable: true
          description: "Average mean length of transcripts in this type"
      required:
        - annotations_count
        - missing_annotations_count

    TranscriptTypeDetailsResponse:
      type: object
      properties:
        type:
          type: string
          description: "The transcript type name"
        annotations_count:
          type: integer
          description: "Number of annotations with this type"
        missing_annotations_count:
          type: integer
          description: "Number of annotations missing this type"
        summary:
          type: object
          description: "Aggregated statistics (mean) for all metrics"
          additionalProperties:
            type: object
            properties:
              mean:
                type: number
        metrics:
          type: array
          items:
            type: string
          description: "List of metrics available for this type"
      required:
        - type
        - annotations_count
        - missing_annotations_count
        - summary
        - metrics

    TranscriptTypeMetricValuesResponse:
      type: object
      properties:
        type:
          type: string
          description: "The transcript type name"
        metric:
          type: string
          description: "The metric name"
        values:
          type: array
          items:
            type: number
          description: "List of values (ordered by annotation_id)"
        annotation_ids:
          type: array
          items:
            type: string
          description: "List of annotation_ids (only if include_annotations=true, ordered to match values)"
        missing:
          type: array
          items:
            type: string
          description: "List of annotation_ids missing this metric"
      required:
        - type
        - metric
        - values
        - missing

    AnnotationsAggregatesByTaxonResponse:
      type: object
      description: "Annotation aggregates grouped by taxon at a given rank. fields lists the fixed column order used by rows."
      properties:
        fields:
          type: array
          items:
            type: string
          description: "Fixed column names: taxid, taxon_name, annotations_count, avg_coding_genes_count, avg_non_coding_genes_count, avg_pseudogenes_count"
        rows:
          type: array
          items:
            type: array
            items: {}
          description: "One row per taxon, values aligned with fields"
      required:
        - fields
        - rows

    BuscoStatsSummaryResponse:
      type: object
      properties:
        total_annotations:
          type: integer
          description: "Total number of annotations in queryset"
        summary:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/BuscoMetricSummary"
          description: "Per-metric stats keyed by complete, single_copy, duplicated, fragmented, missing"
        metrics:
          type: array
          items:
            type: string
          description: "List of available BUSCO metrics"
      required:
        - total_annotations
        - summary
        - metrics

    BuscoMetricSummary:
      type: object
      properties:
        annotations_count:
          type: integer
          description: "Number of annotations with BUSCO data"
        missing_annotations_count:
          type: integer
          description: "Number of annotations missing BUSCO data"
        mean:
          type: number
          nullable: true
          description: "Mean value for this metric"
      required:
        - annotations_count
        - missing_annotations_count

    BuscoMetricValuesResponse:
      type: object
      properties:
        metric:
          type: string
          description: "The BUSCO metric name"
        values:
          type: array
          items:
            type: number
          description: "List of values (ordered by annotation_id)"
        annotation_ids:
          type: array
          items:
            type: string
          description: "List of annotation_ids (only if include_annotations=true, ordered to match values)"
      required:
        - metric
        - values

    UploadGffResponse:
      type: object
      properties:
        task_id:
          type: string
          description: "Celery task ID for the upload job"
        remaining_quota:
          type: integer
          description: "Remaining uploads allowed for this client in the current 24h window"
      required:
        - task_id
        - remaining_quota

    UploadJobStatusResponse:
      type: object
      properties:
        task_id:
          type: string
        state:
          type: string
          description: "Celery task state (PENDING, PROGRESS, SUCCESS, FAILURE, etc.)"
        meta:
          type: object
          additionalProperties: true
          description: "Progress metadata when state is PROGRESS"
        result:
          description: "Job result when state is SUCCESS"
        error:
          type: string
          description: "Error message when state is FAILURE"
      required:
        - task_id
        - state

    UploadRateLimitResponse:
      type: object
      properties:
        used:
          type: integer
          description: "Uploads used in the last 24 hours"
        remaining:
          type: integer
          description: "Remaining uploads in the current 24h window"
      required:
        - used
        - remaining

    FlattenedTreeResponse:
      type: object
      description: "Flattened taxonomy tree as fields + rows. Column order is fixed."
      properties:
        fields:
          type: array
          items:
            type: string
          description: "Fixed column names: taxid, parent_taxid, scientific_name, annotations_count, assemblies_count, organisms_count, rank, coding_mean_count, non_coding_mean_count, pseudogene_mean_count, mRNA_mean_count, lncRNA_mean_count, tRNA_mean_count, miRNA_mean_count, busco_single_copy_mean, busco_duplicated_mean, busco_fragmented_mean, busco_missing_mean"
        rows:
          type: array
          items:
            type: array
            items: {}
          description: "One row per taxon, values aligned with fields"
      required:
        - fields
        - rows

    TopVisitor:
      type: object
      properties:
        country:
          type: string
        visits_count:
          type: integer
      required:
        - country
        - visits_count

    TopVisitorsResponse:
      type: array
      items:
        $ref: "#/components/schemas/TopVisitor"

    UsageSummaryResponse:
      type: object
      properties:
        unique_users:
          type: integer
        active_30d:
          type: integer
        countries:
          type: integer
        returning_pct:
          type: number
        as_of:
          type: string
          format: date-time
      required:
        - unique_users
        - active_30d
        - countries
        - returning_pct
        - as_of

    TopCountry:
      type: object
      properties:
        country:
          type: string
        unique_users:
          type: integer
      required:
        - country
        - unique_users

    TopCountriesResponse:
      type: array
      items:
        $ref: "#/components/schemas/TopCountry"

    UsageCapabilityItem:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        unique_users:
          type: integer
        request_count:
          type: integer
      required:
        - id
        - label
        - unique_users

    UsageCapabilitiesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/UsageCapabilityItem"
        as_of:
          type: string
          format: date-time
          nullable: true
      required:
        - items

    TopEntityRow:
      type: object
      properties:
        id:
          type: string
        unique_users:
          type: integer
        label:
          type: string
          nullable: true
        organism_name:
          type: string
          nullable: true
        assembly_accession:
          type: string
          nullable: true
        provider:
          type: string
          nullable: true
        database:
          type: string
          nullable: true
        rank:
          type: string
          nullable: true
      required:
        - id
        - unique_users

    TopEntitiesResponse:
      type: object
      properties:
        top_assemblies:
          type: array
          items:
            $ref: "#/components/schemas/TopEntityRow"
        top_annotations:
          type: array
          items:
            $ref: "#/components/schemas/TopEntityRow"
        top_taxons:
          type: array
          items:
            $ref: "#/components/schemas/TopEntityRow"
        as_of:
          type: string
          format: date-time
          nullable: true
      required:
        - top_assemblies
        - top_annotations
        - top_taxons