Programmatic access to FAIR-TPs compound and transformation data.
Search compounds, read full compound records, follow the transformations recorded for a compound, find the shortest pathway between two compounds and run SMARTS substructure searches. Every endpoint is a plain GET request that returns JSON or XML.
All endpoints share one base URL. No account or API key is needed.
Base URL
https://fairtps.lcsb.uni.lu/api/v1Try a compound search. Open the URL in a browser or run the same request with curl.
https://fairtps.lcsb.uni.lu/api/v1/compounds?q=atrazinecurl "https://fairtps.lcsb.uni.lu/api/v1/compounds?q=atrazine"count is the number of matches across all pages. Use the inchikey of a result to fetch its full record.
{
"meta": {
"api_version": "v1",
"count": 17,
"page": 1,
"page_size": 20,
"total_pages": 1
},
"data": [
{
"inchikey": "MXWJVTOOROXGIU-UHFFFAOYSA-N",
"name": "Atrazine",
"title": "Atrazine",
"iupac_name": "6-chloro-4-N-ethyl-2-N-propan-2-yl-1,3,5-triazine-2,4-diamine",
"molecular_formula": "C8H14ClN5",
"pubchem_cid": "2256",
"mass": 215.0937732,
"xlogp": 2.6
}
]
}Each task maps to a single endpoint.
Search by name, PubChem title, IUPAC name or synonym.
/Get the full record for one compound, with synonyms, structures and masses.
/List the reactions in which a compound is the substrate or the product.
/Find the shortest chain of reactions that links one compound to another.
/Find every compound whose structure contains a SMARTS pattern.
/Search with up to 12 SMARTS patterns in a single request.
/The API has seven endpoints. All of them are read only and use GET. Open an example response to see the fields it returns.
GET/
Returns the API version and the response formats the service supports. It is a quick way to check that the API is reachable.
None.
https://fairtps.lcsb.uni.lu/api/v1/meta{
"api_version": "v1",
"service": "FAIR-TPs Public API",
"supported_formats": [
"application/json",
"application/xml"
],
"documentation": "/api/v1/docs"
}GET/
Searches compound names, PubChem titles, IUPAC names and synonyms, ignoring letter case. Each compound appears once and is returned as a summary.
Summaries leave out synonyms and structures. Fetch a compound by its inchikey for the full record.
qOptionalatrazinepageOptional1Example 2page_sizeOptional20Example 50https://fairtps.lcsb.uni.lu/api/v1/compounds?q=atrazine{
"meta": {
"api_version": "v1",
"count": 17,
"page": 1,
"page_size": 20,
"total_pages": 1
},
"data": [
{
"inchikey": "MXWJVTOOROXGIU-UHFFFAOYSA-N",
"name": "Atrazine",
"title": "Atrazine",
"iupac_name": "6-chloro-4-N-ethyl-2-N-propan-2-yl-1,3,5-triazine-2,4-diamine",
"molecular_formula": "C8H14ClN5",
"pubchem_cid": "2256",
"mass": 215.0937732,
"xlogp": 2.6
}
]
}GET/
Returns the full record for one compound, including synonyms, SMILES, InChI, exact and monoisotopic mass, molecular weight and XLogP.
inchikeyRequiredMXWJVTOOROXGIU-UHFFFAOYSA-NPart of the pathhttps://fairtps.lcsb.uni.lu/api/v1/compounds/MXWJVTOOROXGIU-UHFFFAOYSA-N{
"inchikey": "MXWJVTOOROXGIU-UHFFFAOYSA-N",
"name": "Atrazine",
"title": "Atrazine",
"iupac_name": "6-chloro-4-N-ethyl-2-N-propan-2-yl-1,3,5-triazine-2,4-diamine",
"synonyms": [
"atrazine",
"1912-24-9",
"Gesaprim",
"Aatrex"
],
"molecular_formula": "C8H14ClN5",
"pubchem_cid": "2256",
"smiles": "CCNC1=NC(=NC(=N1)Cl)NC(C)C",
"canonical_smiles": "CCNC1=NC(=NC(=N1)Cl)NC(C)C",
"isomeric_smiles": "CCNC1=NC(=NC(=N1)Cl)NC(C)C",
"inchi": "InChI=1S/C8H14ClN5/c1-4-10-7-12-6(9)13-8(14-7)11-5(2)3/h5H,4H2,1-3H3,(H2,10,11,12,13,14)",
"exact_mass": 215.0937732,
"monoisotopic_mass": 215.0937732,
"molecular_weight": 215.68,
"xlogp": 2.6
}GET/
Lists the recorded transformation reactions that involve a compound. Each entry names the substrate and the product in the direction of the reaction, with biosystems, enzymes, the dataset reference and the change in mass and XLogP.
mass_diff and xlogp_diff are product minus substrate. A value of 0 is a measured result, while null means no value is available.
inchikeyRequiredMXWJVTOOROXGIU-UHFFFAOYSA-NPart of the pathdirectionOptionaloutgoing lists reactions where the compound is the substrate, incoming lists reactions where it is the product, and both lists all of them.Default bothExample outgoingdatasetOptionaldataset_reference exactly.biosystemOptionalHumanenzymeOptionalCYP3A4pageOptional1Example 2page_sizeOptional20Example 50https://fairtps.lcsb.uni.lu/api/v1/compounds/MXWJVTOOROXGIU-UHFFFAOYSA-N/connections?page_size=1{
"meta": {
"api_version": "v1",
"count": 126,
"page": 1,
"page_size": 1,
"total_pages": 126
},
"data": [
{
"direction": "outgoing",
"substrate": {
"inchikey": "MXWJVTOOROXGIU-UHFFFAOYSA-N",
"name": "Atrazine",
"molecular_formula": "C8H14ClN5",
"pubchem_cid": "2256"
},
"product": {
"inchikey": "DFWFIQKMSFGDCQ-UHFFFAOYSA-N",
"name": "Deethylatrazine",
"molecular_formula": "C6H10ClN5",
"pubchem_cid": "22563"
},
"transformation": "Environmental Transformation",
"biosystems": [],
"enzymes": [],
"dataset_reference": "Kiefer, K.; Müller, A.; Singer, H.; Hollender, J. S60 | SWISSPEST19 | Swiss Pesticides and Metabolites from Kiefer et al. 2019. Zenodo. DOI: 10.5281/zenodo.3544760.",
"evidence": null,
"evidence_doi": null,
"mass_diff": -28.031300199999976,
"xlogp_diff": -1.1
}
]
}GET/
Finds the shortest chain of transformation reactions from one compound to another. Both compounds are identified by InChIKey.
When no forward chain exists, the reverse direction is searched and traversal says which one answered. If nothing connects the two compounds, the response is still 200 with found set to false. Up to 25 equally short pathways are returned.
sourceRequiredMXWJVTOOROXGIU-UHFFFAOYSA-NtargetRequiredsource.Example DFWFIQKMSFGDCQ-UHFFFAOYSA-Nmax_depthOptional20Example 3https://fairtps.lcsb.uni.lu/api/v1/pathways/shortest?source=MXWJVTOOROXGIU-UHFFFAOYSA-N&target=DFWFIQKMSFGDCQ-UHFFFAOYSA-N&max_depth=1{
"source": "MXWJVTOOROXGIU-UHFFFAOYSA-N",
"target": "DFWFIQKMSFGDCQ-UHFFFAOYSA-N",
"max_depth": 1,
"found": true,
"traversal": "forward",
"path_length": 1,
"pathway_count": 1,
"pathways": [
{
"length": 1,
"nodes": [
{
"position": 0,
"inchikey": "MXWJVTOOROXGIU-UHFFFAOYSA-N",
"name": "Atrazine",
"molecular_formula": "C8H14ClN5",
"pubchem_cid": "2256"
},
{
"position": 1,
"inchikey": "DFWFIQKMSFGDCQ-UHFFFAOYSA-N",
"name": "Deethylatrazine",
"molecular_formula": "C6H10ClN5",
"pubchem_cid": "22563"
}
],
"steps": [
{
"step": 1,
"substrate": {
"inchikey": "MXWJVTOOROXGIU-UHFFFAOYSA-N",
"name": null,
"molecular_formula": null,
"pubchem_cid": "2256"
},
"product": {
"inchikey": "DFWFIQKMSFGDCQ-UHFFFAOYSA-N",
"name": null,
"molecular_formula": null,
"pubchem_cid": "22563"
},
"transformation": "Dealkylation",
"biosystems": [
"Rice"
],
"enzymes": [],
"dataset_reference": null,
"evidence": null,
"evidence_doi": null,
"mass_diff": -28.031300199999976,
"xlogp_diff": -1.1
}
]
}
]
}GET/
Finds compounds whose structure contains a SMARTS pattern. Matching uses RDKit, and every candidate is checked before results are paged, so count is complete.
A valid pattern that matches nothing returns 200 with a count of 0. A pattern RDKit cannot parse returns 422. URL encode the pattern when you build the request.
smartsRequiredc1ncncn1datasetOptionalbiosystemOptionalpageOptional1Example 2page_sizeOptional20Example 50https://fairtps.lcsb.uni.lu/api/v1/search/substructure?smarts=c1ncncn1&page_size=1{
"meta": {
"api_version": "v1",
"count": 170,
"page": 1,
"page_size": 1,
"total_pages": 170
},
"data": [
{
"inchikey": "UUVWYPNAQBNQJQ-UHFFFAOYSA-N",
"name": "Altretamine",
"title": "Altretamine",
"iupac_name": "2-N,2-N,4-N,4-N,6-N,6-N-hexamethyl-1,3,5-triazine-2,4,6-triamine",
"molecular_formula": "C9H18N6",
"pubchem_cid": "2123",
"mass": 210.1592946,
"xlogp": 2.7
}
]
}GET/
Searches with several SMARTS patterns at once and returns compounds that match any of them, ranked by how many of the patterns each compound matches.
Repeat the smarts parameter once per pattern. If any pattern is invalid, the whole request returns 422, so a partial result is never mistaken for a complete one.
smartsRequiredc1ncncn1Can be repeateddatasetOptionalbiosystemOptionalpageOptional1Example 2page_sizeOptional20Example 50https://fairtps.lcsb.uni.lu/api/v1/search/substructure/batch?smarts=c1ncncn1&smarts=C%28%3DO%29O&page_size=1{
"meta": {
"api_version": "v1",
"count": 3745,
"page": 1,
"page_size": 1,
"total_pages": 3745
},
"data": [
{
"inchikey": "GOJNKIKCITVQDE-UHFFFAOYSA-N",
"name": "Atrazine-GSH-conjugate",
"title": "Atrazine-GSH-conjugate",
"iupac_name": "2-[3-[[4-(ethylamino)-6-(propan-2-ylamino)-1,3,5-triazin-2-yl]sulfanyl]propanoylamino]acetic acid",
"molecular_formula": "C13H22N6O3S",
"pubchem_cid": "177546081",
"mass": 342.14740976,
"xlogp": 1.5
}
]
}Responses are JSON by default. Endpoints that return lists share one envelope: a meta object with pagination details and a data array.
meta.countmeta.pagemeta.page_sizemeta.total_pagesFields without a value are returned as null rather than left out, and pubchem_cid is a string so identifiers are never altered by number parsing.
The same data is available as XML. Send Accept: application/xml and every list uses named elements.
curl -H "Accept: application/xml" "https://fairtps.lcsb.uni.lu/api/v1/meta"Errors are returned as problem documents (RFC 9457) in the format you asked for. Branch on the code field, which stays stable, rather than on the readable title or detail.
The compound or the path does not exist.
not_found
The Accept header asks for a format the API does not provide. Use JSON or XML.
not_acceptable
The request URL is too long, usually because of long SMARTS patterns. Send fewer or shorter patterns.
uri_too_long
The request was understood, but a parameter is missing or invalid. For most validation errors the errors list names the parameter.
validation_errortoo_many_patterns
Too many requests arrived in a short period. Wait and retry later.
rate_limited
The service cannot complete the request right now. If a search ran out of time, narrow it instead of repeating it unchanged.
temporarily_unavailablescientific_query_timeoutcapacity_exhaustedresource_control_unavailable
{
"type": "/api/v1/problems/validation_error",
"title": "Validation error",
"status": 422,
"detail": "One or more request parameters were invalid.",
"code": "validation_error",
"instance": "/api/v1/compounds",
"errors": [
{
"field": "query.page_size",
"code": "less_than_equal",
"message": "Input should be less than or equal to 100"
}
]
}Three short tasks that cover most first integrations.
Search for atrazine and note the inchikey of the result you want.
https://fairtps.lcsb.uni.lu/api/v1/compounds?q=atrazineRequest the full record with that key.
https://fairtps.lcsb.uni.lu/api/v1/compounds/MXWJVTOOROXGIU-UHFFFAOYSA-NAsk for the reactions in which atrazine is the substrate.
https://fairtps.lcsb.uni.lu/api/v1/compounds/MXWJVTOOROXGIU-UHFFFAOYSA-N/connections?direction=outgoingEach product is a transformation product. Switch to direction=incoming to see which compounds form atrazine instead.
Find compounds that contain a 1,3,5-triazine ring by passing the pattern in smarts.
https://fairtps.lcsb.uni.lu/api/v1/search/substructure?smarts=c1ncncn1To look for several substructures at once, repeat smarts and call the batch endpoint.
https://fairtps.lcsb.uni.lu/api/v1/search/substructure/batch?smarts=c1ncncn1&smarts=C%28%3DO%29OThe same lookup in three languages: search by name, then fetch the full record of the first result.
curl "https://fairtps.lcsb.uni.lu/api/v1/compounds?q=atrazine&page_size=5"
curl "https://fairtps.lcsb.uni.lu/api/v1/compounds/MXWJVTOOROXGIU-UHFFFAOYSA-N"
# SMARTS patterns contain characters that must be URL encoded
curl -G "https://fairtps.lcsb.uni.lu/api/v1/search/substructure" \
--data-urlencode "smarts=c1ncncn1" \
--data-urlencode "page_size=5"import requests
BASE_URL = "https://fairtps.lcsb.uni.lu/api/v1"
search = requests.get(
f"{BASE_URL}/compounds",
params={"q": "atrazine", "page_size": 5},
timeout=30,
)
search.raise_for_status()
results = search.json()["data"]
if results:
inchikey = results[0]["inchikey"]
detail = requests.get(f"{BASE_URL}/compounds/{inchikey}", timeout=30)
detail.raise_for_status()
compound = detail.json()
print(compound["name"], compound["molecular_formula"])// Node.js 18 or later, run as an ES module
const BASE_URL = "https://fairtps.lcsb.uni.lu/api/v1";
const search = await fetch(`${BASE_URL}/compounds?q=atrazine&page_size=5`);
if (!search.ok) throw new Error(`Search failed with status ${search.status}`);
const { data } = await search.json();
if (data.length > 0) {
const detail = await fetch(`${BASE_URL}/compounds/${data[0].inchikey}`);
const compound = await detail.json();
console.log(compound.name, compound.molecular_formula);
}The version is part of every route, so fields in v1 keep their names and meaning. New fields may be added, and a breaking change would be released as v2.
The API applies request and resource controls so the service stays available for everyone. Substructure, batch and pathway searches do the most work, so avoid repeating identical requests and cache results that rarely change.
Successful responses carry an ETag. Send it back in an If-None-Match header and the API answers 304 Not Modified without a body when nothing has changed. After a 429, wait before retrying and honour Retry-After when it is present.