openapi: 3.0.1 info: title: NCBI Datasets BioSample Virus API version: v2 description: '### NCBI Datasets is a resource that lets you easily gather data from NCBI. The NCBI Datasets version 2 API is updated often to add new features, fix bugs, and enhance usability. ' servers: - url: https://api.ncbi.nlm.nih.gov/datasets/v2 security: - ApiKeyAuthHeader: [] tags: - name: Virus description: '#### Options to download virus genome data, including the associated sequence and metadata. These virus services allow you to get virus genome metadata as a data report or download genome and protein sequence, and metadata, as a virus data package, for virus GenBank genomes. ' paths: /virus/taxon/{taxon}/genome: get: summary: Get a download summary of a virus genome data package by taxon description: Get a download summary of a virus genome data package, including counts and file sizes, in JSON format. tags: - Virus operationId: virus_genome_summary responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2DownloadSummary' parameters: - name: accessions description: One or more nucleotide sequence accessions in: query required: false schema: type: array items: type: string examples: example-0: value: NC_038294.1 summary: Betacoronavirus England 1 isolate H123990006, complete genome - name: taxon description: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank in: path required: true schema: type: string examples: example-0: value: '1335626' summary: NCBI Taxonomy ID for MERS, Middle East respiratory syndrome-related coronavirus example-1: value: '2697049' summary: NCBI Taxonomy ID for SARS-CoV-2 example-2: value: '197911' summary: NCBI Taxonomy ID for the genus Alphainfluenzavirus - name: refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Inclue all genomes - name: released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: geo_location description: Limit to genomes collected from the specified geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: include_sequence description: Specify which sequence files to include in the data package. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' examples: example-0: value: - GENOME - CDS - PROTEIN summary: Include genomic, CDS, and protein sequence files - name: aux_report description: Specify which report files to include in the data package. The virus data report is always included, and its inclusion is not affected by this parameter. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' examples: example-0: value: BIOSAMPLE summary: Include the BioSample report /virus/genome: post: summary: Get a download summary of a virus genome data package description: Get a download summary of a virus genome data package, including counts and file sizes, in JSON format. tags: - Virus operationId: virus_genome_summary_by_post responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2DownloadSummary' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v2VirusDatasetRequest' examples: Single Virus accession example: description: Betacoronavirus England 1 isolate H123990006, complete genome value: accessions: - NC_038294.1 /virus/taxon/sars2/protein/{proteins}: get: summary: Get a download summary of a SARS-CoV-2 protein data package by protein name description: Get a download summary of a SARS-CoV-2 protein data package, including counts and file sizes, in JSON format. tags: - Virus operationId: sars2_protein_summary responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2DownloadSummary' parameters: - name: proteins description: One or more SARS-CoV-2 protein names in: path required: true schema: type: array items: type: string examples: example-0: value: spike protein summary: SARS-CoV-2 spike protein example-1: value: - spike protein - envelope protein - RdRp summary: SARS-CoV-2 spike, envelope, and RNA-dependent RNA polymerase proteins - name: refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Both GenBank & RefSeq genomes - name: annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: All genomes - name: released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: pangolin_classification description: Limit to SARS-CoV-2 genomes with the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: geo_location description: Limit to genomes collected from the specififed geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: include_sequence description: Specify which sequence files to include in the data package. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' examples: example-0: value: - CDS - PROTEIN summary: Include CDS and proetin sequence files - name: aux_report description: Specify which report files to include in the data package. The virus data report is always included, and its inclusion is not affected by this parameter. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' examples: example-0: value: ANNOTATION summary: Include the annotation report /virus/taxon/sars2/protein: post: summary: Get a download summary of a SARS-CoV-2 protein data package by protein name description: Get a download summary of a SARS-CoV-2 protein data package, including counts and file sizes, in JSON format. tags: - Virus operationId: sars2_protein_summary_by_post responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2DownloadSummary' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v2Sars2ProteinDatasetRequest' examples: SARS-CoV-2 virus RefSeq protein example: description: SARS-CoV-2 spike surface glycoprotein (RefSeq) value: proteins: - spike refseq_only: true include_sequence: - PROTEIN /virus/taxon/{taxon}/genome/table: get: deprecated: true summary: Get virus genome metadata in a tabular format description: Get virus genome metadata in tabular format for virus genomes by taxon. tags: - Virus operationId: virus_genome_table responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2TabularOutput' parameters: - name: accessions description: One or more nucleotide sequence accessions in: query required: false schema: type: array items: type: string examples: example-0: value: NC_038294.1 summary: Betacoronavirus England 1 isolate H123990006, complete genome - name: taxon description: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank in: path required: true schema: type: string examples: example-0: value: '1335626' summary: NCBI Taxonomy ID for MERS, Middle East respiratory syndrome-related coronavirus example-1: value: '2697049' summary: NCBI Taxonomy ID for SARS-CoV-2 example-2: value: '197911' summary: NCBI Taxonomy ID for the genus Alphainfluenzavirus - name: refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Inclue all genomes - name: released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: geo_location description: Limit to genomes collected from the specified geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: table_fields description: Specify which fields to include in the tabular report in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusTableField' examples: example-0: value: - protein_accession - protein_name summary: SARS-CoV-2 protein accession and name - name: include_sequence description: Specify which sequence files to include in the data package. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' examples: example-0: value: - GENOME - CDS - PROTEIN summary: Include genomic, CDS, and protein sequence files - name: aux_report description: Specify which report files to include in the data package. The virus data report is always included, and its inclusion is not affected by this parameter. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' examples: example-0: value: BIOSAMPLE summary: Include the BioSample report - name: format description: Choose download format (tsv, csv or jsonl) in: query required: false schema: $ref: '#/components/schemas/v2TableFormat' default: tsv examples: example-0: value: tsv summary: TSV example-1: value: csv summary: CSV example-2: value: jsonl summary: JSON Lines /virus/taxon/sars2/protein/{proteins}/table: get: summary: Get SARS-CoV-2 protein metadata in a tabular format by protein name description: Get SARS-CoV-2 protein metadata in a tabular format by protein name. tags: - Virus operationId: sars2_protein_table responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2TabularOutput' parameters: - name: proteins description: One or more SARS-CoV-2 protein names in: path required: true schema: type: array items: type: string examples: example-0: value: spike protein summary: SARS-CoV-2 spike protein example-1: value: - spike protein - envelope protein - RdRp summary: SARS-CoV-2 spike, envelope, and RNA-dependent RNA polymerase proteins - name: refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Both GenBank & RefSeq genomes - name: annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: All genomes - name: released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: pangolin_classification description: Limit to SARS-CoV-2 genomes with the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: geo_location description: Limit to genomes collected from the specififed geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: table_fields description: Specify which fields to include in the tabular report in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusTableField' examples: example-0: value: - protein_accession - protein_name summary: Protein accession and name - name: format description: Specify output format in: query required: false schema: $ref: '#/components/schemas/v2TableFormat' default: tsv examples: example-0: value: tsv summary: TSV, tabular format example-1: value: jsonl summary: JSON Lines format /virus/taxon/{taxon}/dataset_report: get: summary: Get a virus data report by taxon description: 'Get a virus data report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept: application/x-ndjson) formats.' tags: - Virus operationId: virus_reports_by_taxon responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2reportsVirusDataReportPage' application/x-ndjson: schema: $ref: '#/components/schemas/v2reportsVirusDataReportPage' text/tab-separated-values: schema: type: string parameters: - name: taxon description: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank in: path required: true schema: type: string examples: example-0: value: '1335626' summary: NCBI Taxonomy ID for MERS, Middle East respiratory syndrome-related coronavirus example-1: value: '2697049' summary: NCBI Taxonomy ID for SARS-CoV-2 example-2: value: '197911' summary: NCBI Taxonomy ID for the genus Alphainfluenzavirus - name: filter.refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: filter.annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Include all genomes - name: filter.released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: filter.pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: filter.geo_location description: Limit to genomes collected from the specified geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: filter.usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: filter.complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: returned_content description: Return complete virus reports or nucleotide accessions only in: query required: false schema: $ref: '#/components/schemas/v2VirusDataReportRequestContentType' - name: table_fields description: Specify which fields to include in the tabular report in: query required: false schema: type: array items: type: string examples: example-0: value: - accession - is-complete - is-annotated summary: Virus Data Report Fields - name: page_size description: The maximum number of virus data reports to return. Default is 20 and maximum is 1000. If the number of results exceeds the page size, `page_token` can be used to retrieve the remaining results. in: query required: false schema: type: integer default: 20 - name: page_token description: A page token is returned when the results count exceeds `page size`. Use this token along with previous request parameters to retrieve the next page of results. When `page_token` is empty, all results have been retrieved. in: query required: false schema: type: string /virus/accession/{accessions}/dataset_report: get: summary: Get a virus data report by nucleotide accession description: 'Get a virus data report by nucleotide accession. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept: application/x-ndjson) formats.' tags: - Virus operationId: virus_reports_by_acessions responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2reportsVirusDataReportPage' application/x-ndjson: schema: $ref: '#/components/schemas/v2reportsVirusDataReportPage' text/tab-separated-values: schema: type: string parameters: - name: accessions description: One or more nucleotide sequence accessions in: path required: true schema: type: array items: type: string examples: example-0: value: NC_038294.1 summary: Betacoronavirus England 1 isolate H123990006, complete genome - name: filter.refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: filter.annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Include all genomes - name: filter.released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: filter.pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: filter.geo_location description: Limit to genomes collected from the specified geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: filter.usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: filter.complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: returned_content description: Return complete virus reports or nucleotide accessions only in: query required: false schema: $ref: '#/components/schemas/v2VirusDataReportRequestContentType' - name: table_fields description: Specify which fields to include in the tabular report in: query required: false schema: type: array items: type: string examples: example-0: value: - accession - is-complete - is-annotated summary: Virus Data Report Fields - name: page_size description: The maximum number of virus data reports to return. Default is 20 and maximum is 1000. If the number of results exceeds the page size, `page_token` can be used to retrieve the remaining results. in: query required: false schema: type: integer default: 20 - name: page_token description: A page token is returned when the results count exceeds `page size`. Use this token along with previous request parameters to retrieve the next page of results. When `page_token` is empty, all results have been retrieved. in: query required: false schema: type: string /virus: post: summary: Get a virus data report description: 'Get a virus data report. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept: application/x-ndjson) formats.' tags: - Virus operationId: virus_reports_by_post responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2reportsVirusDataReportPage' application/x-ndjson: schema: $ref: '#/components/schemas/v2reportsVirusDataReportPage' text/tab-separated-values: schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v2VirusDataReportRequest' examples: RefSeq Virus TaxID example: description: Middle East repiratory syndrome-related coronavirus, RefSeq genomes value: filter: taxons: - '1335626' refseq_only: true /virus/taxon/{taxon}/annotation_report: get: summary: Get a virus annotation report by taxon description: 'Get virus annotation report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept: application/x-ndjson) formats.' tags: - Virus operationId: virus_annotation_reports_by_taxon responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2reportsVirusAnnotationReportPage' application/x-ndjson: schema: $ref: '#/components/schemas/v2reportsVirusAnnotationReportPage' text/tab-separated-values: schema: type: string parameters: - name: taxon description: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank in: path required: true schema: type: string examples: example-0: value: '1335626' summary: MERS example-1: value: '2697049' summary: SARS-COV-2 example-2: value: '11118' summary: Coronaviridae - name: filter.refseq_only description: If true, limit to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: filter.annotated_only description: If true, limit to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Include all genomes - name: filter.released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: filter.pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: filter.geo_location description: Limit to genomes collected from the specififed geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: filter.usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: filter.complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: table_fields description: 'Specify which fields to include in the tabular report. Additional fields are described here: [virus annotation report fields](https://www.ncbi.nlm.nih.gov/datasets/docs/v2/command-line-tools/using-dataformat/virus-data-reports/#virus-annotation-report-fields). Use of this parameter requires the HTTP header, `accept: text/tab-separated-values`.' in: query required: false schema: type: array items: type: string examples: example-0: value: - accession - gene-cds-name - gene-cds-nuc-fasta-range-start - gene-cds-nuc-fasta-range-stop summary: Virus genome nucleotide accession, gene CDS name, and annotated location - name: page_size description: The maximum number of virus data reports to return. Default is 20 and maximum is 1000. If the number of results exceeds the page size, `page_token` can be used to retrieve the remaining results. in: query required: false schema: type: integer default: 20 - name: page_token description: A page token is returned when the results count exceeds `page size`. Use this token along with previous request parameters to retrieve the next page of results. When `page_token` is empty, all results have been retrieved. in: query required: false schema: type: string /virus/accession/{accessions}/annotation_report: get: summary: Get a virus annotation report by nucleotide accession description: 'Get a virus annotation report by nucleotide accesion. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept: application/x-ndjson) formats.' tags: - Virus operationId: virus_annotation_reports_by_acessions responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2reportsVirusAnnotationReportPage' application/x-ndjson: schema: $ref: '#/components/schemas/v2reportsVirusAnnotationReportPage' text/tab-separated-values: schema: type: string parameters: - name: accessions description: One or more nucleotide sequence accessions in: path required: true schema: type: array items: type: string examples: example-0: value: NC_038294.1 summary: Betacoronavirus England 1 isolate H123990006, complete genome - name: filter.refseq_only description: If true, limit to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: filter.annotated_only description: If true, limit to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Include all genomes - name: filter.released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: filter.host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: filter.pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: filter.geo_location description: Limit to genomes collected from the specififed geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: filter.usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: filter.complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: table_fields description: 'Specify which fields to include in the tabular report. Additional fields are described here: [virus annotation report fields](https://www.ncbi.nlm.nih.gov/datasets/docs/v2/command-line-tools/using-dataformat/virus-data-reports/#virus-annotation-report-fields). Use of this parameter requires the HTTP header, `accept: text/tab-separated-values`.' in: query required: false schema: type: array items: type: string examples: example-0: value: - accession - gene-cds-name - gene-cds-nuc-fasta-range-start - gene-cds-nuc-fasta-range-stop summary: Virus genome nucleotide accession, gene CDS name, and annotated location - name: page_size description: The maximum number of virus data reports to return. Default is 20 and maximum is 1000. If the number of results exceeds the page size, `page_token` can be used to retrieve the remaining results. in: query required: false schema: type: integer default: 20 - name: page_token description: A page token is returned when the results count exceeds `page size`. Use this token along with previous request parameters to retrieve the next page of results. When `page_token` is empty, all results have been retrieved. in: query required: false schema: type: string /virus/annotation_report: post: summary: Get a virus annotation report description: 'Get a virus annotation report. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept: application/x-ndjson) formats.' tags: - Virus operationId: virus_annotation_reports_by_post responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2reportsVirusAnnotationReportPage' application/x-ndjson: schema: $ref: '#/components/schemas/v2reportsVirusAnnotationReportPage' text/tab-separated-values: schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v2VirusAnnotationReportRequest' examples: RefSeq Virus TaxID example: description: Middle East repiratory syndrome-related coronavirus, RefSeq genomes value: filter: taxons: - '1335626' refseq_only: true /virus/accession/{accessions}/check: get: summary: Check the validity of a virus genome nucleotide accession description: Check the validity of a virus genome nucleotide accession. Output in JSON format. tags: - Virus operationId: virus_accession_availability responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2VirusAvailability' parameters: - name: accessions description: virus accessions in: path required: true schema: type: array items: type: string examples: example-0: value: NC_038294.1 summary: Betacoronavirus England 1 isolate H123990006, complete genome /virus/check: post: summary: Check the validity of a virus genome nucleotide accession description: Check the validity of a virus genome nucleotide accession. Output in JSON format. tags: - Virus operationId: virus_accession_availability_post responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/v2VirusAvailability' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v2VirusAvailabilityRequest' examples: Single Virus accession example: description: Betacoronavirus England 1 isolate H123990006, complete genome value: accessions: - NC_038294.1 /virus/taxon/{taxon}/genome/download: get: summary: Get a virus genome data package by taxon description: Download a virus genome data package including sequence, annotation, BioSample data and a detailed data report by taxon. tags: - Virus operationId: virus_genome_download responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/zip: schema: format: binary type: string description: Zip compressed stream parameters: - name: taxon description: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank in: path required: true schema: type: string examples: example-0: value: '1335626' summary: NCBI Taxonomy ID for MERS, Middle East respiratory syndrome-related coronavirus example-1: value: '2697049' summary: NCBI Taxonomy ID for SARS-CoV-2 example-2: value: '197911' summary: NCBI Taxonomy ID for the genus Alphainfluenzavirus - name: refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Inclue all genomes - name: released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: geo_location description: Limit to genomes collected from the specified geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: include_sequence description: Specify which sequence files to include in the data package. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' examples: example-0: value: - GENOME - CDS - PROTEIN summary: Include genomic, CDS, and protein sequence files - name: aux_report description: Specify which report files to include in the data package. The virus data report is always included, and its inclusion is not affected by this parameter. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' examples: example-0: value: BIOSAMPLE summary: Include the BioSample report - name: use_psg description: Experimental approach to retrieving sequence data. in: query required: false schema: type: boolean - name: filename description: Output file name. in: query required: false schema: type: string default: ncbi_dataset.zip /virus/accession/{accessions}/genome/download: get: summary: Get a virus genome data package by nucleotide accession description: Download a virus genome data package including sequence, annotation, BioSample data and a detailed data report by nucleotide accession. tags: - Virus operationId: virus_genome_download_accession responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/zip: schema: format: binary type: string description: Zip compressed stream parameters: - name: accessions description: One or more nucleotide sequence accessions in: path required: true schema: type: array items: type: string examples: example-0: value: NC_038294.1 summary: Betacoronavirus England 1 isolate H123990006, complete genome - name: taxons description: NCBI Taxonomy IDs or names (common or scientific) at any taxonomic rank in: query required: false schema: type: array items: type: string examples: example-0: value: '1335626' summary: MERS example-1: value: '2697049' summary: SARS-COV-2 example-2: value: '11118' summary: Coronaviridae - name: refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Include both RefSeq and GenBank genomes - name: annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: Inclue all genomes - name: released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: pangolin_classification description: Limit to SARS-CoV-2 genomes from the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: geo_location description: Limit to genomes collected from the specified geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: include_sequence description: Specify which sequence files to include in the data package. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' examples: example-0: value: - GENOME - CDS - PROTEIN summary: Include genomic, CDS, and protein sequence files - name: aux_report description: Specify which report files to include in the data package. The virus data report is always included, and its inclusion is not affected by this parameter. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' examples: example-0: value: BIOSAMPLE summary: Include the BioSample report - name: use_psg description: Experimental approach to retrieving sequence data. in: query required: false schema: type: boolean - name: filename description: Output file name. in: query required: false schema: type: string default: ncbi_dataset.zip /virus/genome/download: post: summary: Get a virus genome data package description: Download a virus genome data package including sequence, annotation, BioSample data and a detailed data report by nucleotide accession. tags: - Virus operationId: virus_genome_download_post responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/zip: schema: format: binary type: string description: Zip compressed stream requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v2VirusDatasetRequest' examples: Single Virus accession example: description: Betacoronavirus England 1 isolate H123990006, complete genome value: accessions: - NC_038294.1 parameters: - name: filename description: Output file name. in: query required: false schema: type: string default: ncbi_dataset.zip /virus/taxon/sars2/protein/{proteins}/download: get: summary: Get a SARS-CoV-2 protein data package by protein name description: Download a SARS-CoV-2 protein data package including sequence, annotation, BioSample data and a detailed data report by protein name. tags: - Virus operationId: sars2_protein_download responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/zip: schema: format: binary type: string description: Zip compressed stream parameters: - name: proteins description: One or more SARS-CoV-2 protein names in: path required: true schema: type: array items: type: string examples: example-0: value: spike protein summary: SARS-CoV-2 spike protein example-1: value: - spike protein - envelope protein - RdRp summary: SARS-CoV-2 spike, envelope, and RNA-dependent RNA polymerase proteins - name: refseq_only description: If true, limit results to RefSeq genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to RefSeq genomes example-1: value: false summary: Both GenBank & RefSeq genomes - name: annotated_only description: If true, limit results to annotated genomes. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to annotated genomes example-1: value: false summary: All genomes - name: released_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: updated_since in: query required: false schema: type: string format: date-time examples: example-0: value: '2025-01-15' summary: January 15th, 2025, in ISO 8601 YYYY-MM-DD format - name: host description: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). in: query required: false schema: type: string examples: example-0: value: 9606 summary: NCBI Taxonomy ID for human example-1: value: Felis catus summary: Scientific name for domestic cat - name: pangolin_classification description: Limit to SARS-CoV-2 genomes with the specified Pango lineage. in: query required: false schema: type: string examples: example-0: value: LP.8.1 summary: SARS-CoV-2 Pango lineage LP.8.1 - name: geo_location description: Limit to genomes collected from the specififed geographic location. in: query required: false schema: type: string examples: example-0: value: USA summary: USA example-1: value: Asia summary: Asia - name: usa_state description: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). in: query required: false schema: type: string examples: example-0: value: CA summary: California example-1: value: TX summary: Texas - name: complete_only description: Limit to genomes designated as complete, as defined by the submitter. in: query required: false schema: type: boolean default: false examples: example-0: value: true summary: Limit to complete genomes example-1: value: false summary: All genomes - name: include_sequence description: Specify which sequence files to include in the data package. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' examples: example-0: value: - CDS - PROTEIN summary: Include CDS and proetin sequence files - name: aux_report description: Specify which report files to include in the data package. The virus data report is always included, and its inclusion is not affected by this parameter. in: query required: false schema: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' examples: example-0: value: ANNOTATION summary: Include the annotation report - name: filename description: Output file name. in: query required: false schema: type: string default: ncbi_dataset.zip /virus/taxon/sars2/protein/download: post: summary: Get a SARS-CoV-2 protein data package description: Download a SARS-CoV-2 protein data package including sequence, annotation, BioSample data and a detailed data report. tags: - Virus operationId: sars2_protein_download_post responses: default: description: An unexpected error response. content: text/plain: schema: $ref: '#/components/schemas/rpcStatus' '200': description: A successful response content: application/zip: schema: format: binary type: string description: Zip compressed stream requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v2Sars2ProteinDatasetRequest' examples: SARS-CoV-2 virus RefSeq protein example: description: SARS-CoV-2 spike surface glycoprotein (RefSeq) value: proteins: - spike refseq_only: true include_sequence: - PROTEIN parameters: - name: filename description: Output file name. in: query required: false schema: type: string default: ncbi_dataset.zip components: schemas: v2reportsInfraspecificNames: type: object properties: breed: type: string title: A homogenous group of animals within a domesticated species cultivar: type: string title: A variety of plant within a species produced and maintained by cultivation ecotype: type: string title: A population or subspecies occupying a distinct habitat isolate: type: string title: The individual isolate from which the sequences in the genome assembly were derived sex: type: string title: Physical sex of sampled organism strain: type: string title: A genetic variant, subtype or culture within a species v2reportsConservedDomain: type: object properties: accession: type: string title: cdd accession name: type: string range: $ref: '#/components/schemas/v2reportsRange' title: range on the protein v2reportsVirusDataReportPage: type: object properties: reports: type: array items: $ref: '#/components/schemas/v2reportsVirusAssembly' total_count: type: integer title: The total count of available assemblies (ignoring the page_size parameter). next_page_token: type: string title: A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. v2reportsPurposeOfSampling: type: string enum: - PURPOSE_OF_SAMPLING_UNKNOWN - PURPOSE_OF_SAMPLING_BASELINE_SURVEILLANCE default: PURPOSE_OF_SAMPLING_UNKNOWN v2DownloadSummaryDehydrated: type: object properties: estimated_file_size_mb: type: integer url: type: string cli_download_command_line: type: string cli_rehydrate_command_line: type: string v2reportsWarning: type: object properties: gene_warning_code: $ref: '#/components/schemas/v2reportsWarningGeneWarningCode' reason: type: string message: type: string replaced_id: $ref: '#/components/schemas/v2reportsWarningReplacedId' unrecognized_identifier: type: string v2reportsOrientation: type: string enum: - none - plus - minus default: none v2reportsVirusAssemblyCollectionLocation: type: object properties: geographic_location: type: string title: Country of virus specimen collection geographic_region: type: string title: Region of virus specimen collection usa_state: type: string title: Two letter abbreviation of the state of the virus specifime collection (if United States) v2reportsWarningReplacedId: type: object properties: requested: type: string returned: type: string v2DownloadSummaryFileSummary: type: object properties: file_count: type: integer size_mb: type: number format: float v2VirusAvailability: type: object properties: valid_accessions: type: array items: type: string invalid_accessions: type: array items: type: string message: type: string v2reportsErrorGeneErrorCode: type: string enum: - UNKNOWN_GENE_ERROR_CODE - INCOMPLETE_LOOKUP_SYMBOL - INVALID_TAXON_GENE_ARGUMENT default: UNKNOWN_GENE_ERROR_CODE v2reportsVirusAssemblySubmitterInfo: type: object properties: names: type: array items: type: string affiliation: type: string title: The submitter's organization and/or institution country: type: string title: The country representing the submitter's affilation v2reportsOrganism: type: object properties: tax_id: type: integer title: NCBI Taxonomy identifier sci_name: type: string title: Scientific name organism_name: type: string title: Scientific name common_name: type: string title: Common name lineage: type: array items: $ref: '#/components/schemas/v2reportsLineageOrganism' strain: type: string pangolin_classification: type: string infraspecific_names: $ref: '#/components/schemas/v2reportsInfraspecificNames' v2TableFormat: type: string enum: - tsv - csv - jsonl default: tsv v2reportsVirusGene: type: object properties: name: type: string gene_id: type: integer nucleotide: $ref: '#/components/schemas/v2reportsSeqRangeSetFasta' title: The interval on the genomic nucleotide record of the CDS feature. cds: type: array items: $ref: '#/components/schemas/v2reportsVirusPeptide' v2DownloadSummaryAvailableFiles: type: object properties: all_genomic_fasta: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' genome_gff: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' genome_gbff: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' rna_fasta: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' prot_fasta: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' genome_gtf: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' cds_fasta: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' sequence_report: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' annotation_report: $ref: '#/components/schemas/v2DownloadSummaryFileSummary' v2VirusDatasetRequest: type: object properties: accessions: type: array items: type: string taxon: type: string title: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank taxons: type: array items: type: string refseq_only: type: boolean title: If true, limit results to RefSeq genomes. annotated_only: type: boolean title: If true, limit results to annotated genomes. released_since: type: string format: date-time updated_since: type: string format: date-time host: type: string title: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). pangolin_classification: type: string title: Limit to SARS-CoV-2 genomes from the specified Pango lineage. geo_location: type: string title: Limit to genomes collected from the specified geographic location. usa_state: type: string title: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). complete_only: type: boolean title: Limit to genomes designated as complete, as defined by the submitter. table_fields: type: array items: $ref: '#/components/schemas/v2VirusTableField' include_sequence: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' aux_report: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' format: $ref: '#/components/schemas/v2TableFormat' title: Choose download format (tsv, csv or jsonl) use_psg: type: boolean title: Experimental approach to retrieving sequence data. v2reportsVirusAssemblyCompleteness: type: string enum: - UNKNOWN - COMPLETE - PARTIAL default: UNKNOWN v2VirusDatasetReportType: type: string enum: - DATASET_REPORT - ANNOTATION - BIOSAMPLE_REPORT default: DATASET_REPORT v2DownloadSummary: type: object properties: record_count: type: integer title: The number of records for the requested filter. assembly_count: type: integer title: For backwards compatability with old VirusDatasetSummary resource_updated_on: type: string format: date-time title: The latest date on which the resource was updated. hydrated: $ref: '#/components/schemas/v2DownloadSummaryHydrated' dehydrated: $ref: '#/components/schemas/v2DownloadSummaryDehydrated' errors: type: array items: $ref: '#/components/schemas/v2reportsError' messages: type: array items: $ref: '#/components/schemas/v2reportsMessage' available_files: $ref: '#/components/schemas/v2DownloadSummaryAvailableFiles' v2VirusDataReportRequestContentType: type: string enum: - COMPLETE - ACCESSIONS_ONLY default: COMPLETE title: Specify a specific group of values to be returned, currently either all fields or accessions only v2reportsErrorAssemblyErrorCode: type: string enum: - UNKNOWN_ASSEMBLY_ERROR_CODE - INVALID_BIOPROJECT_IDS - NO_ASSEMBLIES_FOR_BIOPROJECTS - INVALID_TAXON - MISSING_SEARCH_FIELD - INVALID_BIOSAMPLE_IDS - NO_ASSEMBLIES_FOR_BIOSAMPLE_IDS - NO_ASSEMBLIES_FOR_ASSEMBLY_NAMES - INVALID_WGS_ACCESSIONS - NO_ASSEMBLIES_FOR_WGS_ACCESSIONS default: UNKNOWN_ASSEMBLY_ERROR_CODE v2TabularOutput: type: object properties: data: type: string v2ViralSequenceType: type: string enum: - GENOME - CDS - PROTEIN - NONE default: GENOME v2reportsRange: type: object properties: begin: type: string format: uint64 title: Sequence start position end: type: string format: uint64 title: Sequence stop position orientation: $ref: '#/components/schemas/v2reportsOrientation' title: Direction relative to the genome order: type: integer title: The position of this sequence in a group of sequences ribosomal_slippage: type: integer title: When ribosomal slippage is desired, fill out slippage amount between this and previous range. v2reportsErrorVirusErrorCode: type: string enum: - UNKNOWN_VIRUS_ERROR_CODE default: UNKNOWN_VIRUS_ERROR_CODE v2Sars2ProteinDatasetRequest: type: object properties: proteins: type: array items: type: string refseq_only: type: boolean title: If true, limit results to RefSeq genomes. annotated_only: type: boolean title: If true, limit results to annotated genomes. released_since: type: string format: date-time updated_since: type: string format: date-time host: type: string title: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). pangolin_classification: type: string title: Limit to SARS-CoV-2 genomes with the specified Pango lineage. geo_location: type: string title: Limit to genomes collected from the specififed geographic location. usa_state: type: string title: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). complete_only: type: boolean title: Limit to genomes designated as complete, as defined by the submitter. table_fields: type: array items: $ref: '#/components/schemas/v2VirusTableField' include_sequence: type: array items: $ref: '#/components/schemas/v2ViralSequenceType' aux_report: type: array items: $ref: '#/components/schemas/v2VirusDatasetReportType' format: $ref: '#/components/schemas/v2TableFormat' title: Specify output format v2reportsErrorTaxonomyErrorCode: type: string enum: - UNKNOWN_TAXONOMY_ERROR_CODE - INVALID_TAXONOMY_TAXON default: UNKNOWN_TAXONOMY_ERROR_CODE v2reportsVirusPeptideUniProtId: type: object properties: id: type: string title: UniProt ID name: type: string title: UniProt name v2reportsVirusPeptideViralPeptideCompleteness: type: string enum: - UNKNOWN - COMPLETE - PARTIAL default: UNKNOWN rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' v2reportsError: type: object properties: assembly_error_code: $ref: '#/components/schemas/v2reportsErrorAssemblyErrorCode' gene_error_code: $ref: '#/components/schemas/v2reportsErrorGeneErrorCode' organelle_error_code: $ref: '#/components/schemas/v2reportsErrorOrganelleErrorCode' virus_error_code: $ref: '#/components/schemas/v2reportsErrorVirusErrorCode' taxonomy_error_code: $ref: '#/components/schemas/v2reportsErrorTaxonomyErrorCode' reason: type: string message: type: string invalid_identifiers: type: array items: type: string v2VirusDataReportRequest: type: object properties: filter: $ref: '#/components/schemas/v2VirusDatasetFilter' title: All the supported filters for virus requests returned_content: $ref: '#/components/schemas/v2VirusDataReportRequestContentType' title: Return complete virus reports or nucleotide accessions only table_fields: type: array items: type: string table_format: type: string title: Optional pre-defined template for processing a tabular data request page_size: type: integer title: The maximum number of virus data reports to return. Default is 20 and maximum is 1000. If the number of results exceeds the page size, `page_token` can be used to retrieve the remaining results. page_token: type: string title: A page token is returned when the results count exceeds `page size`. Use this token along with previous request parameters to retrieve the next page of results. When `page_token` is empty, all results have been retrieved. v2reportsVirusAnnotationReport: type: object properties: accession: type: string isolate_name: type: string genes: type: array items: $ref: '#/components/schemas/v2reportsVirusGene' v2reportsVirusAssembly: type: object properties: accession: type: string title: The accession.version of the viral nucleotide sequence. Includes both GenBank and RefSeq accessions is_complete: type: boolean is_annotated: type: boolean title: The viral genome has been annotated by either the submitter (GenBank) or by NCBI (RefSeq) isolate: $ref: '#/components/schemas/v2reportsIsolate' source_database: type: string title: Indicates if the source of the viral nucleotide record is from a GenBank submitter or from NCBI-derived curation (RefSeq) protein_count: type: integer title: The total count of annotated proteins including both proteins and polyproteins but not processed mature peptides host: $ref: '#/components/schemas/v2reportsOrganism' title: Taxon from which the virus sample was isolated virus: $ref: '#/components/schemas/v2reportsOrganism' title: Viral taxon bioprojects: type: array items: type: string location: $ref: '#/components/schemas/v2reportsVirusAssemblyCollectionLocation' update_date: type: string title: Date the viral nucleotide accession was last updated in NCBI Virus release_date: type: string title: Date the viral nucleotide accession was first released in NCBI Virus nucleotide_completeness: type: string title: Value describing if the of the viral nucleotide sequence represents a complete or partial genome completeness: $ref: '#/components/schemas/v2reportsVirusAssemblyCompleteness' title: Indicates whether the viral nucleotide sequence represents a complete or partial genome length: type: integer title: Length of the viral nucleotide sequence gene_count: type: integer title: Total count of genes annotated on the viral nucleotide sequence mature_peptide_count: type: integer title: Total count of processed mature peptides annotated on the viral nucleotide sequence biosample: type: string title: Associated Biosample accessions mol_type: type: string title: ICTV (International Committee on Taxonomy of Viruses) viral classification based on nucleic acid composition, strandedness and method of replication nucleotide: $ref: '#/components/schemas/v2reportsSeqRangeSetFasta' title: The whole genomic nucleotide record of the CDS feature. purpose_of_sampling: $ref: '#/components/schemas/v2reportsPurposeOfSampling' title: SARS-CoV-2 only, indicates whether the sequence was collected randomly for epedimiology studies sra_accessions: type: array items: type: string submitter: $ref: '#/components/schemas/v2reportsVirusAssemblySubmitterInfo' title: Name, affiliation, and country of the submitter(s) lab_host: type: string title: This sequence is from viruses passaged in this host is_lab_host: type: boolean title: If true, this sequence is from viruses passaged in a laboratory is_vaccine_strain: type: boolean title: If true, this sequence is derived from a virus used as a vaccine or potential vaccine segment: type: string title: The virus segment v2reportsVirusPeptide: type: object properties: accession: type: string title: Protein accession and version name: type: string title: Protein name other_names: type: array items: type: string nucleotide: $ref: '#/components/schemas/v2reportsSeqRangeSetFasta' title: The interval on the genomic nucleotide record of this mature-peptide feature protein: $ref: '#/components/schemas/v2reportsSeqRangeSetFasta' title: The full polyprotein record or interval on the polyprotein for mature-peptide features pdb_ids: type: array items: type: string cdd: type: array items: $ref: '#/components/schemas/v2reportsConservedDomain' uni_prot_kb: $ref: '#/components/schemas/v2reportsVirusPeptideUniProtId' title: UniProt identifier mature_peptide: type: array items: $ref: '#/components/schemas/v2reportsVirusPeptide' protein_completeness: $ref: '#/components/schemas/v2reportsVirusPeptideViralPeptideCompleteness' title: Protein completeness v2DownloadSummaryHydrated: type: object properties: estimated_file_size_mb: type: integer url: type: string cli_download_command_line: type: string v2VirusAnnotationFilter: type: object properties: accessions: type: array items: type: string taxon: type: string title: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank taxons: type: array items: type: string refseq_only: type: boolean title: If true, limit to RefSeq genomes. annotated_only: type: boolean title: If true, limit to annotated genomes. released_since: type: string format: date-time updated_since: type: string format: date-time host: type: string title: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). pangolin_classification: type: string title: Limit to SARS-CoV-2 genomes from the specified Pango lineage. geo_location: type: string title: Limit to genomes collected from the specififed geographic location. usa_state: type: string title: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). complete_only: type: boolean title: Limit to genomes designated as complete, as defined by the submitter. v2reportsIsolate: type: object properties: name: type: string title: BioSample harmonized attribute names https://www.ncbi.nlm.nih.gov/biosample/docs/attributes/ source: type: string title: Source material from which the viral specimen was isolated collection_date: type: string title: The collection date for the sample from which the viral nucleotide sequence was derived v2reportsLineageOrganism: type: object properties: tax_id: type: integer title: NCBI Taxonomy identifier name: type: string title: Scientific name v2reportsVirusAnnotationReportPage: type: object properties: reports: type: array items: $ref: '#/components/schemas/v2reportsVirusAnnotationReport' total_count: type: integer title: The total count of available assemblies (ignoring the page_size parameter). next_page_token: type: string title: A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. v2reportsMessage: type: object properties: error: $ref: '#/components/schemas/v2reportsError' warning: $ref: '#/components/schemas/v2reportsWarning' v2VirusAvailabilityRequest: type: object properties: accessions: type: array items: type: string v2reportsWarningGeneWarningCode: type: string enum: - UNKNOWN_GENE_WARNING_CODE - ACCESSION_VERSION_MISMATCH - REPLACED_GENE_ID - DISCONTINUED_GENE_ID - UNRECOGNIZED_GENE_ID - UNRECOGNIZED_GENE_SYMBOL - UNRECOGNIZED_ACCESSION - UNRECOGNIZED_TAX_TOKEN - NO_GENE_ANNOTATION_FOUND - ABOVE_SPECIES_TAXON default: UNKNOWN_GENE_WARNING_CODE v2reportsErrorOrganelleErrorCode: type: string enum: - UNKNOWN_ORGANELLE_ERROR_CODE - INVALID_ORGANELLE_TAXON - NO_ORGANELLES_FOR_ACCESSION default: UNKNOWN_ORGANELLE_ERROR_CODE v2VirusTableField: type: string enum: - unspecified - nucleotide_accession - species_tax_id - species_name - genus - family - nucleotide_length - isolate_name - sequence_type - nuc_completeness - geo_location - us_state - host_name - host_tax_id - collection_date - bioproject - biosample - polyprotein_name - protein_name - protein_accession - protein_synonym - cds_span default: unspecified v2reportsSeqRangeSetFasta: type: object properties: seq_id: type: string title: Seq_id may include location info in addition to a sequence accession accession_version: type: string title: Accession and version of the viral nucleotide sequence title: type: string sequence_hash: type: string title: Unique identifier for identical sequences range: type: array items: $ref: '#/components/schemas/v2reportsRange' protobufAny: type: object properties: type_url: type: string value: type: string format: byte v2VirusDatasetFilter: type: object properties: accessions: type: array items: type: string taxon: type: string title: NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank taxons: type: array items: type: string refseq_only: type: boolean title: If true, limit results to RefSeq genomes. annotated_only: type: boolean title: If true, limit results to annotated genomes. released_since: type: string format: date-time updated_since: type: string format: date-time host: type: string title: Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name). pangolin_classification: type: string title: Limit to SARS-CoV-2 genomes from the specified Pango lineage. geo_location: type: string title: Limit to genomes collected from the specified geographic location. usa_state: type: string title: Limit to genomes collected from the specified U.S. state (two-letter abbreviation). complete_only: type: boolean title: Limit to genomes designated as complete, as defined by the submitter. v2VirusAnnotationReportRequest: type: object properties: filter: $ref: '#/components/schemas/v2VirusAnnotationFilter' table_fields: type: array items: type: string table_format: type: string title: Optional pre-defined template for processing a tabular data request page_size: type: integer title: The maximum number of virus data reports to return. Default is 20 and maximum is 1000. If the number of results exceeds the page size, `page_token` can be used to retrieve the remaining results. page_token: type: string title: A page token is returned when the results count exceeds `page size`. Use this token along with previous request parameters to retrieve the next page of results. When `page_token` is empty, all results have been retrieved. securitySchemes: ApiKeyAuth: type: apiKey in: query name: api_key ApiKeyAuthHeader: type: apiKey in: header name: api-key externalDocs: description: Interactively explore genome assembly datasets url: https://www.ncbi.nlm.nih.gov/datasets/genomes/