SecMet API Documentation

antiSMASH suite API

Welcome to the antiSMASH API documentation. Here you will find how to interact with the antiSMASH suite's services using REST API calls.

antiSMASH web service

This section describes how to interact with the antiSMASH web service running at https://antismash.secondarymetabolites.org/

Submit a job

Job submissions to antiSMASH use a multipart/form-data content type, as this is the only way to upload files that is supported by all browsers.

Property	Description
`ncbi`	(either ¹ ) GenBank/RefSeq ID of a DNA sequence to download from NCBI ( `string` )
`seq`	(or ¹ ) GenBank/EMBL/FASTA file to run the analysis on ( `file` )
`gff3`	IFF `seq` is provided and a FASTA file, a GFF3 file with annotations is accepted. ( `file` )
`email`	Email address to send notifications to ( `string` )
`minimal`	Make this a cluster detection only job ( `boolean` )
`smcogs`	Run the smCoG detection ( `boolean` )
`asf`	Run with ActiveSiteFinder detection ( `boolean` )
`tta`	Detect TTA codons ( `boolean` )
`clusterblast`	Run ClusterBlast ( `boolean` )
`knownclusterblast`	Run KnownClusterBlast ( `boolean` )
`subclusterblast`	Run SubClusterBlast ( `boolean` )
`fullhmmer`	Run full-genome PFAM analysis ( `boolean` )
`borderpredict`	Run the ClusterFinder algorithm for cluster border detection ( `boolean` )
`inclusive`	Run the ClusterFinder algorithm ( `boolean` )
`cf_cdsnr`	Minimum size of a ClusterFinder cluster, in number of CDS ( `integer` )
`cf_npfams`	Minimum number of biosynthetic Pfam domains in a ClusterFinder cluster ( `integer` )
`cf_threshold`	ClusterFinder mean probability threshold ( `float` )
`genefinder`	Which gene finder to use if needed ( `string` , allowed values `none` , `prodigal` , `prodigal-m` )
`cassis`	(fungismash only ² ) Run CASSIS algorithm for cluster border prediction ( `boolean` )

One of ncbi or seq is required to run a job. If both are provided, the uploaded file is ignored.
Only available for fungiSMASH, ignored in bacterial mode

The response is a JSON object containing the antiSMASH ID of the created job.

POST

/api/v1.0/submit

Example request

$ http --form https://antismash.secondarymetabolites.org/api/v1.0/submit ncbi=Y16952 email=alice@example.com

Example response

{
    "id": "bacteria-30fca1a2-c602-11e7-baf0-c717fe9be382"
}

Query job status

Query the status of a running job

Once the job has completed successfully (state will be done), the result contains a result_url member, giving the relative URL of the result's index.html file.

GET

/api/v1.0/status/{id}

Example request

http https://antismash.secondarymetabolites.org/api/v1.0/status/bacteria-30fca1a2-c602-11e7-baf0-c717fe9be382

Example response

{
    "uid": "bacteria-30fca1a2-c602-11e7-baf0-c717fe9be382",
    "added": "2017-11-10 11:13:34.749706",
    "added_ts": "2017-11-10T11:13:34Z",
    "asf": "True",
    "borderpredict": "False",
    "cassis": "False",
    "cf_cdsnr": "5",
    "cf_npfams": "5",
    "cf_threshold": "0.6",
    "clusterblast": "False",
    "dispatcher": "nbc04-A",
    "download": "Y16952",
    "email": "alice@example.com",
    "filename": "Y16952.gbk",
    "fullhmmer": "False",
    "genefinder": "prodigal",
    "inclusive": "False",
    "jobtype": "antismash4",
    "knownclusterblast": "True",
    "last_changed": "2017-11-10 11:13:42.016316",
    "last_changed_ts": "2017-11-10T11:13:42Z",
    "minimal": "False",
    "molecule": "nucl",
    "molecule_type": "nucl",
    "short_status": "running",
    "smcogs": "True",
    "state": "running",
    "status": "running: Predicting NRPS A domain substrate specificities with SANDPUMA",
    "subclusterblast": "True",
    "taxon": "bacteria",
    "tta": "False"
}

{
    "uid": "bacteria-30fca1a2-c602-11e7-baf0-c717fe9be382",
    "state": "done",
    "result_url": "/upload/bacteria-30fca1a2-c602-11e7-baf0-c717fe9be382/index.html",
}

antiSMASH database

These API calls can be used to interact with the antiSMASH database.

Get the statistics

Get some statistics on all entries in the database.

GET

/api/v2.0/stats

Example request

$ http https://antismash-db.secondarymetabolites.org/api/v2.0/stats

Example response

{
    "clusters": [
        {
            "count": 7893,
            "description": "Nonribosomal peptide",
            "name": "nrps"
        },
        {
            "count": 5198,
            "description": "Bacteriocin or other unspecified RiPP",
            "name": "bacteriocin"
        },
        ...
    ],
    "num_clusters": 32548,
    "num_genomes": 24776,
    "num_sequences": 1210854,
    "top_secmet_assembly_id": "GCF_001542625.1",
    "top_secmet_species": "Streptomyces griseochromogenes ATCC 14511",
    "top_secmet_taxon": 68214,
    "top_secmet_taxon_count": 49,
    "top_seq_species": "Escherichia coli",
    "top_seq_taxon": 562,
    "top_seq_taxon_count": 26339
}

Search

Search in the antiSMASH database.

Property	Description
`query`	(either ¹ ) a query JSON object like used from the 'query builder' page
`search_string`	(or ¹ ) a string search like used from the 'simple query' page
`offset`	(optional) integer specifying the offset into the search
`paginate`	(optional) integer specifying how many entries to return

One of query or search_string is required to run a search. If both are provided, the search_string is ignored.

The properties are the same for both the search and export endpoints, but the valid values vary a bit.

A query object has three properties:

Property	Description
`search`	only `cluster` is valid for the `/api/v1.0/search` endpoint
`return_type`	only `json` is valid for the `/api/v1.0/search` endpoint
`terms`	a recursive binary tree of search terms.

There are two different types of search terms:

Operations

Possible operations are AND, OR and EXCEPT. They are used to build up more complicated searches.

Operations have four properties:

Property	Description
`term_type`	needs to be `op`
`operation`	one of `and` , `or` , or `except`
`left`	a valid Term object
`rigt`	a valid Term object

Expressions

Expressions are leaf nodes for the binary tree that define a search parameter.

Expressions have three properties:

Property	Description
`term_type`	needs to be `expr`
`category`	any of the allowed search categories
`term`	a search term to search the category with

POST

/api/v1.0/search

Example request

$ http https://antismash-db.secondarymetabolites.org/api/v1.0/search query:='{"search": "cluster", "return_type": "json", "terms": {"term_type": "op", "operation": "and", "left": {"term_type": "op", "operation": "or", "left": {"term_type": "expr", "category": "genus", "term": "rhodococcus"}, "right": {"term_type": "expr", "category": "genus", "term": "streptomyces"}}, "right": {"term_type": "expr", "category": "type", "term": "terpene"}}}' offset=0 paginate=50

Example request body

{
    "query": {
        "search": "cluster",
        "return_type": "json",
        "terms": {
            "term_type": "op",
            "operation": "and",
            "left": {
                "term_type": "op",
                "operation": "or",
                "left": {
                    "term_type": "expr",
                    "category": "genus",
                    "term": "rhodococcus"
                },
                "right": {
                    "term_type": "expr",
                    "category": "genus",
                    "term": "streptomyces"
                }
            },
            "right": {
                "term_type": "expr",
                "category": "type",
                "term": "terpene"
            }
        }
    },
    "offset": 0,
    "paginate": 50
}

Example response

{
    "clusters": [
        {
            "acc": "NC_012490",
            "assembly_id": "GCF_000010105",
            "bgc_id": 9919,
            "cbh_acc": "BGC0000268_c1",
            "cbh_description": "Sch47554/Sch47555",
            "cbh_rank": 1,
            "cluster_number": 8,
            "contig_edge": false,
            "description": "Hybrid cluster: Nonribosomal peptide & Terpene",
            "end_pos": 3314570,
            "genus": "Rhodococcus",
            "minimal": false,
            "similarity": 5,
            "species": "erythropolis",
            "start_pos": 3257160,
            "strain": "PR4 (= NBRC 100887)",
            "term": "nrps-terpene hybrid",
            "version": 1
        },
        {
            "acc": "NC_012490",
            "assembly_id": "GCF_000010105",
            "bgc_id": 9923,
            "cbh_acc": "BGC0000664_c1",
            "cbh_description": "Isorenieratene",
            "cbh_rank": 1,
            "cluster_number": 12,
            "contig_edge": false,
            "description": "Terpene",
            "end_pos": 3928673,
            "genus": "Rhodococcus",
            "minimal": false,
            "similarity": 42,
            "species": "erythropolis",
            "start_pos": 3907728,
            "strain": "PR4 (= NBRC 100887)",
            "term": "terpene",
            "version": 1
        },
        ...
    ],
    "offset": 0,
    "paginate": 50,
    "stats": {
        "clusters_by_phylum": {
            "data": [
                4009
            ],
            "labels": [
                "Actinobacteria"
            ]
        },
        "clusters_by_type": {
            "data": [
                7,
                15,
                ...
            ],
            "labels": [
                "amglyccycl",
                "arylpolyene",
                ...
            ]
        }
    },
    "total": 4009
}

Export

Export entries from the antiSMASH database.

Property	Description
`query`	(either ¹ ) a query JSON object like used from the 'query builder' page
`search_string`	(or ¹ ) a string search like used from the 'simple query' page
`offset`	(optional) integer specifying the offset into the search
`paginate`	(optional) integer specifying how many entries to return

One of query or search_string is required to run a search. If both are provided, the search_string is ignored.

The properties are the same for both the search and export endpoints, but the valid values vary a bit.

A query object has three properties:

Property	Description
`search`	One of `cluster` , `gene` , or `domain`
`return_type`	One of `json` , `csv` , `fasta` , or `fastaa`
`terms`	a recursive binary tree of search terms.

The cluster search type searches entire clusters, just like in the HTML output. gene and domain search CDS features and protein domains annotated on the genomes instead.

The json return type returns the same information as on the /api/v1.0/search endpoint. csv returns the same information in a tab-separated value format. fasta returns a DNA fasta file of all hits, fastaa returns a protein fasta file of all hits.

Terms work as described above.

POST

/api/v1.0/export

Example request

$ http https://antismash-db.secondarymetabolites.org/api/v1.0/export query:='{"search": "cluster", "return_type": "csv", "terms": {"term_type": "op", "operation": "and", "left": {"term_type": "op", "operation": "or", "left": {"term_type": "expr", "category": "genus", "term": "rhodococcus"}, "right": {"term_type": "expr", "category": "genus", "term": "streptomyces"}}, "right": {"term_type": "expr", "category": "type", "term": "terpene"}}}' offset=0 paginate=50

Example request body

{
    "query": {
        "search": "cluster",
        "return_type": "csv",
        "terms": {
            "term_type": "op",
            "operation": "and",
            "left": {
                "term_type": "op",
                "operation": "or",
                "left": {
                    "term_type": "expr",
                    "category": "genus",
                    "term": "rhodococcus"
                },
                "right": {
                    "term_type": "expr",
                    "category": "genus",
                    "term": "streptomyces"
                }
            },
            "right": {
                "term_type": "expr",
                "category": "type",
                "term": "terpene"
            }
        }
    },
    "offset": 0,
    "paginate": 50
}

Example response

#Genus	Species	Strain	NCBI accession	Cluster number	BGC type	From	To	On contig edge	Fast mode only	Most similar known cluster	Similarity in %	MIBiG BGC-ID	Results URL	Download URL
Rhodococcus	erythropolis	PR4 (= NBRC 100887)	NC_012490.1	8	nrps-terpene hybrid	3257160	3314570	False	False	Sch47554/Sch47555	5	BGC0000268_c1	https://antismash-db.secondarymetabolites.org/go/GCF_000010105/8	https://antismash-db.secondarymetabolites.org/api/v1.0/download/genbank/GCF_000010105/cluster/8
Rhodococcus	erythropolis	PR4 (= NBRC 100887)	NC_012490.1	12	terpene	3907728	3928673	False	False	Isorenieratene	42	BGC0000664_c1	https://antismash-db.secondarymetabolites.org/go/GCF_000010105/12	https://antismash-db.secondarymetabolites.org/api/v1.0/download/genbank/GCF_000010105/cluster/12
Streptomyces	griseus	NBRC 13350	NC_010572.1	1	terpene	47131	72706	False	False	Isorenieratene	100	BGC0000664_c1	https://antismash-db.secondarymetabolites.org/go/GCF_000010605/1	https://antismash-db.secondarymetabolites.org/api/v1.0/download/genbank/GCF_000010605/cluster/1