API Reference¶
Attention
- reference docs for the bio.tools API
- to make suggestions about these guidelines please add comments via GitHub
- if you find a bug, have any questions or suggestions, please get in touch with us.
- see also the API Usage Guide
The bio.tools Web API provides an easy way to access the bio.tools database.
List tools¶
List and search through all the available tools. Can sort, filter, and search the results.
HTTP GET
https://bio.tools/api/tool/
https://bio.tools/api/t/
Endpoint parameters¶
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
page | No | Integer | 1 | Result page number |
format | No | String(json, api) | json | Response media type |
q | No | String | Query term, used for searching, matches all attributes | |
sort | No | String(lastUpdate, additionDate, name, affiliation, score) | lastUpdate | Sorts the results by choosen value (score only available when there is a query) |
ord | No | String(desc, asc) | desc | Orders the results by either Ascending or Descending order |
<attribute> | No | String | Filter by <attribute>. List of supported attributes below. |
Filtering¶
To filter the results by attribute name, the attribute name has to be added as a parameter to the URL, with the value being the desired search term, e.g. ?name=signalp
Attributes¶
These are the attributes supported by bio.tools:
Parameter | Search behaviour |
---|---|
biotoolsID | Search for bio.tools tool ID (usually quoted - to get exact match) |
name | Search for tool name (quoted as needed) |
homepage | Exact search for tool homepage URL (must be quoted) |
description | Search over tool description (quoted as needed) |
version | Exact search for tool version (must be quoted) |
topic | Search for EDAM Topic (term) (quoted as needed) |
topicID | Exact search for EDAM Topic (URI): must be quoted |
function | Fuzzy search over function (input, operation, output, note and command) |
operation | Fuzzy search for EDAM Operation (term) (quoted as needed) |
operationID | Exact search for EDAM Operation (ID) (must be quoted) |
dataType | Fuzzy search over input and output for EDAM Data (term) (quoted as needed) |
dataTypeID | Exact search over input and output for EDAM Data (ID) (must be quoted) |
dataFormat | Fuzzy search over input and output for EDAM Format (term) (quoted as needed) |
dataFormatID | Exact search over input and output for EDAM Format (ID) (must be quoted) |
input | Fuzzy search over input for EDAM Data and Format (term) (quoted as needed) |
inputID | Exact search over input for EDAM Data and Format (ID) (must be quoted) |
inputDataType | Fuzzy search over input for EDAM Data (term) (quoted as needed) |
inputDataTypeID | Exact search over input for EDAM Data (ID) (must be quoted) |
inputDataFormat | Fuzzy search over input for EDAM Format (term) (quoted as needed) |
inputDataFormatID | Exact search over input for EDAM Format (ID) (must be quoted) |
output | Fuzzy search over output for EDAM Data and Format (term) (quoted as needed) |
outputID | Exact search over output for EDAM Data and Format (ID) (must be quoted) |
outputDataType | Fuzzy search over output for EDAM Data (term) (quoted as needed) |
outputDataTypeID | Exact search over output for EDAM Data (ID) (must be quoted) |
outputDataFormat | Fuzzy search over output for EDAM Format (term) (quoted as needed) |
outputDataFormatID | Exact search over output for EDAM Format (ID) (must be quoted) |
toolType | Exact search for tool type |
collectionID | Exact search for tool collection (normally quoted) |
maturity | Exact search for tool maturity |
operatingSystem | Exact search for tool operating system |
language | Exact search for programming language |
cost | Exact search for cost |
license | Exact search for software or data usage license (quoted as needed) |
accessibility | Exact search for tool accessibility |
credit | Fuzzy search over credit (name, email, URL, ORCID iD, type of entity, type of role and note) |
creditName | Exact search for name of credited entity |
creditTypeRole | Exact search for role of credited entity |
creditTypeEntity | Exact search for type of credited entity |
creditOrcidID | Exact search for ORCID iD of credited entity (must be quoted) |
publication | Fuzzy search over publication (DOI, PMID, PMCID, publication type and tool version) (quoted as needed) |
publicationID | Exact search for publication ID (DOI, PMID or PMCID) (must be quoted) |
publicationType | Exact search for publication type |
publicationVersion | Exact search for tool version associated with a publication (must be quoted) |
link | Fuzzy search over general link (URL, type and note) (quote as needed) |
linkType | Exact search for type of information found at a link |
documentation | Fuzzy search over documentation link (URL, type and note) (quote as needed) |
documentationType | Exact search for type of documentation |
download | Fuzzy search over download link (URL, type, version and note) (quote as needed) |
downloadType | Exact search for type of download |
downloadVersion | Exact search for tool version associated with a download (must be quoted) |
otherID | Fuzzy search over alternate tool IDs (ID value, type of ID and version) |
otherIDValue | Exact search for value of alternate tool ID (must be quoted) |
otherIDType | Exact search for type of alternate tool ID |
otherIDVersion | Exact search for tool version associated with an alternate ID (must be quoted) |
Important
- Values of the following parameters must be given in quotes to get sensible (or any) results:
homepage
version
topicID
operationID
dataTypeID
dataFormatID
inputID
inputDataTypeID
inputDataFormatID
outputID
outputDataTypeID
outputDataFormatID
creditOrcidID
publicationID
publicationVersion
downloadVersion
otherIDValue
otherIDVersion
- e.g.
- https://bio.tools/api/tool?topicID=”topic_3510”
- Values of other parameters can be quoted or unquoted:
- Unquoted values invoke a fuzzy word search: it will search for fuzzy matches of words in the search phrase, to the target field
- Quoted values invoke an exact phrase search; it will search for an exact match of the full-length of the search phrase, to the target field (matches to target substrings are allowed)
- e.g.
- https://bio.tools/api/tool?biotoolsID=”blast” returns the tool with biotoolsID of “blast” (the “canonical” blast)
- https://bio.tools/api/tool?biotoolsID=blast returns all tools with “blast” in their biotoolsID (all blast flavours)
Caution
The parameters are (currently) case-sensitive, e.g. you must use &biotoolsID=
and not &biotoolsid
Example¶
curl -X GET "https://bio.tools/api/tool/?page=1&format=json&name=signalp&sort=name&ord=asc&q=protein-signal-peptide-detection"
Note
- An EDAM concept ID can be specified as a concept URI or ID:
- Concept URI e.g.
http://edamontology.org/operation_2403
- Concept ID e.g.
operation_2403
- Concept URI e.g.
- In future we may add support for:
- Concept CURIE e.g.
EDAM:operation_2403
- Numerical ID e.g.
2403
- Concept CURIE e.g.
Note: URIs and IDs must be quoted, e.g. &topicID="operation_2403"
Response data¶
Key Name | Description | Example |
---|---|---|
count | The total tool count results for your query | 2313 |
previous | Link to the previous page | ?page=4 |
next | Link to the next page | ?page=6 |
list | An array with multiple tools and their relative information | ARRAY |
Tool detail¶
Obtain information about a single tool.
HTTP GET
https://bio.tools/api/tool/:id/
https://bio.tools/api/t/:id/
https://bio.tools/api/:id/
Endpoint Parameters¶
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
id | Yes | String | biotoolsID | |
format | No | String(json, xml, api) | json | Response media type |
Example¶
curl -X GET "https://bio.tools/api/tool/signalp/?format=json"
Caution
bio.tools supports upload/download of data in XML format compliant to biotoolsScheme v3.0.0. If you want to download in XML format you should use these endpoints (see Tool detail below):
https://bio.tools/api/tool/id/
https://bio.tools/api/t/id/
https://bio.tools/api/id/
e.g. https://bio.tools/api/tool/signalp
Were you to try to get XML format returned from a search over bio.tools
e.g. https://bio.tools/api/tool?toolid=signalp&format=xml
currently you’d get garbled / invalid XML (don’t use it!) - we’re looking at a fix.
Register a tool¶
Register a new tool.
Important
This method requires the user to be authenticated. Learn how to Log in / obtain token.
HTTP POST
https://bio.tools/api/tool/
https://bio.tools/api/t/
Endpoint Parameters¶
Parameter | Required | Type | Description |
---|---|---|---|
data | Yes | Tool | Tool you wish to register. See an example tool. |
Note
It is possible to specify editing permissions for tools. Learn how to manage Editing permissions.
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | Media type |
Authorization | Yes | String(‘Token <authorization token>’) | Authorization header. Learn how to Log in / obtain token. |
Example¶
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Token 028595d682541e7e1a5dcf2306eccb720dadafd7" \
-d '<resource>' "https://bio.tools/api/tool/"
Validate registering a tool¶
Test registering a tool without it actually being saved into the database.
Important
This method requires the user to be authenticated. Learn how to Log in / obtain token.
HTTP POST
https://bio.tools/api/tool/validate/
https://bio.tools/api/t/validate/
Endpoint Parameters¶
Parameter | Required | Type | Description |
---|---|---|---|
data | Yes | Tool | Tool you wish to validate. See an example tool. |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | Media type |
Authorization | Yes | String(‘Token <authorization token>’) | Authorization header. Learn how to Log in / obtain token. |
Example¶
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Token 028595d682541e7e1a5dcf2306eccb720dadafd7" \
-d '<resource>' "https://bio.tools/api/tool/validate/"
Update a tool¶
Update a tool description.
Important
This method requires the user to be authenticated. Learn how to Log in / obtain token.
HTTP PUT
https://bio.tools/api/tool/:id/
https://bio.tools/api/t/:id/
https://bio.tools/api/:id/
Endpoint Parameters¶
Parameter | Required | Type | Description |
---|---|---|---|
id | Yes | String | biotoolsID |
data | Yes | Tool | Description with which you wish to update the tool See an example tool. |
Note
It is possible to specify editing permissions for tools. Learn how to manage Editing permissions.
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | Media type |
Authorization | Yes | String(‘Token <authorization token>’) | Authorization header. Learn how to Log in / obtain token. |
Example¶
curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: Token 028595d682541e7e1a5dcf2306eccb720dadafd7" \
-d '<resource>' "https://bio.tools/api/tool/SignalP"
Validate updating a tool¶
Test updating a tool without it actually being saved into the database.
Important
This method requires the user to be authenticated. Learn how to Log in / obtain token.
HTTP PUT
https://bio.tools/api/tool/:id/validate/
https://bio.tools/api/t/:id/validate/
https://bio.tools/api/:id/validate/
Endpoint Parameters¶
Parameter | Required | Type | Description |
---|---|---|---|
id | Yes | String | biotoolsID |
data | Yes | Tool Description with which you wish to update the tool for validation See an example tool. |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | Media type |
Authorization | Yes | String(‘Token <authorization token>’) | Authorization header. Learn how to Log in / obtain token. |
Example¶
curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: Token 028595d682541e7e1a5dcf2306eccb720dadafd7" \
-d '<resource>' "https://bio.tools/api/tool/SignalP/validate/"
Editing permissions¶
Manage editing permissions for the registered tools.
There are currently three types of editing permissions supported by the system:
Private¶
A private tool can only be edited by the creator of the tool. This is the default option. In order to set this kind of permission, add the following info into the tool data:
"editPermission": {
"type": "private"
}
Public¶
Public tool can be modified by any user registered in the system. In order to set this kind of permission, add the following info into the tool data:
"editPermission": {
"type": "public"
}
Group¶
Specify a list of users in the system that can edit the tool. In order to set this kind of permission, add the following info into the tool data:
"editPermission": {
"type": "private",
"authors": [
"registered_user_1", "registered_user_2"
]
}
Delete a tool¶
Removes a tool from the registry.
Important
This method requires the user to be authenticated. Learn how to Log in / obtain token.
HTTP DELETE
https://bio.tools/api/tool/:id/
https://bio.tools/api/t/:id/
https://bio.tools/api/:id/
Endpoint Parameters¶
Parameter | Required | Type | Description |
---|---|---|---|
id | Yes | String | biotoolsID |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Authorization | Yes | String(‘Token <authorization token>’) | Authorization header. Learn how to Log in / obtain token. |
Example¶
curl -X DELETE \
-H "Authorization: Token 028595d682541e7e1a5dcf2306eccb720dadafd7" \
"https://bio.tools/api/tool/SignalP"
List used terms¶
Obtain a list of terms registered with tools for some attributes, e.g. a list of names of all tools.
HTTP GET
https://bio.tools/api/used-terms/:attribute
Endpoint Parameters¶
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
attribute | Yes | String(name, topic, functionName, input, output, credits, all) | Attribute for which a list of used terms will be returned | |
format | No | String(json, xml, api) | json | Response media type |
Example¶
curl -X GET "https://bio.tools/api/used-terms/name/?format=json"
Response data¶
Key Name | Description |
---|---|
data | A list of used terms |
Create a user account¶
Creates a user account and emails a verification email.
HTTP POST
https://bio.tools/api/rest-auth/registration/
POST data¶
Key Name | Required | Type | Description | Example |
---|---|---|---|---|
username | Yes | String | Account username | username |
password1 | Yes | String | Password | password |
password2 | Yes | String | Repeated password | password |
Yes | String | Account email. The verification email will be sent to this address | example@example.org |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | POST data media type |
Example¶
curl -X POST -H "Content-Type: application/json" \
-d '{"username":"username", "password1":"password", \
"password2":"password", "email":"example@example.org"}' \
"https://bio.tools/api/rest-auth/registration/"
Verify a user account¶
Verifies a user account based on the emailed verification key.
HTTP POST
https://bio.tools/api/rest-auth/registration/verify-email/
POST data¶
Key Name | Required | Type | Description | Example |
---|---|---|---|---|
key | Yes | String | Verification key from account creation email | ndwowtbpmlk5zxdxfrwgu2822xynjidhizhwosycve7hro1of156hjwdsf1f6gbn |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | POST data media type |
Example¶
curl -X POST -H "Content-Type: application/json" \
-d '{"key":"ndwowtbpmlk5zxdxfrwgu2822xynjidhizhwosycve7hro1of156hjwdsf1f6gbn"}' \
"https://bio.tools/api/rest-auth/registration/verify-email/"
Log in / obtain token¶
Logs the user in and returns an authentication token.
HTTP POST
https://bio.tools/api/rest-auth/login/
POST data¶
Key Name | Required | Type | Description | Example |
---|---|---|---|---|
username | Yes | String | Account username | username |
password | Yes | String | Password | password |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | POST data media type |
Example¶
curl -X POST -H "Content-Type: application/json" \
-d '{"username":"username","password":"password"}' \
"https://bio.tools/api/rest-auth/login/"
Response data¶
Key Name | Description |
---|---|
key | Authentication token |
Get user information¶
Return information about the logged in user account, including a list of registered tool (name, id, version, additionDate, lastUpdate)
Important
This method requires the user to be authenticated. Learn how to Log in / obtain token.
HTTP GET
https://bio.tools/api/rest-auth/user/
Endpoint Parameters¶
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
format | No | String(json, xml, api) | json | Response media type |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Authorization | Yes | String(‘Token <authorization token>’) | Authorization header. Learn how to Log in / obtain token. |
Example¶
curl -X GET \
-H "Authorization: Token 028595d682541e7e1a5dcf2306eccb720dadafd7" \
"https://bio.tools/api/rest-auth/user/?format=json"
Response data¶
Key Name | Description |
---|---|
username | Account username |
Account email | |
resources | List of registered tools (limited to name, id, version, additionDate, lastUpdate) |
Log out¶
Log out of the system.
Important
This method requires the user to be authenticated. Learn how to Log in / obtain token.
HTTP POST
https://bio.tools/api/rest-auth/logout/
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Authorization | Yes | String(‘Token <authorization token>’) | Authorization header. Learn how to Log in / obtain token. |
Example¶
curl -X POST
-H "Authorization: Token 028595d682541e7e1a5dcf2306eccb720dadafd7" \
"https://bio.tools/api/rest-auth/logout/"
Reset user password¶
Send a password reset email.
HTTP POST
https://bio.tools/api/rest-auth/password/reset/
POST data¶
Key Name | Required | Type | Description | Example |
---|---|---|---|---|
Yes | String | Account email | example@example.org |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | POST data media type |
Example¶
curl -X POST -H "Content-Type: application/json" \
-d '{"email":"example@example.org"}' \
"https://bio.tools/api/rest-auth/password/reset/"
Confirm password reset¶
Confirm a password reset using uid and token from a password reset email.
HTTP POST
https://bio.tools/api/rest-auth/password/reset/confirm/
POST data¶
Key Name | Required | Type | Description | Example |
---|---|---|---|---|
uid | Yes | String | UID from password reset email | MQ |
token | Yes | String | Token from password reset email | 4ct-67e90a1ab4f22fbb9b9f |
password1 | Yes | String | New password | new_password |
password2 | Yes | String | New password repeated | new_password |
Headers¶
Parameter | Required | Allowed values | Description |
---|---|---|---|
Content-Type | Yes | String(application/json, application/xml) | POST data media type |
Example¶
curl -X POST -H "Content-Type: application/json" \
-d '{"uid":"MQ", "token":"4ct-67e90a1ab4f22fbb9b9f", \
"password1":"new_password", "password2":"new_password"}' \
"https://bio.tools/api/rest-auth/password/reset/confirm/"