MMseqs2 Server API documentation version v1
https://search.mmseqs.com/api
The MMseqs2 desktop and web server app facilitates interactive sequence searches through custom protein sequence and profile databases on personal workstations. By eliminating MMseqs2's runtime overhead, we reduced response times to a few seconds at sensitivities close to BLAST.
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
A python3 API usage example can be found here.
/databases
Provides a list of available search databases, including all parameters needed for the frontend.
get /databases
Provides a list of available search databases, including all parameters needed for the frontend.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- databases: required (array of database)
Items: database
- name: required (string)
Name of the search database.
Example:
Uniclust30 - version: required (string)
Version of the database.
Example:
2017_10 - path: required (string)
Identifier and path substring.
Example:
uniclust30_2017_07_seed - default: required (boolean)
If a database is pre-selected by default for a new user.
- order: required (integer)
In which order the database should be shown in the user interface. 0 is the first.
- search: required (string)
Extra parameters that are passed to MMseqs2. Useful parameters would be "-s 7" for a high sensitivty search or "--num-iterations 2" for a iterative-profile search.
Example:
-s 7
Example:
{ "name": "Uniclust30", "version" : "2017_10", "path" : "uniclust30_2017_10_seed", "default" : true, "order" : 0, "search" : "-s 7" } - name: required (string)
Example:
{ "databases" :
[{
"name": "Uniclust30",
"version" : "2017_10",
"path" : "uniclust30_2017_10_seed",
"default" : true,
"order" : 0,
"search" : ""
}]
}
HTTP status code 400
A configuration error occured. A database ".params" file was invalid and could be decoded.
Reorders the databases. Only available if server was started with "-server.dbmanagment true" parameter.
post /databases/order
Reorders the databases. Only available if server was started with "-server.dbmanagment true" parameter.
Body
Media type: application/x-www-form-urlencoded
Type: object
Properties- database[]: required (array of path)
Submitted as application/x-www-form-urlencoded. Provide database[] multiple times for each path: database[]=uniclust30_2017_07_seed&database[]=pfam_31.0
/database
Adds or removes a search database for processing. Only available if server was started with "-server.dbmanagment true" parameter.
post /database
Adds or removes a search database for processing. Only available if server was started with "-server.dbmanagment true" parameter.
Body
Media type: application/x-www-form-urlencoded
Type: object
Properties- path: required (string)
Example:
uniclust30_2017_07_seed - name: required (string)
Name of the search database.
Example:
Uniclust30 - version: required (string)
Version of the database.
Example:
2017_10 - default: required (boolean)
If a database is pre-selected by default for a new user.
- order: required (integer)
In which order the database should be shown in the user interface. 0 is the first.
- search: required (string)
Extra parameters that are passed to MMseqs2. Useful parameters would be "-s 7" for a high sensitivty search or "--num-iterations 2" for a iterative-profile search.
Example:
-s 7 - format: required (one of fasta, stockholm)
Format of database. Sequence databases must be in FASTA format. Profile (Multiple sequence alignment) databases must be in STOCKHOLM format.
Example:
fasta - file: required (union of string or file)
If submitted as "application/x-www-form-urlencoded" file must be a FASTA string. If submitted as "multipart/form-data" file must be a FASTA file.
Example:
>TEST MPKIIEAIYENGVFKPLQKVDLKEGEKAKIVLESISDKTFGILKASETEIKKVLEEIDDFWGVC >TEST2 ...
Example:
{
"name": "Uniclust30",
"version" : "2017_10",
"path" : "uniclust30_2017_10_seed",
"default" : true,
"order" : 0,
"search" : "-s 7"
}
Media type: multipart/form-data
Type: object
Properties- path: required (string)
Example:
uniclust30_2017_07_seed - name: required (string)
Name of the search database.
Example:
Uniclust30 - version: required (string)
Version of the database.
Example:
2017_10 - default: required (boolean)
If a database is pre-selected by default for a new user.
- order: required (integer)
In which order the database should be shown in the user interface. 0 is the first.
- search: required (string)
Extra parameters that are passed to MMseqs2. Useful parameters would be "-s 7" for a high sensitivty search or "--num-iterations 2" for a iterative-profile search.
Example:
-s 7 - format: required (one of fasta, stockholm)
Format of database. Sequence databases must be in FASTA format. Profile (Multiple sequence alignment) databases must be in STOCKHOLM format.
Example:
fasta - file: required (union of string or file)
If submitted as "application/x-www-form-urlencoded" file must be a FASTA string. If submitted as "multipart/form-data" file must be a FASTA file.
Example:
>TEST MPKIIEAIYENGVFKPLQKVDLKEGEKAKIVLESISDKTFGILKASETEIKKVLEEIDDFWGVC >TEST2 ...
Example:
{
"name": "Uniclust30",
"version" : "2017_10",
"path" : "uniclust30_2017_10_seed",
"default" : true,
"order" : 0,
"search" : "-s 7"
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- id: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw - status: required (one of PENDING, RUNNING, COMPLETE, ERROR, UNKNOWN - default: PENDING)
Ticket status
Example:
{
"id" : "v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw",
"status" : "COMPLETE"
}
HTTP status code 400
Invalid database or decoding error.
delete /database
Adds or removes a search database for processing. Only available if server was started with "-server.dbmanagment true" parameter.
/ticket
Submits a new job to the queue and gets a ticket referencing this job. Ticket is needed for all further api calls regarding this job.
post /ticket
Submits a new job to the queue and gets a ticket referencing this job. Ticket is needed for all further api calls regarding this job.
Body
Media type: application/x-www-form-urlencoded
Type: object
Properties- q: required (union of fasta or file)
One or more query sequence in FASTA format. If submitted as "application/x-www-form-urlencoded" q must be a FASTA string. If submitted as "multipart/form-data" q must be a FASTA file.
- database[]: required (array of path)
Databases to search against.
- mode: required (one of all, summary - default: all)
Search mode. Either all hit mode "all" or greedy-best hit mode "summary".
- email: required (union of string or nil)
Email address for notifications.
Media type: multipart/form-data
Type: object
Properties- q: required (union of fasta or file)
One or more query sequence in FASTA format. If submitted as "application/x-www-form-urlencoded" q must be a FASTA string. If submitted as "multipart/form-data" q must be a FASTA file.
- database[]: required (array of path)
Databases to search against.
- mode: required (one of all, summary - default: all)
Search mode. Either all hit mode "all" or greedy-best hit mode "summary".
- email: required (union of string or nil)
Email address for notifications.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- id: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw - status: required (one of PENDING, RUNNING, COMPLETE, ERROR, UNKNOWN - default: PENDING)
Ticket status
Example:
{
"id" : "v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw",
"status" : "COMPLETE"
}
HTTP status code 400
Gets the status of a ticket
get /ticket/{ticket}
Gets the status of a ticket
URI Parameters
- ticket: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- id: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw - status: required (one of PENDING, RUNNING, COMPLETE, ERROR, UNKNOWN - default: PENDING)
Ticket status
Example:
{
"id" : "v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw",
"status" : "COMPLETE"
}
HTTP status code 400
Error if ticket was not found or could not be encoded to JSON.
Gets the type of the ticket
get /ticket/type/{ticket}
Gets the type of the ticket
URI Parameters
- ticket: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw
/tickets
Gets the status of multiple tickets
post /tickets
Gets the status of multiple tickets
Body
Media type: application/x-www-form-urlencoded
Type: object
Properties- tickets[]: required (array of string)
Submitted as application/x-www-form-urlencoded. Provide tickets[] multiple times for each path: tickets[]=lvtydCEDvWFkerPNYmZAdcw2UgbuR2kF1YwJ2g&tickets[]=v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw
HTTP status code 200
Body
Media type: application/json
Type: array of object
Items: ticketResponse
- id: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw - status: required (one of PENDING, RUNNING, COMPLETE, ERROR, UNKNOWN - default: PENDING)
Ticket status
Example:
[{
"id" : "lvtydCEDvWFkerPNYmZAdcw2UgbuR2kF1YwJ2g",
"status" : "COMPLETE"
}, {
"id" : "v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw",
"status":"COMPLETE"
}]
HTTP status code 400
/result
Gets the alignment results for query number entry of the ticket.
get /result/{ticket}/{entry}
Gets the alignment results for query number entry of the ticket.
URI Parameters
- ticket: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw - entry: required (number)
The results of which query should be fetched.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- query: required (object)
- header: required (string)
- sequence: required (string)
Example:
{ "header" : "TEST", "sequence" : "MPKIIEAIYENGVFKPLQKVDLKEGEKAKIVLESISDKTFGILKASETEIKKVLEEIDDFWGVC" } - results: required (array of databasebresults)
Items: databasebresults
- db: required (string)
Database identifier.
Example:
uniclust30_2017_07_seed - alignments: required (array of alignments)
Items: alignments
- query: required (string)
- target: required (string)
- seqId: required (number)
- alnLength: required (integer)
- missmatches: required (integer)
- gapsopened: required (integer)
- qStartPos: required (integer)
- qEndPos: required (integer)
- dbStartPos: required (integer)
- dbEndPos: required (integer)
- eval: required (union of number or string)
- score: required (integer)
- qLen: required (integer)
- dbLen: required (integer)
Example:
{ "query": "TEST", "target": "A0A075WD96", "seqId": 1, "alnLength": 64, "missmatches": 0, "gapsopened": 0, "qStartPos": 1, "qEndPos": 64, "dbStartPos": 1, "dbEndPos": 64, "eval": 1.65e-34, "score": 130, "qLen": 64, "dbLen": 64 }
Example:
{ "db" : "uniclust30_2017_10_seed", "alignments" : [{ "query" : "TEST", "target" : "A0A075WD96", "seqId" : 1, "alnLength" : 64, "missmatches" : 0, "gapsopened" : 0, "qStartPos" : 1, "qEndPos" : 64, "dbStartPos" : 1, "dbEndPos" : 64, "eval" : 1.65e-34, "score" : 130, "qLen" : 64, "dbLen" : 64 }] } - db: required (string)
Example:
{
"query" : {
"header" : "TEST",
"sequence" : "MPKIIEAIYENGVFKPLQKVDLKEGEKAKIVLESISDKTFGILKASETEIKKVLEEIDDFWGVC"
},
"results" : [{
"db" : "uniclust30_2017_10_seed",
"alignments" : [{
"query" : "TEST",
"target" : "A0A075WD96",
"seqId" : 1,
"alnLength" : 64,
"missmatches":0,
"gapsopened":0,
"qStartPos":1,
"qEndPos":64,
"dbStartPos":1,
"dbEndPos":64,
"eval":1.65e-34,
"score":130,
"qLen":64,
"dbLen":64
}]
}]
}
HTTP status code 400
Downloads all alignment results in a BLAST-tab compatible format for the specified ticket.
get /result/download/{ticket}
Downloads all alignment results in a BLAST-tab compatible format for the specified ticket.
URI Parameters
- ticket: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw
Gets a paginated list of queries belonging to a search job.
get /result/queries/{ticket}/{limit}/{page}
Gets a paginated list of queries belonging to a search job.
URI Parameters
- ticket: required (string)
The ticket object is a basic element of the API. Any job submission returns a ticket. The job status has to be polled based on this ticket. Once a job is in the "COMPLETED" state. Results can be fetched based on the "/result" endpoint.
Example:
v04cLYK_gxRUMOWy7pXvUNxzSYWAmoDO38gLUw - limit: required (integer)
Number of queries per page.
- page: required (integer)
Which page should be fetched.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- lookup: required (array of lookup)
Items: lookup
- id: required (integer)
Entry in FASTA file
- name: required (string)
First word of FASTA header
- set: required (integer)
Not used yet, currently 0.
Example:
{ "id" : 0, "name" : "TEST", "set" : 0 } - id: required (integer)
- hasNext: required (boolean)
Does a next page exist
Example:
{
"lookup" :
[{
"id" : 0,
"name" : "TEST",
"set" : 0
}],
"hasNext" : false
}