API#
In brief#
Version 4.1 of mOTUs-db comes with an API that allows automated access to genomic information stored in the database. For any of the ~4 million genomes users can retrieve the genome sequence, its predicted genes and proteins, functional annotations (KEGG, Pfam, eggNOG), non-coding RNA predictions (tRNA, rRNA) and antiSMASH results. Additionally, antiSMASH results can be visualized in the antiSMASH viewer.
The API is available at motus-api.microbiomics.io and is open: no API key is required, and every response is either a JSON document or a downloadable file.
The most accessible way to explore the API is through its interactive documentation. Open the link in a new tab, expand the Download or Viewer sections
and press Try it out to run a live request without writing any code.
Experienced users can either consume the machine-readable OpenAPI specification to generate a client in the language of their choice or interact with the API through the mOTUs tool.
Endpoints#
All endpoints use the GET method, so every request shown below can be pasted
straight into a browser address bar. The {genome} path segment is a genome identifier within mOTUs-db, e.g.
ARTA20-1_SAMN17006400_MAG_00000010. Data endpoints are versioned under the
/v1/ prefix. An unknown genome or an unsupported file_type returns an HTTP
422 response with a JSON body describing the problem.
Endpoint |
Description |
|---|---|
|
Return server health and confirm the master database is reachable. |
|
Return the versions of all tools and databases bundled in this release. |
|
Download a file associated with a genome (see |
|
Open the antiSMASH HTML viewer for a genome. |
Downloading genome files#
GET /v1/genomes/{genome}/download
Streams a single file for the requested genome. The file is selected with the required file_type query parameter:
File Type |
Content |
|---|---|
|
Genome sequence (nucleotide, FASTA) |
|
Predicted gene sequences (nucleotide, FASTA) |
|
Predicted protein sequences (amino acid, FASTA) |
|
Gene coordinates (GFF) |
|
KEGG functional annotations |
|
Pfam domain annotations |
|
eggNOG functional annotations |
|
tRNA predictions |
|
rRNA predictions |
|
antiSMASH results (biosynthetic gene clusters) |
Each file is streamed with a Content-Disposition header carrying its correct name,
so the -OJ flag will save the download under the server-provided name. The examples below download one
file of every type for a single genome:
# Genome sequence (nucleotide, FASTA)
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=genome"
# Predicted gene sequences (nucleotide, FASTA)
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=gene_fna"
# Predicted protein sequences (amino acid, FASTA)
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=gene_faa"
# Gene coordinates (GFF)
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=gene_gff"
# KEGG functional annotations
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=kegg"
# Pfam domain annotations
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=pfam"
# eggNOG functional annotations
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=eggnog"
# tRNA predictions
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=trna"
# rRNA predictions
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=rrna"
# antiSMASH results (biosynthetic gene clusters)
curl -OJ "https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/download?file_type=antismash"
antiSMASH viewer#
GET /v1/genomes/{genome}/viewer/antismash/
antiSMASH produces an interactive HTML report that can be accessed directly through the mOTUs API. Because the report is a web page rather than a data file, it can be directly opened in a browser for viewing:
https://motus-api.microbiomics.io/v1/genomes/ARTA20-1_SAMN17006400_MAG_00000010/viewer/antismash/
System endpoints#
GET /health returns the server status and confirms the master database is reachable.
GET /v1/versions returns the versions of the tools and databases bundled in the current release.
curl "https://motus-api.microbiomics.io/health"
curl "https://motus-api.microbiomics.io/v1/versions"
mOTUs is part of SIB's portfolio of open tools and databases.
mOTUs is part of the ELIXIR-CH Service Delivery Plan.