last update

2026-May-05

VirJenDB

v1.0

VirJenDB API

The VirJenDB API provides programmatic access to search, retrieve, and download viral genome data, and is available through the Swagger UI at https://api2.virjendb.org/swagger.

Overview of Endpoints

1. Search Endpoint

POST /v2/search

Search the VirJenDB dataset using structured JSON queries.

Request Body

{
  "items": [
    {
      "operator": "or",
      "metadataField": "string",
      "searchTerm": "string"
    }
  ],
  "filter": [
    { "field": "", "value": "" }
  ],
  "pageSize": 50,
  "pageNumber": 1,
  "sortColumn": "string",
  "sortOrder": "asc"
}

Fields

Notes

• The Swagger UI exposes operator and sortOrder as query parameters as well as in the JSON body examples. The request body shown above matches the documented example shape.
• Keep search terms non-empty for meaningful results.

Responses

Example Request

Search for records where the metadata field Host Species matches Escherichia coli.

{
  "items": [
    {
      "operator": "",
      "metadataField": "Host Species",
      "searchTerm": "Escherichia coli"
    }
  ],
  "filter": [],
  "pageSize": 50,
  "pageNumber": 1,
  "sortColumn": "",
  "sortOrder": "asc"
}

2. Download Endpoint

POST /v2/download

Download data based on search results or selected accession IDs.

Supported Data Types

• Metadata
• VirJenDB accession IDs
• Sequences

Supported File Types

• csv
• tsv
• json
• xml
• fasta (for sequence downloads)

Request Body

The download request contains two top-level parts:

• download: controls what is exported
• search: defines which records are included when download.scope is max

Download Object

Download Scope (download.scope)

selection

• Requires download.selected_ids
• The API documentation says a maximum of 10,000 IDs is supported in a single request
• If more than 10,000 IDs are supplied, only the first 10,000 are processed

max

• Uses the search object
• Supports pagination with search.pageSize and search.pageNumber
• The API documentation indicates Elasticsearch search_after is used for deep pagination
• pageSize should not exceed 10,000

Information Type (download.information)

Details

metadata

• Use download.metadata to choose which metadata fields are included
• If download.metadata is empty, all public metadata fields are included

virjendb_accessions

• Produces a lightweight list of accession IDs

sequences

• Produces FASTA output
• Metadata fields from download.metadata may be included in the FASTA header
• The accession appears first in the header, followed by additional fields separated by |

File Type (download.fileType)

Search Object in Downloads

When download.scope is max, the search object follows the same structure as the /v2/search endpoint.

It supports:

• full-text search
• filtering
• sorting
• pagination

Important Notes

• VirJenDB accession IDs use the prefix vj followed by digits, for example vj000000000010
• If no results are found, the API returns 404 Not Found
• The API documentation lists 400, 404, 422, and 500 as possible error responses for download requests
• The Swagger UI notes that some file-type and parameter combinations may be rejected by the backend with 400 Bad Request

Errors

Example Request

Download sequences for records where Host Species = Escherichia coli.

{
  "download": {
    "scope": "max",
    "information": "sequences",
    "fileType": "fasta",
    "metadata": ["Host Species", "Molecule Type"]
  },
  "search": {
    "items": [
      {
        "metadataField": "Host Species",
        "searchTerm": "Escherichia coli"
      }
    ],
    "filter": [],
    "pageSize": 50,
    "pageNumber": 1,
    "sortColumn": "",
    "sortOrder": "asc"
  }
}

3. Sequence Endpoint

POST /v2/sequence

Retrieve genome sequences using VirJenDB accession IDs.

Request Body

{
  "virjendb_accessions": [
    "vj000000000010",
    "vj000005747069"
  ]
}

Notes

• The Swagger UI describes this endpoint as a sequence download endpoint
• The response schema shown in Swagger is generic, so the exact response shape should be verified against the live API if strict parsing is needed

4. Dataset Download

GET /v2/datasets_download

Download pre-generated VirJenDB dataset files.

Query Parameter

Available Filenames

• 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

Example

filename=virjendbv1_full_dataset_sequence.csv.gz

5. Metadata Endpoints

Query Metadata Fields

POST /v2/metadata

Filter and retrieve metadata field definitions.

Request Body

{
  "field_name": [],
  "privacy": [],
  "tags": [],
  "submission_requiredness": [],
  "submission_fieldtype": [],
  "submission_validation": [],
  "match_mode": "and",
  "summary": false
}

Notes

• This endpoint appears to support filtering by multiple metadata properties
• The Swagger UI does not fully explain the meaning of every field, so field-level behavior should be treated as schema-driven rather than inferred

Download Metadata Fields

POST /v2/metadata_download

Download metadata definitions as a file.

Request Body

{
  "field_name": [],
  "file_type": "csv"
}

Notes

• Use this endpoint to export metadata field definitions
• The exact output shape depends on the server-side implementation and selected file type

dditional Resources

• Swagger UI: https://swagger.io/tools/swagger-ui
• REST API basics: https://www.freecodecamp.org/news/how-to-use-rest-api