last update

2026-July-27

VirJenDB

v1.0

VirJenDB API

Use the API to search records, retrieve sequences, download record exports or datasets, and export metadata definitions.

Getting Started

Base URL:

https://api2.virjendb.org

The API is public and does not require an API key.

API reference: interactive documentation and JSON specification.

Available Endpoints

API2 provides these five operations:

Searching Records

Basic Search

Send POST /v2/search. The required query must be a plain string:

{
  "query": "country:somalia",
  "pageSize": 5,
  "pageNumber": 1
}

Do not wrap query in an items object or encode it as an array.

Search Response

A successful search response contains these top-level fields:

Each result contains id, score, and source. Public metadata, including VirJenDB Accession, is inside source. An explicit sort can make score null. Use source["VirJenDB Accession"] in download and sequence requests.

Search Clauses

Write each clause as field:value:

Put the complete expression in one query string.

Search Multiple Conditions

Place multiple clauses in the same query string, separated by spaces:

country:somalia country:netherlands

Do not send the clauses as an array.

Search Operators

Use : to separate a field name from its value:

For multiple conditions, repeat the field:value form and separate the clauses with spaces.

Pagination

Pagination applies only to POST /v2/search:

{
  "query": "country:somalia country:netherlands",
  "pageSize": 2,
  "pageNumber": 2
}

pageSize defaults to 50 and pageNumber defaults to 1.

Search pagination is limited to the first 10,000 matching records. Narrow the query or apply filters to inspect records beyond that range.

Downloads are not paginated. The /v2/download search object accepts only query and optional filter. A scope: "max" download exports every match, so keep the query narrow.

Sorting Results

Send sortColumn and sortOrder in the JSON body:

{
  "query": "country:somalia country:netherlands",
  "sortColumn": "sequence_length",
  "sortOrder": "desc"
}

sortOrder accepts asc or desc. Send both sorting fields in the request body, not as URL query parameters.

Example Search Request

This request returns page 2 with at most two records, sorted by descending sequence length:

curl -X POST "https://api2.virjendb.org/v2/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "pageNumber": 2,
    "pageSize": 2,
    "query": "country:somalia country:netherlands",
    "sortColumn": "sequence_length",
    "sortOrder": "desc"
  }'

Results depend on the current database contents.

Downloading Records

Send POST /v2/download with both search and download objects:

The examples below use these format combinations:

Do not use JSON for multi-record downloads because the response is not valid JSON.

Download Matching Search Results

Use scope: "max" with a narrow query to export every match as CSV:

curl -X POST "https://api2.virjendb.org/v2/download" \
  -H "Accept: text/csv" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "query": "country:somalia country:netherlands"
    },
    "download": {
      "scope": "max",
      "information": "metadata",
      "fileType": "csv",
      "metadata": ["INSDC Accession", "Species NCBI", "Country"]
    }
  }' \
  --output virjendb-matches.csv

Download searches do not use pagination or sorting fields.

Download Selected Records

Use scope: "selection", an empty query, and selected_ids. This request saves the two selected accessions as TSV:

curl -X POST "https://api2.virjendb.org/v2/download" \
  -H "Accept: text/tab-separated-values" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "query": ""
    },
    "download": {
      "scope": "selection",
      "information": "virjendb_accessions",
      "fileType": "tsv",
      "selected_ids": ["vj000016638006", "vj000016638007"]
    }
  }' \
  --output virjendb-accessions.tsv

VirJenDB accessions use vj followed by 12 digits. A selection processes at most the first 10,000 IDs.

Downloading Sequences

Use information: "sequences" with fileType: "fasta":

curl -X POST "https://api2.virjendb.org/v2/download" \
  -H "Accept: application/x-fasta" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "query": ""
    },
    "download": {
      "scope": "selection",
      "information": "sequences",
      "keys": "human_readable",
      "fileType": "fasta",
      "metadata": ["Host Species"],
      "selected_ids": ["vj000016638006"]
    }
  }' \
  --output virjendb-sequences.fasta

The FASTA file begins with:

;fields=virjendb_accession|host_species
>vj000016638006|Homo sapiens

Retrieving Sequences as JSON

POST /v2/sequence returns an object that maps accessions to sequence strings:

curl -X POST "https://api2.virjendb.org/v2/sequence" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "virjendb_accessions": ["vj000000000010", "vj000005747069"]
  }'

Use /v2/download when a FASTA file or metadata in the header is required.

Downloading Precomputed Datasets

GET /v2/datasets_download requires one of the filenames below. A dataset-list endpoint is not available.

Full dataset archives can be large.

Download a checksum and its matching archive into the same directory:

curl \
  "https://api2.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_cluster_comparison_metrics.sha256" \
  --output virjendbv1_votu_cluster_comparison_metrics.sha256

curl \
  "https://api2.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_cluster_comparison_metrics.csv.gz" \
  --output virjendbv1_votu_cluster_comparison_metrics.csv.gz

sha256sum --check virjendbv1_votu_cluster_comparison_metrics.sha256

A successful check prints:

virjendbv1_votu_cluster_comparison_metrics.csv.gz: OK

Metadata Definitions

Export selected definitions with POST /v2/metadata/download:

curl -X POST "https://api2.virjendb.org/v2/metadata/download" \
  -H "Accept: text/csv" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      "VirJenDB Accession",
      "INSDC Accession",
      "Host Common Name"
    ]
  }' \
  --output virjendb-metadata-fields.csv

Select the response format with the Accept header:

Use exact public field names. Unknown names are omitted, so confirm that the response contains every requested definition.

Response Statuses

Check the HTTP status before using a response body or downloaded file.