REST API — Technical guide and examples

Methods exposed to the REST API to query RetroRules are described here below:

► Rules from EC Number

Returns the list of reaction rules from a given EC number. It returns the rule SMARTS and its diameter, direction, unique identifier, penalty score, if it expresses stereochemistry and all EC numbers.

URL:
/api/v0.7/ecnumber/?input=:EC Number
/api/v0.7/ecnumber/?input=:EC Number&minDiameter=:Minimal Diameter
Method:
GET
URL Params:
Required:
  • input=[string]
Optional:
  • minDiameter=[integer]
Success Response:
Code: 200
Content: {
  • diameter: 16,
  • direction: -1,
  • ec_numbers: ["1.1.1.272","1.1.1.338"]
  • id: 1145694269360631,
  • score: 0.6020599913279624,
  • isStereo: 1,
  • smarts_string: "([#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](-[#6:9](-[#1:10])(-[#16:12](=[#8:13])(-[#8:15]-[#1:16])=[#8:14])-[#1:11])(-[#8:7]-[#1:8])-[#1:6])>>([#1&+:8].[#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](=[#8:7])-[#6:9](-[#1:11])(-[#1:10])-[#16:12](=[#8:14])(=[#8:13])-[#8:15]-[#1:16].[#1]-[#7]=[#6](-[#8]-[#1])-[#6]1=[#6](-[#1])-[#7](-[#6](-[#1])=[#6](-[#1])-[#6]-1(-[#1])-[#1:6])-[#6]1(-[#1])-[#8]-[#6](-[#1])(-[#6](-[#1])(-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#6](-[#1])(-[#1])-[#6]2(-[#6](-[#6](-[#1])(-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#1])-[#6](-[#8]-2)(-[#1])-[#7]2:[#6]3:[#7]:[#6](:[#7]:[#6](-[#7](-[#1])-[#1]):[#6]:3:[#7]:[#6]:2-[#1])-[#1])(-[#1])-[#8]-[#1])-[#1])-[#6](-[#1])(-[#8]-[#1])-[#6]-1(-[#1])-[#8]-[#1])"}, ...]
Error Response:
Code: 400
Content: "{ 'message': 'Input minDiameter must be integer from -1 to 16' }"
Code: 400
Content: "{ 'message': 'EC number is too short or too long' }"
Code: 403
Content: "{ 'message': 'Do no yet handle 5.1 and 5.2 EC numbers' }"
Code: 404
Content: "{ 'message': 'Request INPUT is not present in the database' }"
Sample Call:
curl -i "https://retrorules.org/api/v0.7/ecnumber/?input=1.1.1.1&minDiameter=6"
Notes: Default diameter if not specified is 12. 'id' is the unique identifier. 'score' is penalty score where the smaller the better. 'direction' is -1 for reverse and 1 for forward. 'isStereo' determines if a given rule contains stochiometric descriptions where 1 is True and 0 is False.

► Rules from Substrate

Returns the list of reactions rules associated with a given substrate name. It returns the rule SMARTS and its diameter, direction, unique identifier, penalty score and all EC numbers.

URL
/api/v0.7/substrate/?input=:Substrate Name
/api/v0.7/substrate/?input=:Substrate Name&minDiameter=:Minimal Diameter
Method:
GET
URL Params
Required:
  • input=[string]
Optional:
  • minDiameter=[integer]
Success Response:
Code: 200
Content: {
  • diameter: 16,
  • direction: -1,
  • ec_numbers: ["1.1.1.272", "1.1.1.338"]
  • id: 1145694269360631,
  • score: 0.6020599913279624,
  • isStereo: 1,
  • smarts_string: "([#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](-[#6:9](-[#1:10])(-[#16:12](=[#8:13])(-[#8:15]-[#1:16])=[#8:14])-[#1:11])(-[#8:7]-[#1:8])-[#1:6])>>([#1&+:8].[#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](=[#8:7])-[#6:9](-[#1:11])(-[#1:10])-[#16:12](=[#8:14])(=[#8:13])-[#8:15]-[#1:16].[#1]-[#7]=[#6](-[#8]-[#1])-[#6]1=[#6](-[#1])-[#7](-[#6](-[#1])=[#6](-[#1])-[#6]-1(-[#1])-[#1:6])-[#6]1(-[#1])-[#8]-[#6](-[#1])(-[#6](-[#1])(-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#6](-[#1])(-[#1])-[#6]2(-[#6](-[#6](-[#1])(-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#1])-[#6](-[#8]-2)(-[#1])-[#7]2:[#6]3:[#7]:[#6](:[#7]:[#6](-[#7](-[#1])-[#1]):[#6]:3:[#7]:[#6]:2-[#1])-[#1])(-[#1])-[#8]-[#1])-[#1])-[#6](-[#1])(-[#8]-[#1])-[#6]-1(-[#1])-[#8]-[#1])"}, ...]
Error Response:
Code: 400
Content: { 'message': 'Input minDiameter must be integer from -1 to 16' }
Code: 404
Content: { 'message': 'Request INPUT is not present in the database' }
Sample Call:
curl -i "https://retrorules.org/api/v0.7/substrate/?input=pyruvate&minDiameter=6"
Notes: Default diameter if not specified is 12. 'id' is the unique identifier. 'score' is penalty score where the smaller the better. 'direction' is -1 for reverse and 1 for forward. 'isStereo' determines if a given rule contains stochiometric descriptions where 1 is True and 0 is False.

► Rules from Reaction ID

Returns the list of reaction rules from a given reation ID from one of the following databases: ['mnxr' or 'mnx', 'bigg', 'kegg', 'metacyc', 'reactome', 'rhea', 'sabiork', 'seed']. It returns the rule SMARTS and its diameter, direction, unique identifier, penalty score, if it expresses stereochemistry and all EC numbers (called here repo to avoid confusion with out own database).

URL
/api/v0.7/repo/?input=:Reaction ID&repo=:Database Name
/api/v0.7/repo/?input=:ReactionID&repo=:Database Name&minDiameter=:Minimal Diameter
Method:
GET
URL Params
Required:
  • input=[string]
  • repo=[string]
Optional:
  • minDiameter=[integer]
Success Response:
Code: 200
Content: {
  • diameter: 16,
  • direction: -1,
  • ec_numbers: ["1.1.1.272", "1.1.1.338"]
  • id: 1145694269360631,
  • score: 0.6020599913279624,
  • isStereo: 1,
  • smarts_string: "([#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](-[#6:9](-[#1:10])(-[#16:12](=[#8:13])(-[#8:15]-[#1:16])=[#8:14])-[#1:11])(-[#8:7]-[#1:8])-[#1:6])>>([#1&+:8].[#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](=[#8:7])-[#6:9](-[#1:11])(-[#1:10])-[#16:12](=[#8:14])(=[#8:13])-[#8:15]-[#1:16].[#1]-[#7]=[#6](-[#8]-[#1])-[#6]1=[#6](-[#1])-[#7](-[#6](-[#1])=[#6](-[#1])-[#6]-1(-[#1])-[#1:6])-[#6]1(-[#1])-[#8]-[#6](-[#1])(-[#6](-[#1])(-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#6](-[#1])(-[#1])-[#6]2(-[#6](-[#6](-[#1])(-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#1])-[#6](-[#8]-2)(-[#1])-[#7]2:[#6]3:[#7]:[#6](:[#7]:[#6](-[#7](-[#1])-[#1]):[#6]:3:[#7]:[#6]:2-[#1])-[#1])(-[#1])-[#8]-[#1])-[#1])-[#6](-[#1])(-[#8]-[#1])-[#6]-1(-[#1])-[#8]-[#1])"}, ...]
Error Response:
Code: 400
Content: { 'message': 'Input minDiameter must be integer from -1 to 16' }
Code: 400
Content: { 'message': 'The Request repo REPO is not valid' }
Code: 404
Content: { 'message': 'Request INPUT is not present in the database' }
Sample Call:
curl -i "https://retrorules.org/api/v0.7/reactionid/?input=MNXR104443&repo=mnxr"
Notes: Default diameter if not specified is 12. 'id' is the unique identifier. 'score' is penalty score where the smaller the better. 'direction' is -1 for reverse and 1 for forward. 'isStereo' determines if a given rule contains stochiometric descriptions where 1 is True and 0 is False.

► Rules from InChI

Returns the list of reaction rules that includes the rule SMARTS and its diameter, direction, unique identifier, penalty score, if it expresses stereochemistry and all EC numbers associated with it from a given InChI

URL
/api/v0.7/inchi/?input=:InChI
/api/v0.7/inchi/?input=:InChI&minDiameter=:Minimal Diameter
Method:
GET
URL Params
Required:
  • input=[string]
Optional:
  • minDiameter=[integer]
Success Response:
Code: 200
Content:
  • diameter: 16,
  • direction: -1,
  • ec_numbers: ["1.1.1.272", "1.1.1.338"]
  • id: 1145694269360631,
  • score: 0.6020599913279624,
  • isStereo: 1,
  • smarts_string: { "([#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](-[#6:9](-[#1:10])(-[#16:12](=[#8:13])(-[#8:15]-[#1:16])=[#8:14])-[#1:11])(-[#8:7]-[#1:8])-[#1:6])>>([#1&+:8].[#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](=[#8:7])-[#6:9](-[#1:11])(-[#1:10])-[#16:12](=[#8:14])(=[#8:13])-[#8:15]-[#1:16].[#1]-[#7]=[#6](-[#8]-[#1])-[#6]1=[#6](-[#1])-[#7](-[#6](-[#1])=[#6](-[#1])-[#6]-1(-[#1])-[#1:6])-[#6]1(-[#1])-[#8]-[#6](-[#1])(-[#6](-[#1])(-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#6](-[#1])(-[#1])-[#6]2(-[#6](-[#6](-[#1])(-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#1])-[#6](-[#8]-2)(-[#1])-[#7]2:[#6]3:[#7]:[#6](:[#7]:[#6](-[#7](-[#1])-[#1]):[#6]:3:[#7]:[#6]:2-[#1])-[#1])(-[#1])-[#8]-[#1])-[#1])-[#6](-[#1])(-[#8]-[#1])-[#6]-1(-[#1])-[#8]-[#1])"}, ...]
Error Response:
Code: 400
Content: { 'message': 'Input minDiameter must be integer from -1 to 16' }
Code: 404
Content: { 'message': 'Request INPUT is not present in the database' }
Sample Call:
curl -i "https://retrorules.org/api/v0.7/inchi/?input=InChI=1S/C4H4O5/c5-2(4(8)9)1-3(6)7/h1H2,(H,6,7)(H,8,9)/p-2"
Notes:Default diameter if not specified is 12. 'id' is the unique identifier. 'score' is penalty score where the smaller the better. 'direction' is -1 for reverse and 1 for forward. 'isStereo' determines if a given rule contains stochiometric descriptions where 1 is True and 0 is False.

► Rules from Repository

Returns the list of reaction rules that includes the rule SMARTS and its diameter, direction, unique identifier, penalty score, if it expresses stereochemistry and all EC numbers associated with it from a given database name including ['mnxr' or 'mnx', 'bigg', 'kegg', 'metacyc', 'reactome', 'rhea', 'sabiork', 'seed'].

URL
/api/v0.7/repo/?input=:DB Name
/api/v0.7/repo/?input=:DB Name&minDiameter=:Minimal Diameter
Method:
GET
URL Params
Required:
  • input=[string]
Optional:
  • minDiameter=[integer]
Success Response:
Code: 200
Content:
  • diameter: 16,
  • direction: -1,
  • ec_numbers: ["1.1.1.272", "1.1.1.338"],
  • id: 1145694269360631,
  • score: 0.6020599913279624,
  • isStereo: 1,
  • smarts_string: { "([#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](-[#6:9](-[#1:10])(-[#16:12](=[#8:13])(-[#8:15]-[#1:16])=[#8:14])-[#1:11])(-[#8:7]-[#1:8])-[#1:6])>>([#1&+:8].[#1:1]-[#8:2]-[#6:3](=[#8:4])-[#6:5](=[#8:7])-[#6:9](-[#1:11])(-[#1:10])-[#16:12](=[#8:14])(=[#8:13])-[#8:15]-[#1:16].[#1]-[#7]=[#6](-[#8]-[#1])-[#6]1=[#6](-[#1])-[#7](-[#6](-[#1])=[#6](-[#1])-[#6]-1(-[#1])-[#1:6])-[#6]1(-[#1])-[#8]-[#6](-[#1])(-[#6](-[#1])(-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#6](-[#1])(-[#1])-[#6]2(-[#6](-[#6](-[#1])(-[#8]-[#15](=[#8])(-[#8]-[#1])-[#8]-[#1])-[#6](-[#8]-2)(-[#1])-[#7]2:[#6]3:[#7]:[#6](:[#7]:[#6](-[#7](-[#1])-[#1]):[#6]:3:[#7]:[#6]:2-[#1])-[#1])(-[#1])-[#8]-[#1])-[#1])-[#6](-[#1])(-[#8]-[#1])-[#6]-1(-[#1])-[#8]-[#1])"}, ...]
Error Response:
Code: 400
Content: { 'message': 'Input minDiameter must be integer from -1 to 16' }
Code: 404
Content: { 'message': 'Request INPUT is not present in the database' }
Sample Call:
curl -i "https://retrorules.org/api/v0.7/repo/?input=kegg"
Notes:Default diameter if not specified is 12. 'id' is the unique identifier. 'score' is penalty score where the smaller the better. 'direction' is -1 for reverse and 1 for forward. 'isStereo' determines if a given rule contains stochiometric descriptions where 1 is True and 0 is False.

► Rules from SMARTS ID

Returns the list of reaction rules that includes the rule SMARTS and its diameter, direction, unique identifier, penalty score, if it expresses stereochemistry and all EC numbers associated with it from the ID of said reaction rule.

URL
/api/v0.7/smartsid/?input=:smarts ID&input=:smarts ID& etc...
/api/v0.7/smartsid/?input=:smarts ID&input=:smarts ID& etc...&minDiameter=:Minimal Diameter
Method:
GET
URL Params
Required:
  • input=[string]
Optional:
  • minDiameter=[integer]
Success Response:
Code: 200
Content: [[{
  • diameter: 14,
  • direction: 1,
  • ec_numbers: ["3.3.2.10"]
  • id: 2,
  • isStereo: 0,
  • score: 0,
  • smarts_string: "([#8&v2:1]1-[#6&v4:2](-[#6&v4:3]-1(-[#6&v4:4](-[#1&v1:5])(-[#1&v1:6])-[#1&v1:7])-[#6&v4:8](-[#1&v1:9])(-[#1&v1:10])-[#1&v1:11])(-[#1&v1:12])-[#1&v1:13])>>([#8&v2:1](-[#6&v4:3](-[#6&v4:2](-[#8&v2]-[#1&v1])(-[#1&v1:12])-[#1&v1:13])(-[#6&v4:4](-[#1&v1:5])(-[#1&v1:6])-[#1&v1:7])-[#6&v4:8](-[#1&v1:9])(-[#1&v1:10])-[#1&v1:11])-[#1&v1])",
  • },{,
  • diameter: 12,
  • direction: 1,
  • ec_numbers: ["3.3.2.10"]
  • id: 2,
  • isStereo: 0,
  • score: 0,
  • smarts_string: "([#8&v2:1]1-[#6&v4:2](-[#6&v4:3]-1(-[#6&v4:4](-[#1&v1:5])(-[#1&v1:6])-[#1&v1:7])-[#6&v4:8](-[#1&v1:9])(-[#1&v1:10])-[#1&v1:11])(-[#1&v1:12])-[#1&v1:13])>>([#8&v2:1](-[#6&v4:3](-[#6&v4:2](-[#8&v2]-[#1&v1])(-[#1&v1:12])-[#1&v1:13])(-[#6&v4:4](-[#1&v1:5])(-[#1&v1:6])-[#1&v1:7])-[#6&v4:8](-[#1&v1:9])(-[#1&v1:10])-[#1&v1:11])-[#1&v1])" ,
  • },{
  • diameter: 16,
  • direction: 1,
  • ec_numbers: ["3.3.2.10"]
  • id: 2,
  • isStereo: 0,
  • score: 0,
  • smarts_string: "([#8&v2:1]1-[#6&v4:2](-[#6&v4:3]-1(-[#6&v4:4](-[#1&v1:5])(-[#1&v1:6])-[#1&v1:7])-[#6&v4:8](-[#1&v1:9])(-[#1&v1:10])-[#1&v1:11])(-[#1&v1:12])-[#1&v1:13])>>([#8&v2:1](-[#6&v4:3](-[#6&v4:2](-[#8&v2]-[#1&v1])(-[#1&v1:12])-[#1&v1:13])(-[#6&v4:4](-[#1&v1:5])(-[#1&v1:6])-[#1&v1:7])-[#6&v4:8](-[#1&v1:9])(-[#1&v1:10])-[#1&v1:11])-[#1&v1])",
  • }][{
  • diameter: 12,
  • direction: -1,
  • ec_numbers: ["2.7.1.72"]
  • id: 7,
  • isStereo: 0,
  • score: 0,
  • smarts_string: "([#7&v3:1](=[#6&v4:2](-[#7&v3:3](-[#1&v1:4])-[#1&v1:5])-[#7&v3:6](-[#6&v4:7]1(-[#6&v4:8](-[#8&v2:9]-[#15&v5:10](=[#8&v2:11])(-[#8&v2:12]-[#1&v1:13])-[#8&v2:14]-[#1&v1:15])(-[#6&v4:16](-[#8&v2:17]-[#1&v1:18])(-[#6&v4:19](-[#8&v2:20]-[#6&v4:21](-[#8&v2:22])(-[#6&v4:23])-[#1&v1:24])(-[#6&v4:25](-[#7&v3:26](-[#6&v4:27])-[#1&v1:28])(-[#6&v4:29]-1(-[#8&v2:30]-[#1&v1:31])-[#1&v1:32])-[#1&v1:33])-[#1&v1:34])-[#1&v1:35])-[#1&v1:36])-[#1&v1:37])-[#1&v1:38])-[#1&v1:39])>>([#15&v5](=[#8&v2])(-[#8&v2]-[#1&v1])(-[#8&v2]-[#15&v5](=[#8&v2])(-[#8&v2]-[#1&v1])-[#8&v2]-[#15&v5:10](=[#8&v2:11])(-[#8&v2:12]-[#1&v1:13])-[#8&v2:14]-[#1&v1:15])-[#8&v2]-[#6&v4](-[#6&v4]1(-[#6&v4](-[#6&v4](-[#8&v2]-[#1&v1])(-[#6&v4](-[#8&v2]-1)(-[#7&v3]1:[#6&v4](:[#7&v3]:[#6&v4]2:[#6&v4](:[#7&v3]:[#6&v4](:[#7&v3]:[#6&v4]:1:2)-[#1&v1])-[#7&v3](-[#1&v1])-[#1&v1])-[#1&v1])-[#1&v1])-[#1&v1])(-[#8&v2]-[#1&v1])-[#1&v1])-[#1&v1])(-[#1&v1])-[#1&v1].[#7&v3:1](=[#6&v4:2](-[#7&v3:3](-[#1&v1:4])-[#1&v1:5])-[#7&v3:6](-[#6&v4:7]1(-[#6&v4:8](-[#8&v2:9]-[#1&v1])(-[#6&v4:16](-[#8&v2:17]-[#1&v1:18])(-[#6&v4:19](-[#8&v2:20]-[#6&v4:21](-[#8&v2:22])(-[#6&v4:23])-[#1&v1:24])(-[#6&v4:25](-[#7&v3:26](-[#6&v4:27])-[#1&v1:28])(-[#6&v4:29]-1(-[#8&v2:30]-[#1&v1:31])-[#1&v1:32])-[#1&v1:33])-[#1&v1:34])-[#1&v1:35])-[#1&v1:36])-[#1&v1:37])-[#1&v1:38])-[#1&v1:39])"
  • }]]
    • Error Response:
    Code: 400
    Content: { 'message': 'Input minDiameter must be integer from -1 to 16' }
    Code: 404
    Content: { 'message': 'Request INPUT is not present in the database' }
    Sample Call:
    curl -i "https://retrorules.org/api/v0.7/smartsid/?input=RR00239877"
Notes:Default diameter if not specified is 12. 'id' is the unique identifier. 'score' is penalty score where the smaller the better. 'direction' is -1 for reverse and 1 for forward. 'isStereo' determines if a given rule contains stochiometric descriptions where 1 is True and 0 is False.