{"openapi":"3.1.0","info":{"title":"VirJenDB API","version":"2.0.2"},"paths":{"/v2/datasets_download":{"get":{"tags":["Download"],"summary":"Download VirJenDB datasets","operationId":"download_file_v2_datasets_download_get","parameters":[{"name":"filename","in":"query","description":"Select a dataset file to download","required":true,"schema":{"type":"string","enum":["ncbi_to_gtdb_map.csv.gz","virjendbv1_full_dataset_sequence.csv.gz","virjendbv1_unique_seqs_sequence.csv.gz","virjendbv1_votu_clusters_metadata.csv.gz","ncbi_to_gtdb_map.sha256","virjendbv1_full_dataset_sequence.sha256","virjendbv1_unique_seqs_sequence.sha256","virjendbv1_votu_clusters_metadata.sha256","virjendbv1_full_dataset_metadata.csv.gz","virjendbv1_unique_seqs_metadata.csv.gz","virjendbv1_votu_cluster_comparison_metrics.csv.gz","virjendbv1_votu_clusters_sequence.csv.gz","virjendbv1_full_dataset_metadata.sha256","virjendbv1_unique_seqs_metadata.sha256","virjendbv1_votu_cluster_comparison_metrics.sha256","virjendbv1_votu_clusters_sequence.sha256"]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Download one of the available VirJenDB dataset files by selecting the filename query parameter. The endpoint supports gzip-compressed dataset archives and checksum files."}},"/v2/download":{"post":{"tags":["Download"],"summary":"Download VirJenDB data","operationId":"_process_download_v2_download_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"download":{"type":"object","properties":{"scope":{"type":"string","enum":["selection","max"]},"information":{"type":"string","enum":["metadata","virjendb_accessions","sequences"]},"keys":{"type":"string","enum":["id","alias","human_readable"],"description":"Optional key type for accessions or sequence downloads."},"fileType":{"type":"string","enum":["csv","fasta","json","tsv","xml"]},"metadata":{"type":"array","items":{"type":"string"}},"selected_ids":{"type":"array","items":{"type":"string"}}},"required":["scope","information","fileType"]},"search":{"type":"object","properties":{"query":{"type":"string"},"filter":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"value":{}},"required":["field","value"]}}},"required":["query"]}},"required":["download","search"]},"examples":{"download_selection_metadata":{"summary":"Download selected metadata list","value":{"download":{"fileType":"csv","information":"metadata","metadata":["INSDC Accession","Species NCBI","Isolate","Molecule Type","Genome Completeness","Sequence Length","Host Species","Submitter","Collection Date","Country"],"scope":"selection","selected_ids":["vj000016638006","vj000016638007","vj000014557800","vj000014535505","vj000014553356"]},"search":{"query":""}}},"download_max_metadata":{"summary":"Download metadata for a search query","value":{"download":{"scope":"max","information":"metadata","fileType":"json","metadata":["INSDC Accession","Species NCBI","Country"]},"search":{"query":"host_species:Escherichia coli"}}},"download_selection_accessions":{"summary":"Download selected accession ids","value":{"download":{"scope":"selection","information":"virjendb_accessions","fileType":"tsv","selected_ids":["vj000016638006","vj000016638007"]},"search":{"query":""}}}}}}},"responses":{"200":{"description":"Successful download of data.","content":{"text/csv":{"schema":{"type":"string","format":"binary"},"examples":{"csv_example":{"value":"Accession,Molecule Type\n12345,ssRNA(+)\n67890,dsDNA"}}},"text/tab-separated-values":{"schema":{"type":"string","format":"binary"},"examples":{"tsv_example":{"value":"Accession\tMolecule Type\n12345\tssRNA(+)\n67890\tdsDNA"}}},"application/x-fasta":{"schema":{"type":"string","format":"binary"},"examples":{"fasta_example":{"value":">12345|ssRNA(+)\nAGCTAGCTAGCT\n>67890|dsDNA\nTCGATCGATCGA"}}}}},"400":{"description":"Bad Request: Invalid parameters, unsupported file type (e.g., XML), or empty search term."},"404":{"description":"Not Found: No results found for the given criteria or selected IDs."},"500":{"description":"Internal Server Error: An issue occurred on the server (e.g., Elasticsearch error)."}},"description":"\nAllows users to download data from the VirJenDB database based on specific search criteria\nor selected entries. This endpoint supports various data types (metadata, virjendb_accessions, sequences)\nand file formats (TSV, CSV, JSON, XML, FASTA).\n\n### Download Scope (`download.scope`):\nControl what data is included in your download:\n\n- **`selection`**:\n  Downloads only the records explicitly identified by their 'VirJenDB Accession' IDs in the `download.selected_ids` list.\n  This is ideal for downloading a specific subset of results, perhaps after a prior search and selection\n  on the client-side. The maximum number of IDs supported in a single 'selection' download is 10,000.\n  If you provide more than 10,000 IDs, only the first 10,000 will be processed.\n\n- **`max`**:\n  Downloads data for records matching the criteria defined in the `search` object. This scope leverages\n  Elasticsearch's `search_after` mechanism for efficient deep pagination, allowing you to retrieve\n  large result sets in pages.\n\n  Use `search.pageNumber` and `search.pageSize` to specify which portion of the total search hits you wish to download.\n  For example, `pageNumber=1` and `pageSize=10000` will download the first 10,000 results, while\n  `pageNumber=2` and `pageSize=10000` will download records 10,001 to 20,000. There is **no hard limit** on the total\n  number of records you can potentially paginate through, as long as the `pageSize` itself does not exceed\n  the Elasticsearch 10000.\n\n### Information Type (`download.information`):\nSpecify the type of information to be downloaded for the selected records:\n\n- **`metadata`**:\n  Downloads the metadata fields for each record. You can specify which fields to include\n  using `download.metadata`. If `download.metadata` is empty, all public metadata fields\n  will be included by default.\n\n- **`virjendb_accessions`**:\n  Downloads only the 'VirJenDB Accession' IDs for each record. This is a lightweight option\n  for obtaining a list of identifiers.\n\n- **`sequences`**:\n  Downloads the sequence data along with the accession and other requested metadata\n  fields (from `download.metadata`) for each record. Sequences are provided in FASTA\n  format. This can be a large download depending on the number of records and sequence\n  lengths.\n\n### File Type (`download.fileType`):\nChoose the desired output file format:\n\n- **`tsv`**: Tab-Separated Values.\n- **`csv`**: Comma-Separated Values.\n- **`xml`**: Extensible Markup Language — a structured text format for hierarchical data.\n- **`json`**: JavaScript Object Notation — a lightweight format for structured data, commonly used in APIs.\n- **`fasta`**: FASTA format (only available for `information: \"sequences\"`).\n\n### Search Parameters (`search` object):\nWhen `download.scope` is `max`, the `search` object's parameters are used to define\nthe dataset to be downloaded. These parameters work identically to the `/v2/search` endpoint,\nallowing for complex queries, filtering, sorting, and pagination.\n\n**Important Notes:**\n- When downloading `sequences` in FASTA format, metadata fields (from `download.metadata`)\n  will be included in the FASTA header, separated by |. The VirJenID field is always\n  included as the first identifier in the FASTA header.\n- The `pageSize` for `search_request` in 'max' scope determines the number of records\n  in the downloaded file.\n- If no results are found for the given criteria or selections, a `404 Not Found`\n  error will be returned.\n- Internal Elasticsearch 10,000 limits for individual Elasticsearch requests are handled\n  by the backend using `search_after` for deep pagination, but the `pageSize` you request\n  directly dictates the number of results in your download chunk.\n","parameters":[]}},"/v2/sequence":{"post":{"tags":["Search"],"summary":"Download VirJenDB sequence","operationId":"_post_sequence_v2_sequence_post","requestBody":{"description":"The VirJenDB accession numbers to download genome sequence(s).","required":true,"content":{"application/json":{"example":{"virjendb_accessions":["vj000000000010","vj000005747069"]},"schema":{"type":"object","properties":{"virjendb_accessions":{"type":"array","items":{"type":"string"},"description":"List of accession numbers."}},"required":["virjendb_accessions"]}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response  Post Sequence V2 Sequence Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/search":{"post":{"tags":["Search"],"summary":"Search VirJenDB dataset","description":"This endpoint allows you to search the VirJenDB database using a query string and optional paging/sorting settings.\n\nUse the `query` field for the search query and optionally provide `filter`, `pageSize`, `pageNumber`, `sortColumn`, and `sortOrder`.","operationId":"_do_search_v2_search_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Search query string using field:value expressions."},"filter":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"value":{}},"required":["field","value"]},"description":"Optional filters to apply to the search results."},"pageSize":{"type":"integer","default":50,"description":"Number of results per page"},"pageNumber":{"type":"integer","default":1,"description":"Page number"},"sortColumn":{"type":"string","description":"Field to sort results by (optional)."},"sortOrder":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order"}},"required":["query"]},"examples":{"v2_search_example":{"summary":"Actual v2 search example","value":{"pageNumber":2,"pageSize":2,"query":"country:somal country:nether","sortColumn":"sequence_length","sortOrder":"desc"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response  Do Search V2 Search Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"sortOrder","in":"query","description":"Sort order, either 'asc' or 'desc'.","required":false,"schema":{"type":"string","enum":["asc","desc"]}}]}},"/v2/metadata/download":{"post":{"tags":["Metadata"],"summary":"Download selected metadata fields","description":"Download selected public metadata fields in CSV, JSON, or XLSX format. Use the Accept header to choose the desired output format.","operationId":"_download_v2_metadata_download_post","parameters":[{"name":"accept","in":"header","required":false,"schema":{"allOf":[{"$ref":"#/components/schemas/DownloadMime"}],"default":"text/csv","title":"Accept"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string"},"description":"List of public metadata field names to download."}},"required":["fields"]},"examples":{"metadata_example":{"summary":"Download selected metadata fields","value":{"fields":["Sequence Name","Accession","Host Common Name"]}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body__process_download_v2_download_svelte_post":{"properties":{"format":{"$ref":"#/components/schemas/FileType"},"scope":{"$ref":"#/components/schemas/NewScope"},"columns":{"type":"string","title":"Columns"},"sequences":{"type":"boolean","title":"Sequences"},"query":{"type":"string","title":"Query"},"ids":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ids"}},"type":"object","required":["format","scope","columns","sequences","query"],"title":"Body__process_download_v2_download_svelte_post"},"Body__process_form_download_v2_download_form_post":{"properties":{"download":{"type":"string","title":"Download"},"search":{"type":"string","title":"Search"}},"type":"object","required":["download","search"],"title":"Body__process_form_download_v2_download_form_post"},"Body_file_submitter_api_bc_file_submitter_post":{"properties":{"json_file":{"type":"string","format":"binary","title":"Json File"}},"type":"object","required":["json_file"],"title":"Body_file_submitter_api_bc_file_submitter_post"},"Body_file_validator_only_api_bc_file_validator_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"}},"type":"object","required":["file"],"title":"Body_file_validator_only_api_bc_file_validator_post"},"DownloadMime":{"type":"string","enum":["text/csv","application/json","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],"title":"DownloadMime"},"DownloadSpec":{"properties":{"scope":{"$ref":"#/components/schemas/Scope"},"information":{"$ref":"#/components/schemas/Information"},"keys":{"anyOf":[{"$ref":"#/components/schemas/KeyType"},{"type":"null"}],"default":"human_readable"},"fileType":{"$ref":"#/components/schemas/FileType"},"metadata":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata"},"selected_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Selected Ids","default":[]}},"type":"object","required":["scope","information","fileType"],"title":"DownloadSpec"},"EmailRequest":{"properties":{"subject":{"type":"string","title":"Subject"},"body":{"type":"string","title":"Body"}},"type":"object","required":["subject","body"],"title":"EmailRequest"},"FileType":{"type":"string","enum":["csv","fasta","json","tsv","xml"],"title":"FileType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Information":{"type":"string","enum":["virjendb_accessions","metadata","sequences"],"title":"Information"},"KeyType":{"type":"string","enum":["id","alias","human_readable"],"title":"KeyType"},"NewScope":{"type":"string","enum":["all","ids"],"title":"NewScope"},"ObjectMetadata":{"properties":{"createdTime":{"type":"string","title":"Createdtime"},"id":{"type":"string","title":"Id"}},"type":"object","required":["createdTime","id"],"title":"ObjectMetadata"},"ProjectInput":{"properties":{"projectTitle":{"type":"string","title":"Projecttitle"},"projectDescription":{"type":"string","title":"Projectdescription"},"projectContributors":{"items":{"type":"string"},"type":"array","title":"Projectcontributors"},"numberOfSamples":{"type":"integer","title":"Numberofsamples"},"numberOfExperiments":{"type":"integer","title":"Numberofexperiments"},"numberOfAnalysis":{"type":"integer","title":"Numberofanalysis"},"createdTime":{"type":"string","title":"Createdtime"},"lastEditedTime":{"type":"string","title":"Lasteditedtime"},"projectID":{"type":"string","title":"Projectid"}},"type":"object","required":["projectTitle","projectDescription","projectContributors","numberOfSamples","numberOfExperiments","numberOfAnalysis"],"title":"ProjectInput"},"Scope":{"type":"string","enum":["max","selection"],"title":"Scope"},"SearchRequest":{"properties":{"query":{"type":"string","title":"Query"},"filter":{"items":{"type":"object"},"type":"array","title":"Filter","default":[]},"pageSize":{"type":"integer","title":"Pagesize","default":50},"pageNumber":{"type":"integer","title":"Pagenumber","default":1},"sortColumn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortcolumn"},"sortOrder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder","default":"asc"}},"type":"object","required":["query"],"title":"SearchRequest","example":{"pageNumber":2,"pageSize":2,"query":"country:somal country:nether","sortColumn":"sequence_length","sortOrder":"desc"}},"SearchSpec":{"properties":{"filter":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Filter"},"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"SearchSpec"},"SequenceRequest":{"properties":{"virjendb_accessions":{"items":{"type":"string","pattern":"^vj\\d{12}$"},"type":"array","title":"Virjendb Accessions"}},"type":"object","required":["virjendb_accessions"],"title":"SequenceRequest","example":{"virjendb_accessions":["vj000000000010","vj000005747069"]}},"Suggestion":{"properties":{"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias"},"replace":{"type":"string","title":"Replace"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field"},"public":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public"},"type":{"type":"string","title":"Type"}},"type":"object","required":["replace","type"],"title":"Suggestion","example":{"alias":"ncbi_species","field":"0gl","public":"NCBI Species","type":"text"}},"SuggestionRequest":{"properties":{"term":{"type":"string","title":"Term"},"limit":{"type":"integer","title":"Limit","default":5}},"type":"object","required":["term"],"title":"SuggestionRequest","example":{"limit":5,"term":"ncbi_"}},"SuggestionResponse":{"properties":{"suggestions":{"items":{"$ref":"#/components/schemas/Suggestion"},"type":"array","title":"Suggestions"}},"type":"object","required":["suggestions"],"title":"SuggestionResponse","example":[{"alias":"ncbi_species","field":"0gl","public":"NCBI Species","type":"text"},{"alias":"ncbi_speciestax_id","field":"0cl","public":"NCBI SpeciesTax ID","type":"integer"},{"alias":"ncbi_subclass","field":"0ge","type":"text"}]},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ViralzoneRequest":{"properties":{"rank_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rank Name","example":"genus"},"taxon_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Taxon Name","example":"Enterovirus"},"virjendb_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Virjendb Id"}},"type":"object","title":"ViralzoneRequest","example":{"rank_name":"genus","taxon_name":"Enterovirus"}},"application__download__model__DownloadRequest":{"properties":{"search":{"$ref":"#/components/schemas/SearchSpec"},"download":{"$ref":"#/components/schemas/DownloadSpec"}},"type":"object","required":["search","download"],"title":"DownloadRequest","example":{"download":{"fileType":"csv","information":"metadata","metadata":["INSDC Accession","Species NCBI","Isolate","Molecule Type","Genome Completeness","Sequence Length","Host Species","Submitter","Collection Date","Country"],"scope":"selection","selected_ids":["vj000016638006","vj000016638007","vj000014557800","vj000014535505","vj000014553356"]},"search":{"query":""}}},"application__metadata__model__DownloadRequest":{"properties":{"fields":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Fields","default":[]}},"type":"object","title":"DownloadRequest","example":{"fields":["Assembly Accession","Bioproject Accession","Biosample Accession","Accession BV-BRC","Host Accession","Host BioProject Accession","Host Biosample Accession","Host IMGM Taxon OID","INSDC Accession","Lineage IDs NCBI","Tax ID NCBI","SRA Accession","VirJenDB Accession"]}}}}}