V

IBM RXN for Chemistry httpsrxnresibmcom

Page 1 di 49

APIs Short User Guide (v2)

Date April 5th 2020

Edited by Teodoro Laino

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 2 di 49

Summary

1 INTRODUCTION 4

11 Fair use policy 4

2 API calls 5

21 Basic Information 5

211 Creation and Recovery of an API key 5

212 Common data structure of API calls 6

22 First create a project 7

221 API response code 8

222 Example with curl 9

23 How to create a new prediction 10

231 API response code 10

232 API Response code (in case of errors) 11

233 Example with curl 12

24 Recover prediction attempts using the prediction ID 13

241 API response code 13

242 Example with curl 15

25 List all stored projects 16

251 API response code 16

252 Example with curl 17

26 List all attempts in a project 19

261 API response code 19

262 Example with curl 21

27 Generate more outcomes 23

271 API response code 23

272 Example with curl 24

28 Retrosynthesis Automatic or Interactive 25

29 Automatic Retrosynthesis task submission 26

291 API response code 27

292 Example with curl 27

210 Automatic Retrosynthesis task retrieval 29

2101 API response code 30

2102 Example with curl 31

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 3 di 49

211 Interactive Retrosynthesis task submission 32

2111 API response code 32

2112 Example with curl 33

212 Interactive Retrosynthesis expansion task 36

2121 API response code 36

2122 Example with curl 37

213 Interactive Retrosynthesis retrieve expansions 38

2131 API response code 38

2132 Example with curl 38

214 Interactive Retrosynthesis select an expansion 41

2141 API response code 41

2142 Example with curl 42

215 Retrosynthesis retrieve queue status 45

2151 API response code 45

2152 Example with curl 45

216 Retrosynthesis retrieve PDF 46

2161 API response code 46

2162 Example with curl 46

217 Paragraph to Actions 48

2171 API response code 48

2172 Example with curl 48

IBM is a trademark of International Business Machines Corporation registered in many jurisdictions worldwide

Other product or service names may be trademarks or service marks of IBM or other companies

Changes to V1 added description of functionalities 27 to 214 (more outcomes automatic retrosynthesis and

interactive retrosynthesis)

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 4 di 49

1 INTRODUCTION This is a short user guide to allow the usage of the IBM RXN for Chemistry services in third party

applications through APIs calls

The entire system is based on an authentication mechanism via APIs keys Moreover any actions

performed through APIs will be appearing as well in the user dashboard when accessing the service

through the web-services

Please note that the access to the portal through APIs is done under best effort and subject to

changes without prior notice APIs are provided on an as is basis without warranty of any kind

11 Fair use policy In order to guarantee a fair usage of the free service to anybody on Earth the calls made via the API

interface will be limited to max 6 requests per minute with a minimum time of 2 seconds between

two consecutive calls Please note that the system orchestrating the API calls ignores if a call is

successfully executed or not For example letrsquos consider the following scenario

1 2 3 4 5 6 7

I I I I I I I

100ms 300ms 500ms 700ms 900ms 2200ms

The call (1) will be successfully executed From call (2) to call (6) the system will return an error

message (503 Service Unavailable) which means that the server is currently unable to handle the

request due to a usage policy (too short time between consecutive calls) The implication is that this

is a temporary condition which will be alleviated at the beginning of the next minute

Call (7) is respecting the 2 seconds minimum time but is actually the 7th request done within the

same minute and for this reason will return the same error (503) All the counters will be reset at the

start of the subsequent clock minute

If interested in high-throughput usage of these APIs please get in touch with the IBM RXN for

Chemistry team (httpsrxnresibmcom) for dedicated cloud instances or on premise installation

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 5 di 49

2 API calls

21 Basic Information In this section we will review basic information on how to generate an API key the structure of the

API calls and responses

Here we will document the essential API calls to run basic functionalities (reaction

predictionretrosynthesisetc) A more extensive list of API calls is available online h

ttpsrxnresibmcomrxnapiswagger-uihtml with limited documentation

211 Creation and Recovery of an API key To use the IBM RXN for Chemistry services you have first to generate an API key

To generate the token log-in into your personal account page of RXN and go on your profile page

(top-right corner of the main dashboard) Below your personal information you will find an API key

box Click on the ldquoGENERATErdquo button and it will create your own token (starting with apk-hellip) to use

in the subsequent API calls

Unlike the authentication mechanism for accessing the services through a browser this API key does

not expire (there is no time session limit) and must not be shared with other people to preserve your

own privacy

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 6 di 49

212 Common data structure of API calls

All API calls need to have the base URL of the services BaseUrl rxnresibmcom

Moreover the header of all calls must contain

Content-Type applicationjson Authorization apk-hellip

The structure of the answer to the request is

Payload

metadata

uiMessages

errors []

infos []

warnings []

Payload contains the real answer to the service request and the metadata section contains errors

info or warnings (if any)

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 7 di 49

22 First create a project

To run prediction similarly to the web-interface you have first to create a project folder where your

prediction will be stored

URL BaseUrl+rxnapiapiv1projects

Method POST

Body

nameTest API

invitations[

emailemailemailnop

]

Mandatory fields

name

invitations (can be empty but must be present)

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 8 di 49

221 API response code

The API response code contains several information among which the ldquoidrdquo is the most relevant to

proceed with the prediction capabilities

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 9 di 49

222 Example with curl

~gt curl --data name Test API invitations[] --header Content-Type

applicationjson --header Authorizationapk-have-here-your-own-key -X

POST httpsrxnresibmcomrxnapiapiv1projects

Output

payloadid5c532f56d6cb7600019ea34NVcreatedOn1548955478522

createdByba7a9ee4-6de6-44bc-b0b0-6eb17dc63cNV

modifiedOn1548955478522 modifiedByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63cNVnameTest

APIdescriptionnullattempts[]visibilitynullcomputedFieldsembed

metadatametadatauiMessageserrors[]infos[]warnings[]

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 10 di 49

23 How to create a new prediction

To create a new prediction is it necessary to know the project folder ID (see 22 First create a

project) where the result of the prediction will be stored As seen in the previous section the ID is a

parameter returned by the API response code

In our example for the project ldquoTest APIrdquo we obtained a project ID of

ldquoid5c2c95fed6cb7600019e6f17 Given a smile representing a single or multiple number of input

molecules (such as

C(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H][H]) the API call for

the prediction is constructed as

URL BaseUrl + rxnapiapiv1predictionsprprojectId=hellip

Method POST

Body

reactantsC(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C

=C2)C=C1O[H][H][H]

Mandatory fields

projectId = the project ID returned when the project folder is created

reactants = the smile representing the set of starting molecules

231 API response code

As for the project ID the response code of a prediction contains the prediction ID which is needed

to recover later the result of the prediction

payload

id 5c2cab97d6cb7600019e6f21

createdOn 1546431383554

createdBy 99f7928e-5992-484e-a0dc-9638a788ab47

modifiedOn 1546431383554

modifiedBy 99f7928e-5992-484e-a0dc-9638a788ab47

request

reactants

C(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H]

[H]

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 11 di 49

reagents []

mol

projectId 5c2c95fed6cb7600019e6f17

taskId e8fc2e28-a11d-429a-9821-3e409ef739a1

mol

type pr

status PREDICTION_READY

attempts null

computedFields

embed

metadata

metadatardquo hellip

232 API Response code (in case of errors)

In case of malformed or erroneous SMILES or in case of prediction errors the API reponse will try to

do its best to provide a feedback on why the prediction request failed

An example of a failure

payload null

metadata

uiMessages

errors [

code null

message ExplicitValenceError RDKit ERROR [123934] Explicit

valence for atom 0 H 3 is greater than permitted - reactants [H](C)(C)CCCC

400 RDKitError

type ERROR

fieldId null

target TOAST

]

infos []

warnings []

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 12 di 49

233 Example with curl

curl --data reactants

C(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H]

[H] mol --header Content-Type applicationjson --header

Authorizationapk-have-here-your-own-key -X POST

httpsrxnresibmcomrxnapiapiv1predictionsprprojectId=5c532f56d6cb7

600019ea342

Output

payloadid5c532fa7d6cb7600019ea345createdOn1548955559319cr

eatedByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1548955559319modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8 requestreactants

C(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H]

[H]

reagents[]molprojectId5c532f56d6cb7600019ea342taskId7604

bfc3-de1c-4569-b991-73efb1c7d738 mol typepr statusNEW

attemptsnull

computedFieldsembedmetadatametadatauiMessageserro

rs[]infos[]warnings[]1

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 13 di 49

24 Recover prediction attempts using the prediction ID

Using the prediction ID returned in the API prediction response code one can recover the attempt

outcome generated in the corresponding prediction

URL BaseUrl + rxnapiapiv1predictionsltPREDICTIONIDgt

Method GET

Mandatory fields

PREDICTIONID (es 5c2cab97d6cb7600019e6f21)

241 API response code

La risposta a questa richiesta contiene oltre che lo smiles i dati riguardanti lrsquoaccuratezza della

risposta AttentionWeights (SVG in Base64) e le immagini delle molecole (SVG in Base64)

payload

id 5c2cab97d6cb7600019e6f21

createdOn 1546431383554

createdBy 99f7928e-5992-484e-a0dc-9638a788ab47

modifiedOn 1546431395414

modifiedBy system

request

reactants

C(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H]

[H]

reagents []

mol

projectId 5c2c95fed6cb7600019e6f17

taskId e8fc2e28-a11d-429a-9821-3e409ef739a1

mol

type pr

status SUCCESS

attempts [

id 5c2caba3d6cb7600019e6f22

createdOn 1546431395402

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 14 di 49

createdBy system

modifiedOn 1546431395451

modifiedBy system

name Test API test_20190102_121635401

projectId 5c2c95fed6cb7600019e6f17

smiles Oc1cc(-c2c(O)cccc2-c2ccccc2)cc(O)c1O[H][H][H]gtgtOc1cc(-

c2c(O)cccc2-c2ccccc2)cc(O)c1O

attentionWeights ltxml version=10 encoding=utf-8

standalone=nogtnltDOCTYPE svg PUBLIC -W3CDTD SVG 11ENn

hellip hellip hellip hellip y=42960226gtn ltclipPathgtn ltdefsgtnltsvggtn

confidence 013361498713493347

message ok

reactionImage ltxml version=10 encoding=iso-8859-1gtnltsvg

version=11 baseProfile=fulln xmlns=httpwwww3org2000svgn

xmlnsrdkit=httpwwwrdkitorgxml hellip hellip ltpath d=M 695891968815

700569100 style=fillnonefill-ruleevenoddstroke000000stroke-

width2pxstroke-linecapbuttstroke-linejoinmiterstroke-opacity1

gtnltsvggtn

predictionId 5c2cab97d6cb7600019e6f21

feedbacks null

firstAttempt true

predictTime null

totalTime null

computedFields

embed

metadata

]

computedFields

embed

metadata

metadatardquo hellip

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 15 di 49

242 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET

httpsrxnresibmcomrxnapiapiv1predictions5c532fa7d6cb7600019ea345

Output

payloadid5c5aaf22d6cb7600019ea809createdOn1549446946367cr

eatedByba7a9ee4-6de6-44bc-b0b0-6eb17dc63ca8

modifiedOn1549446950420

modifiedBysystemrequestreactantsC(O)1=C(O)C=C(C2=C(O)C=C([H])C

([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H][H]reagents[]molproje

ctId5c532f56d6cb7600019ea342taskIdaf0e8aa5-c2a9-4819-9e41-

ad7e40421090moltypeprstatusSUCCESSattempts[id5c5a

af26d6cb7600019ea80acreatedOn1549446950408createdBysystemm

odifiedOn1549446950583modifiedBysystemnameTest

API_20190206_095550407projectId5c532f56d6cb7600019ea342smiles

Oc1cc(-c2c(O)cccc2-c2ccccc2)cc(O)c1O[H][H][H]gtgtOc1cc(-c2c(O)cccc2-

c2ccccc2)cc(O)c1OattentionWeightsltxml version=10 encoding=utf-

8 standalone=nogtnltDOCTYPE svg PUBLIC -W3CDTD SVG

11ENn httpwwww3orgGraphicsSVG11DTDsvg11dtdgtn [hellip hellip

hellip]

ldquoconfidence013361498713493347messageokreactionImageltxml

version=10 encoding=iso-8859-1gtn[hellip hellip hellip]

predictionId5c5aaf22d6cb7600019ea809feedbacksnullfirstAttempttru

epredictTimenulltotalTimenullcomputedFieldsembedmetadata

]computedFieldsembedmetadatametadatauiMessages

errors[]infos[]warnings[]

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 16 di 49

25 List all stored projects

URL BaseUrl +rxnapiapiv1projectspage=0ampsize=30

Method GET

251 API response code

Returns the list of projects belonging to API key owner

payload content [ id5c2c95fed6cb7600019e6f17 createdOn1546425854026 createdBy99f7928e-5992-484e-a0dc-9638a788ab47 modifiedOn1546425854026 modifiedBy99f7928e-5992-484e-a0dc-9638a788ab47 nameTest API descriptionnull attempts[] visibilitynull computedFields embed metadata id5c2c95fed6cb7600019e6f18 createdOn1546425854026 createdBy99f7928e-5992-484e-a0dc-9638a788ab47 modifiedOn1546425854026 modifiedBy99f7928e-5992-484e-a0dc-9638a788ab47 nameTest API 2 descriptionnull attempts[] visibilitynull computedFields embed metadata hellip totalPages1 lasttrue totalElements7 numberOfElements7 sortnull firsttrue size20

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 17 di 49

number0 metadatauiMessageserrors[]infos[]warnings[]

The API response code contains several information among which the ldquoidsrdquo are the most relevant to

proceed with the prediction capabilities inside those project containers

252 Example with curl

~gt curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET

httpsrxnresibmcomrxnapiapiv1projectspage=0ampsize=30

Output

payloadcontent[id5b838235a5b9db0001ee1b4bcreatedOn15353

45205378createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1535345205378modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8nametestdescriptionnullattempts[]visibilitynullco

mputedFieldsembedmetadataid5b841f72d633050001f190a2

createdOn1535385458169createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1535385458169modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8nametest on

Mondaydescriptionnullattempts[]visibilitynullcomputedFieldsem

bedmetadataid5bc7344d78d6520001ed4aa1createdOn153978

1709804createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1539781709804modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8nametest

2descriptionnullattempts[]visibilitynullcomputedFieldsembed

metadataid5be4204478d6520001ed6115createdOn15416771241

78createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1541677124178modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8namepress

daydescriptionnullattempts[]visibilitynullcomputedFieldsembed

metadataid5bed994a78d6520001ed6dfbcreatedOn1542297930

532createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1542297930532modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8namewebinar18descriptionnullattempts[]visibilityn

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 18 di 49

ullcomputedFieldsembedmetadataid5c49e8ded6cb7600019e

9732createdOn1548347614461createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1548347614461modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8nameWebinardescriptionnullattempts[]visibilitynul

lcomputedFieldsembedmetadataid5c532f56d6cb7600019ea3

42createdOn1548955478522createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1548955478522modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8nameTest

APIdescriptionnullattempts[]visibilitynullcomputedFieldsembed

metadata]totalPages1lasttruetotalElements7numberOfEleme

nts7sortnullfirsttruesize20number0metadatauiMessagese

rrors[]infos[]warnings[]

Which is equivalent to the view one can get using the browser interface

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 19 di 49

26 List all attempts in a project

URL BaseUrl

+rxnapiapiv1projectsltPROJECTIDgtattemptsraw=amppage=0ampsize=8

ampsort=createdOnDESC

Method GET

Mandatory fields

bull PROJECTID (es 5c2c95fed6cb7600019e6f17)

Optional fields

bull raw (must be always set equal to )

bull page (ie 0 1 2 )

bull size (ie 8 elements per page)

bull sort (createdOn DESC (ASC|DESC) )

In case these fields (defining the paging of the results) are not defined the entire list of attempts will

be retrieved (it may take a long time)

261 API response code

Returns the list of attempts belonging to the given project ID per page and sorted (according

requested criteria)

payload content [ id 5b894010b72b87000121f186 createdOn 1535721488737 createdBy system modifiedOn 1535721488817 modifiedBy system name testfb_20180831_131808737 projectId 5b759c5e300be10001fc9dc6

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 20 di 49

smiles OOC1CC2(CCC3(CCCC3)C2)CC1OgtgtO=C1CC2(CCC3(CCCC3)C2)CC1O attentionWeights ltxml version=10 encoding=utf-8 standalone=nogtnltDOCTYPE svg PUBLIC -W3CDTD SVG 11ENn hellip hellip hellip hellip y=42960226gtn ltclipPathgtn ltdefsgtnltsvggtn confidence 05353702306747437 message ok reactionImage ltxml version=10 encoding=iso-8859-1gtnltsvg version=11 baseProfile=fulln xmlns=httpwwww3org2000svgn xmlnsrdkit=httpwwwrdkitorgxml hellip hellip ltpath d=M 695891968815 700569100 style=fillnonefill-ruleevenoddstroke000000stroke-width2pxstroke-linecapbuttstroke-linejoinmiterstroke-opacity1 gtnltsvggtn predictionId 5b89400cb72b87000121f185 feedbacks null firstAttempt true predictTime null totalTime null computedFields embed metadata id 5b7708d4ec909700010e48a9 createdOn 1534527700063 createdBy system modifiedOn 1534527700101 modifiedBy system name testfb_20180817_174140062 projectId 5b759c5e300be10001fc9dc6 smiles COC(=O)C1=CC2C=CC1CC2COC(=O)CC1CCCC(O)C1gtgtCOC(=O)C1=CC2CCC1CC2 attentionWeights ltxml version=10 encoding=utf-8 standalone=nogtnltDOCTYPE svg PUBLIC -W3CDTD SVG 11ENn hellip hellip hellip hellip y=42960226gtn ltclipPathgtn ltdefsgtnltsvggtn confidence 008226326107978821 message ok reactionImage ltxml version=10 encoding=iso-8859-1gtnltsvg version=11 baseProfile=fulln xmlns=httpwwww3org2000svgn xmlnsrdkit=httpwwwrdkitorgxml hellip hellip ltpath d=M 695891968815 700569100 style=fillnonefill-ruleevenoddstroke000000stroke-width2pxstroke-linecapbuttstroke-linejoinmiterstroke-opacity1 gtnltsvggtn predictionId 5b7708cdec909700010e48a8 feedbacks null firstAttempt true predictTime null

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 21 di 49

totalTime null computedFields embed metadata ] totalPages 1 last true totalElements 2 numberOfElements 2 sort [ direction DESC property createdOn ignoreCase false nullHandling NATIVE descending true ascending false ] first true size 8 number 0 metadatardquo hellip

262 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET

httpsrxnresibmcomrxnapiapiv1projects5c532f56d6cb7600019ea342at

temptsraw=amppage=0ampsize=8ampsort=createdOnDESC

Output

payloadcontent[id5c5aaf26d6cb7600019ea80acreatedOn154944

6950408createdBysystemmodifiedOn1549446950583modifiedBysyst

emnameTest

API_20190206_095550407projectId5c532f56d6cb7600019ea342smiles

Oc1cc(-c2c(O)cccc2-c2ccccc2)cc(O)c1O[H][H][H]gtgtOc1cc(-c2c(O)cccc2-

c2ccccc2)cc(O)c1OattentionWeightsltxml version=10 encoding=utf-

8 [hellip hellip

hellip]rdquordquoconfidence013361498713493347messageokreactionImageltxml

version=10 encoding=iso-8859-1gtnltsvg version=11 [hellip hellip

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 22 di 49

hellip]rdquordquopredictionId5c5aaf22d6cb7600019ea809feedbacksnullfirstAttempt

truepredictTimenulltotalTimenullcomputedFieldsembedmetada

taid5c532fadd6cb7600019ea346createdOn1548955565399create

dBysystemmodifiedOn1548955565542modifiedBysystemnameTe

st

API_20190131_172605398projectId5c532f56d6cb7600019ea342smiles

Oc1cc(-c2c(O)cccc2-c2ccccc2)cc(O)c1O[H][H][H]gtgtOc1cc(-c2c(O)cccc2-

c2ccccc2)cc(O)c1OattentionWeightsltxml version=10 encoding=utf-

8 [hellip hellip

hellip]rdquordquoconfidence013361498713493347messageokreactionImageltxml

version=10 encoding=iso-8859-1gtnltsvg version=11 [hellip hellip

hellip]ldquordquopredictionId5c532fa7d6cb7600019ea345feedbacksnullfirstAttempt

truepredictTimenulltotalTimenullcomputedFieldsembedmetada

ta]totalPages1lasttruetotalElements2numberOfElements2sort

[directionDESCpropertycreatedOnignoreCasefalsenullHandling

NATIVEdescendingtrueascendingfalse]firsttruesize8number0

metadatauiMessageserrors[]infos[]warnings[]

Which is equivalent to the view you can have using the browser and navigating in the ldquoAPI Testrdquo

project folder

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 23 di 49

27 Generate more outcomes

URL BaseUrl

+rxnapiapiv1predictionsprbpredictionId=ltPREDICTIONIDgtampprojectId=

ltPROJECTIDgt

Method POST

Body

reactantsC(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C

=C2)C=C1O[H][H][H]

Mandatory fields

bull PROJECTID = the project ID returned when the project folder is created

bull reactants = the smile representing the set of starting molecules

bull PREDICTIONID = the prediction ID of the reaction for which one wishes to

generate more outcomes (es 5c2cab97d6cb7600019e6f21)

271 API response code

As for the prediction ID the response code of a generate more outcome contains the prediction ID

which is needed to recover later the result of the prediction (see 24 Recover prediction attempts

using the prediction ID)

payload id5c2cab97d6cb7600019e6f21 metadata embed computedFields createdOn1584823120898 createdByba7a9ee4-6de6-44bc-b0b06eb17dcsada8 modifiedOn1584813889819 modifiedByba7a9ee4-6de6-44bc-b0b0-6eb1sdas3ca8 requestreactantsC1=CC=CC=C1[S+](C1=CC=CC=C1)C1=CC=CC=C1O

reagents[]mol

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 24 di 49

projectId5e762b9648260b0001059324

taskId514f45e6-d5ef-4bd6-b025-0162e4f11e17 mol typeprb statusPREDICTION_READY errorMessagenull attemptsnull metadatauiMessageserrors[]infos[]warnings[]extendedP

agination

272 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X POST

httpsrxnresibmcomrxnapiapiv1predictionsprbprojectId=5c532fa7d6cb

7600019ea345amppredictionId=5e76565c48260b00010598d0

--data reactants

C(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H]

[H] mol

Output

payloadid5e76565c48260b00010598d0metadataembedcom

putedFieldscreatedOn1584813660898createdByba7a9ee4-6de6-44bc-

b0b0-6eb17dc63ca8modifiedOn1584813889819modifiedByba7a9ee4-

6de6-44bc-b0b0-6eb17dc63ca8requestreactants

C(O)1=C(O)C=C(C2=C(O)C=C([H])C([H])=C2C2=C([H])C=C([H])C=C2)C=C1O[H][H][

H]reagents[]molprojectId5c532fa7d6cb7600019ea345taskId5

14f45e6-d5ef-4bd6-b025-

0162e4f11e17moltypeprbstatusPREDICTION_READYerrorMess

agenullattemptsnullmetadatauiMessageserrors[]infos[]warn

ings[]extendedPagination

Using the same prediction ID of the original reaction prediction you can visualize all the outcomes

generated by this API call

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 25 di 49

28 Retrosynthesis Automatic or Interactive

When should you choose an interactive VS an automatic

The algorithm of the automatic retrosynthesis uses holistic (inspired by the Bayesian probability) to

determine the optimal branch of the tree to expand in order to arrive in the shortest number of

steps to commercially available materials To optimize speed and performance we never construct

an entire tree of retrosynthetic options but focus exclusively on those disconnections that have the

greatest chance to bring the design to completion in the smallest number of steps We designed the

retrosynthetic tool in this way to provide an interactive use and a better experience for users on the

IBM RXN for Chemistry platform

The holistic is of course perfectible and will undergo constant improvements in the future For this

reason whenever your retrosynthetic task does not produce anything meaningful (ie the target is

disconnected into itself) we recommend trying the interactive mode in which you design the

retrosynthetic tree choosing the steps from a list of options recommended by the AI algorithm

The first more (automatic) is fully human-independent But if you prefer to have control and be only

guided among different possible disconnection then revert to the interactive mode where the AI will

only be your assistant in the retrosynthesis design AI recommends and you choose

The API call is identical It is possible to switch between an automatic or interactive retrosynthesis by

specifying accordingly the value of the API key isInteractive

For automatic retrosynthesis there is little else to do after the submission of the API call rather than

retrieve the results (see 210 Automatic Retrosynthesis task retrieval)

For interactive retrosynthesis you need to construct the retrosynthetic tree using your domain

expertise This consists in calling retrieving choosing and setting the optimal sequences to complete

your retrosynthetic design Next sections will detail the operations needed to construct your

interactive retrosynthesis if you decide to compile it with the use of APIs Of course we recommend

for this task to use the online graphical interface at httpsrxnresibmcom

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 26 di 49

29 Automatic Retrosynthesis task submission

URL BaseUrl +rxnapiapiv1retrosynthesisrsprojectId=ltPROJECTIDgt

Method POST Body isInteractive false this key decides If you want to run and automatic or interactive parameters availability_pricing_threshold 0 available_smiles string or null exclude_smiles string or null exclude_substructures string or null exclude_target_molecule true fap 0 max_steps 0 nbeams 0 pruning_steps 0 product SMILE

Mandatory fields

bull isInteractive= false for automatic retrosynthesis true for interactive

retrosynthesis

bull availability_pricing_threshold= Maximum price in USD per mgml of

commercially available compounds that will be considered available

precursors for the retrosynthesis

bull available_smiles= Smiles of molecules available as precursors

bull exclude_smiles= Smiles of molecules to exclude from set of precursors

bull exclude_substructures= Smiles of substructures to exclude from

precursors

bull exclude_target_molecule=truefalse to exclude product (when

commercially available)

bull fap= Forward Acceptance Probability Every retrosynthetic step is

evaluated with the forward prediction model The step is retrained if the

the forward confidence is greater than FAP

bull max_steps= maximum number of retrosynthetic steps

bull nbeams= maximum number of beams exploring the hypertree

bull pruning_steps= number of interval steps to prune the explored hypertree

bull product= SMILE of the molecule to retrosynthetise

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 27 di 49

bull PROJECTID (es 5c2c95fed6cb7600019e6f17)

Depending on the value of the parameters the retrosynthesis can be a computationally intensive

task

291 API response code

Returns the list of information related to the submitted retrosynthesis A WAITING status is also

returned and indicates that the retrosynthesis is in the queue

292 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X POST --data isInteractive false parameters

availability_pricing_threshold 1 available_smiles null exclude_smiles

null exclude_substructures null exclude_target_molecule true fap 060

max_steps 3 nbeams 10 pruning_steps 2 product C(Cl)1CCCCC1

httpsrxnresibmcomrxnapiapiv1retrosynthesisrsprojectId=5c532f56d6c

b7600019ea342

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 28 di 49

Output

payloadid5e788abd48260b1110105ecf2metadataembedcom

putedFieldscreatedOn1584958141361createdByba7a9ee4-6de6-44bc-

b0b0-6eb17dc63ca8modifiedOn1584958141710modifiedByba7a9ee4-

6de6-44bc-b0b0-

6eb17dc63ca8projectId5c532fa7d6cb7600019ea345statusNEWerror

Messagenulltaskfinished_time00metaDataqueued_timenullsta

rted_time00statusWAITINGexpected_start1584958251683708E9qu

eue_position0task_id5e788abd0f98ae70e4c6a2c6retrieval_time00re

try0countersbackward_prediction0forward_prediction0molecules

[]sequences[]legend[color28a30dlabelMolecule commercially

available on eMoleculescomcolorce4e04labelNot able to find a

synthetic

path]wizardParametersnullsiblings[]metaDataqueuePosition0will

BeCompletedOn1584958251691396E9modelnullisInteractivefalsemet

adatauiMessageserrors[]infos[]warnings[]extendedPagination

The evaluation of the retrosynthesis is an asynchronous process As it may take few minutes once it

is launched you can check with additional APIs (see 210 Automatic Retrosynthesis task retrieval)

the status of the retrosynthesis and eventually retrieve the results

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 29 di 49

210 Automatic Retrosynthesis task retrieval

URL BaseUrl +rxnapiapiv1retrosynthesisltRETROSYNTHESISIDgt

Method GET

Mandatory fields

bull RETROSYNTHESIS= this is the ID returned by the submission API of the

retrosynthesis (es 5e777d0b48260b134105bf2b)

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 30 di 49

2101 API response code

When the retrosynthetic task is completed (taskstatus = SUCCESS) the API response will contain all

possible sequences (build in hierarchical tree format) as well as the list of all possible retrosynthetic

single step for each molecule (siblings)

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 31 di 49

2102 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET

httpsrxnresibmcomrxnapiapiv1retrosynthesis

5e777d0b48260b134105bf2b

Output

payloadhellip

sequences[id5e788ae548260b000105ecf4metadatahcomplexity[0

92843657802133660933212826963169]statusDONE hellip

treeid5e788ae548260b000105ecf7metadataembedcomputed

FieldscreatedOn1584958181564createdBysystemmodifiedOn1584

958181564modifiedBysystemmoleculeId5d0a7756e5d96c00011819db

retrosynthesisId5e788abd48260b000105ecf2sequenceId5e788ae548260

b000105ecf4projectId5e762b9648260b0001059324smilesClC1CCCCC1

confidence0999rclassHydroxy to

chlorohasFeedbackfalsefeedbacknullchildren[id5e788ae548260b0

00105ecf5metadataembedcomputedFieldscreatedOn1584958

181539createdBysystemmodifiedOn1584958181539modifiedBysyste

mmoleculeId5b7b46f1ec909700010e824bretrosynthesisId5e788abd48

260b000105ecf2sequenceId5e788ae548260b000105ecf4projectId5e76

2b9648260b0001059324smilesClP(Cl)(Cl)(Cl)Clconfidence00rclassU

ndefinedhasFeedbackfalsefeedbacknullchildren[]metaDataborder

Color28a30disExpandablefalseid5e788ae548260b000105ecf6m

etadataembedcomputedFieldscreatedOn1584958181556create

dBysystemmodifiedOn1584958181556modifiedBysystemmoleculeId

5b7b3cb0ec909700010e80aaretrosynthesisId5e788abd48260b000105ecf

2sequenceId5e788ae548260b000105ecf4projectId5e762b9648260b00

01059324smilesOC1CCCCC1confidence00rclassUndefinedhasFee

dbackfalsefeedbacknullchildren[]metaDataborderColor28a30d

isExpandablefalse]metaDataisExpandablefalseisInteractivefalse

hellip

The amount of information retrieved by this API call is quite large The different retrosynthetic

sequences are organized in a tree You can parse that information for each sequence to generate the

corresponding retrosynthetic tree

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 32 di 49

211 Interactive Retrosynthesis task submission

URL BaseUrl +rxnapiapiv1retrosynthesisrsprojectId=ltPROJECTIDgt

Method POST Body isInteractive true this key decides If you want to run and automatic or interactive parameters availability_pricing_threshold 0 product SMILE

Mandatory fields

bull isInteractive= false for automatic retrosynthesis true for interactive

retrosynthesis

bull availability_pricing_threshold= Maximum price in USD per mgml of

commercially available compounds that will be considered available

precursors for the retrosynthesis

bull product= SMILE of the molecule to retrosynthetise

bull PROJECTID (es 5c2c95fed6cb7600019e6f17)

The first call is required only to initiate the retrosynthetic task The expansion and selection of the

corresponding tree is achieved with the use of the subsequent APIs

2111 API response code

Returns the list of information related to the submitted retrosynthesis A WAITING status is also

returned and indicates that the retrosynthesis is in the queue

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 33 di 49

2112 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X POST --data isInteractive true parameters

availability_pricing_threshold 1 product C(Cl)1CCCCC1

httpsrxnresibmcomrxnapiapiv1retrosynthesisrsprojectId=5c532f56d6c

b7600019ea342rsquo

Output

payloadid5e899c5948260b000107d777metadataembedcomp

utedFieldscreatedOn1586076761397createdByba7a9ee4-6de6-44bc-

b0b0-6eb17dc63ca8modifiedOn1586076761397modifiedByba7a9ee4-

6de6-44bc-b0b0-

6eb17dc63ca8projectId5e762b9648260b0001059324statusDONEerr

orMessagenulltasknullmolecules[id5e78717a48260b000105ecb4

metadataembedcomputedFieldscreatedOn1584951674746crea

tedByba7a9ee4-6de6-44bc-b0b0-

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 34 di 49

6eb17dc63ca8modifiedOn1584951674746modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8smilesC(Cl)1CCCCC1moleculeImagerdquo

[]

sequences[id5e899c5948260b000107d778metadatanullembedc

omputedFieldscreatedOn1586076761406createdByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8modifiedOn1586076761454modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8usernullconfidence10optimizationScorenullposition0

confidenceTagHnameSequence

0_20200405_085241406outcomeMoleculesnullproductMoleculenullpr

ojectId5e762b9648260b0001059324retrosynthesisId5e899c5948260b000

107d777sequenceIdnulllabelSequence

0complexityGraphnullfeedbacknullhasFeedbacknullisSavednullme

taDatanulltreeid5e899c5948260b000107d779metadataembed

computedFieldscreatedOn1586076761413createdByba7a9ee4-

6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1586076761413modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8moleculeId5e78717a48260b000105ecb4retrosynthesisId

5e899c5948260b000107d777sequenceId5e899c5948260b000107d778

projectId5e762b9648260b0001059324smilesC(Cl)1CCCCC1confidence

10rclassUndefinedhasFeedbacknullfeedbacknullchildren[]meta

DatanullisExpandabletrueisInteractivetrue]legend[]wizardParamet

ersavailable_smiles[]exclude_smiles[]exclude_substructures[]param

etersmax_stepslabelnulldescriptionnullvalue00nbeamslabel

nulldescriptionnullvalue00faplabelnulldescriptionnullvalue

nullpruning_stepslabelnulldescriptionnullvalue00availability_pric

ing_thresholdlabelnulldescriptionnullvalue10siblings[]metaDa

tanullmodelnullisInteractivetruemetadatauiMessageserrors[]

infos[]warnings[]extendedPagination

The information about the tree (highlighted in green) will have to be stored and transmitted when

selecting and assigning a specific expansion (see 211 Interactive Retrosynthesis task submission)

In red is highlighted the RETROSYNTHESISID and in orange the NODEID These information needs to

be intercepted and store for subsequent calls

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 35 di 49

The retrosynthesis appears also in the web application under the user accountproject

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 36 di 49

212 Interactive Retrosynthesis expansion task

URL BaseUrl +rxnapiapiv1retrosynthesisltRETROSYNTHESISIDgt expand-

moleculeltNODEIDgt

Method GET

Mandatory fields

bull NODEID=the target node to expand (see 211 Interactive Retrosynthesis

task submission)

bull RETROSYNTHESISID= this is the ID returned by the submission API of the

retrosynthesis (es 5e777d0b48260b134105bf2b) (see 211 Interactive

Retrosynthesis task submission)

2121 API response code

status WAITING task counters backward_prediction 0 forward_prediction 0 expected_start 0 finished_time 0 metaData additionalProp1 additionalProp2 additionalProp3 queue_position 0 queued_time 0 retrieval_time 0 retry 0 started_time 0 status NEW task_id string

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 37 di 49

2122 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET

httpsrxnresibmcomrxnapiapiv1retrosynthesis5e899c5948260b000107

d777expand-molecule5e899c5948260b000107d779rsquo

Output

payloadtaskfinished_time00metaDataqueued_timenullstarte

d_time00statusWAITINGexpected_start1586009903895212E9queue

_position0task_id5e899db72f5c865fb216a29cretrieval_time00retry

0countersbackward_prediction0forward_prediction0molecules[]

siblings[]metaDatanullstatusWAITINGlegendnullmetadatauiM

essageserrors[]infos[]warnings[]extendedPagination

This API calls the single-step retrosynthetic engine to provide a single step retrosynthesis (including

not only reactants but also reagents) for the node target molecule This API as the automatic

retrosynthesis is task based In order to inspect the outcome it will be necessary to call the relative

API to query the statusresult of the single-step retrosynthetic engine providing the corresponding

task_id (in green)

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 38 di 49

213 Interactive Retrosynthesis retrieve expansions

URL BaseUrl +apiv1retrosynthesislt RETROSYNTHESISIDgtexpand-

moleculeresultlt TASKIDgt

Method GET

Mandatory fields

bull TASKID the ID of the task returned by the task expansion API (see 212

Interactive Retrosynthesis expansion task)

bull RETROSYNTHESISID= this is the ID returned by the submission API of the

retrosynthesis (es 5e777d0b48260b134105bf2b)

2131 API response code

The API response is similar to the response of the automatic retrosynthesis

molecules [] sequences [] siblings [] task

2132 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET

lsquohttpsrxnresibmcomrxnapiapiv1retrosynthesis5e899c5948260b000107

d777expand-moleculeresult5e899db72f5c865fb216a29crsquo

Output

payloadtaskfinished_time1586077112449E9metaDataqueued_ti

menullstarted_time1586077111895E9statusDONEexpected_start0

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 39 di 49

0queue_position0task_id5e899db72f5c865fb216a29cretrieval_time0

0retry0countersbackward_prediction0forward_prediction0molec

ules[id5e78717a48260b000105ecb4metadataembedcomputed

FieldscreatedOn1584951674746createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1584951674746modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8smilesC(Cl)1CCCCC1moleculeImage

[hellip]

reactions[idnullmetadataembedcomputedFieldscreatedOn

nullcreatedBynullmodifiedOnnullmodifiedBynullconfidence0777c

onfidenceTagHlabelnullrclassAlkene

hydrochlorinationsmilesC1=CCCCC1Clchildren[smilesC1=CCCCC1

metaDataborderColor28a30dmoleculeId5d21471fe5d96c000118

3d57isExpandablefalsesmilesClmetaDataborderColor28a3

0dmoleculeId5cce1037c64d8d0001d2aea5isExpandablefalse]meta

Datamolecule2colorC1=CCCCC128a30dCl28a30dmolecule2ex

pandableC1=CCCCC1falseClfalsepricing_threshold1000idnullm

etadataembedcomputedFieldscreatedOnnullcreatedBynullm

odifiedOnnullmodifiedBynullconfidence521E-

7confidenceTagLlabelnullrclassAlkene

hydrochlorinationsmilesC=C1CCCCC1Clchildren[smilesC=C1CCCCC

1metaDataborderColor28a30dmoleculeId5b7b2973ec9097000

10e7f19isExpandablefalsesmilesClmetaDataborderColor28

a30dmoleculeId5cce1037c64d8d0001d2aea5isExpandablefalse]me

taDatamolecule2colorC=C1CCCCC128a30dCl28a30dmolecule

2expandableC=C1CCCCC1falseClfalsepricing_threshold1000idnu

llmetadataembedcomputedFieldscreatedOnnullcreatedBynul

lmodifiedOnnullmodifiedBynullconfidence0136confidenceTagLl

abelnullrclassChlorinationsmilesC1CCCCC1ClP(Cl)(Cl)(Cl)Clchildre

n[smilesC1CCCCC1metaDataborderColor28a30dmoleculeId

5d8292a8e5d96c000118f213isExpandablefalsesmilesClP(Cl)(Cl)(Cl)C

lmetaDataborderColor28a30dmoleculeId5b7b0d80ec90970001

0e7a75isExpandablefalse]metaDatamolecule2colorC1CCCCC12

8a30dClP(Cl)(Cl)(Cl)Cl28a30dmolecule2expandableC1CCCCC1false

ClP(Cl)(Cl)(Cl)Clfalsepricing_threshold1000idnullmetadataembe

dcomputedFieldscreatedOnnullcreatedBynullmodifiedOnnullm

odifiedBynullconfidence00268confidenceTagLlabelnullrclassC

hlorinationsmilesC1CCCCC1O=S(Cl)Clc1ccncc1children[smilesC1C

CCCC1metaDataborderColor28a30dmoleculeId5d8292a8e5d96

c000118f213isExpandablefalsesmilesO=S(Cl)ClmetaDataborder

Color28a30dmoleculeId5b7ac686ec909700010e6b26isExpandable

falsesmilesc1ccncc1metaDataborderColor28a30dmoleculeI

d5b7a6f95ec909700010e5cc4isExpandablefalse]metaDatamolecule

2colorC1CCCCC128a30dO=S(Cl)Cl28a30dc1ccncc128a30d

molecule2expandableC1CCCCC1falseO=S(Cl)Clfalsec1ccncc1falsepri

cing_threshold1000idnullmetadataembedcomputedFields

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 40 di 49

createdOnnullcreatedBynullmodifiedOnnullmodifiedBynullconfidenc

e000898confidenceTagLlabelnullrclassChlorinationsmilesC

1CCCCC1ClP(Cl)Clchildren[smilesC1CCCCC1metaDataborderColo

r28a30dmoleculeId5d8292a8e5d96c000118f213isExpandablefals

esmilesClP(Cl)ClmetaDataborderColor28a30dmoleculeId

5c913d92c64d8d0001d23d45isExpandablefalse]metaDatamolecule2c

olorC1CCCCC128a30dClP(Cl)Cl28a30dmolecule2expandableC

1CCCCC1falseClP(Cl)Clfalsepricing_threshold1000idnullmetadata

embedcomputedFieldscreatedOnnullcreatedBynullmodifiedO

nnullmodifiedBynullconfidence0999confidenceTagHlabelnull

rclassHydroxy to

chlorosmilesClP(Cl)(Cl)(Cl)ClOC1CCCCC1children[smilesClP(Cl)(Cl)(

Cl)ClmetaDataborderColor28a30dmoleculeId5b7b0d80ec90970

0010e7a75isExpandablefalsesmilesOC1CCCCC1metaDataborde

rColor28a30dmoleculeId5b7b3cb0ec909700010e80aaisExpandable

false]metaDatamolecule2colorClP(Cl)(Cl)(Cl)Cl28a30dOC1CCCCC

128a30dmolecule2expandableClP(Cl)(Cl)(Cl)ClfalseOC1CCCCC1fals

epricing_threshold1000idnullmetadataembedcomputedField

screatedOnnullcreatedBynullmodifiedOnnullmodifiedBynullconf

idence0998confidenceTagHlabelnullrclassHydroxy to

chlorosmilesO=S(Cl)ClOC1CCCCC1children[smilesO=S(Cl)Clmet

aDataborderColor28a30dmoleculeId5b7ac686ec909700010e6b26

isExpandablefalsesmilesOC1CCCCC1metaDataborderColor2

8a30dmoleculeId5b7b3cb0ec909700010e80aaisExpandablefalse]

metaDatamolecule2colorO=S(Cl)Cl28a30dOC1CCCCC128a30d

molecule2expandableO=S(Cl)ClfalseOC1CCCCC1falsepricing_threshold

1000

[]

]]metaDatanullstatusDONElegend[color28a30dlabelMolec

ule commercially available on eMoleculescomcolorce4e04labelNot

able to find a synthetic

path]metadatauiMessageserrors[]infos[]warnings[]extende

dPagination

In red are highlighted few possible reactions that can be assigned (see 214 Interactive

Retrosynthesis select an expansion) to the molecule to expand This information (one among the

highlighted ones) needs to be combined with the information provided by the interactive task

submission (see 211 Interactive Retrosynthesis task submission) as input for the

selectionassignment of a specific expansion (see 214 Interactive Retrosynthesis select an

expansion)

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 41 di 49

214 Interactive Retrosynthesis select an expansion

URL BaseUrl +apiv1retrosynthesislt RETROSYNTHESISIDgttreeltNODEIDgt

Method PATCH

Mandatory fields

bull NODEID NODEID=the target node to expand (see 211 Interactive

Retrosynthesis task submission)

bull RETROSYNTHESIS= this is the ID returned by the submission API of the

retrosynthesis (es 5e777d0b48260b134105bf2b)

bull children [

isExpandable true

moleculeId string

smiles string

]

2141 API response code

status NEW task counters backward_prediction 0 forward_prediction 0 expected_start 0 finished_time 0 metaData additionalProp1 additionalProp2 additionalProp3 queue_position 0 queued_time 0 retrieval_time 0 retry 0 started_time 0 status NEW task_id string

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 42 di 49

2142 Example with curl

curl --data-binary

id5e899c5948260b000107d779metadataembedcomputedFiel

dscreatedOn1586076761413createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1586076761413modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8moleculeId5e78717a48260b000105ecb4retrosynthesisId

5e899c5948260b000107d777sequenceId5e899c5948260b000107d778

projectId5e762b9648260b0001059324smilesC(Cl)1CCCCC1hasFeedba

cknullfeedbacknull

confidence0999confidenceTagHlabelnullrclassHydroxy to

chlorosmilesClP(Cl)(Cl)(Cl)ClOC1CCCCC1children[smilesClP(Cl)(Cl)(

Cl)ClmetaDataborderColor28a30dmoleculeId5b7b0d80ec90970

0010e7a75isExpandablefalsesmilesOC1CCCCC1metaDataborde

rColor28a30dmoleculeId5b7b3cb0ec909700010e80aaisExpandable

false]metaDatanullisExpandabletruesiblingIdnull --header Content-

Type applicationjson --header Authorizationapk-have-here-your-own-key

-X PATCH

lsquohttpsrxnresibmcomrxnapiapiv1retrosynthesis5e899c5948260b000107

d777tree5e899c5948260b000107d779

Output

payloadid5e899c5948260b000107d777metadataembedcomp

utedFieldscreatedOn1586076761397createdByba7a9ee4-6de6-44bc-

b0b0-6eb17dc63ca8modifiedOn1586076761397modifiedByba7a9ee4-

6de6-44bc-b0b0-

6eb17dc63ca8projectId5e762b9648260b0001059324statusDONEerr

orMessagenulltasknullmolecules[id5e78717a48260b000105ecb4

metadataembedcomputedFieldscreatedOn1584951674746crea

tedByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1584951674746modifiedByba7a9ee4-6de6-

44bc-b0b0-6eb17dc63ca8smilesC(Cl)1CCCCC1moleculeImage

[]

sequences[id5e899c5948260b000107d778metadatanullembedc

omputedFieldscreatedOn1586076761406createdByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8modifiedOn1586078471049modifiedByba7a9ee4-6de6-

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 43 di 49

44bc-b0b0-

6eb17dc63ca8usernullconfidence0999optimizationScorenullposition

0confidenceTagHnameSequence

0_20200405_085241406outcomeMoleculesnullproductMoleculenullpr

ojectId5e762b9648260b0001059324retrosynthesisId5e899c5948260b000

107d777sequenceIdnulllabelSequence

0complexityGraphnullfeedbacknullhasFeedbacknullisSavednullme

taDatanulltreeid5e899c5948260b000107d779metadataembed

computedFieldscreatedOn1586076761413createdByba7a9ee4-

6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1586078471003modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8moleculeId5e78717a48260b000105ecb4retrosynthesisId

5e899c5948260b000107d777sequenceId5e899c5948260b000107d778pr

ojectId5e762b9648260b0001059324smilesC(Cl)1CCCCC1confidence0

999rclassHydroxy to

chlorohasFeedbacknullfeedbacknullchildren[id5e89a30648260b00

0107d77emetadataembedcomputedFieldscreatedOn15860784

70989createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1586078470989modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8moleculeId5b7b0d80ec909700010e7a75retrosynthesisId

5e899c5948260b000107d777sequenceId5e899c5948260b000107d778pr

ojectId5e762b9648260b0001059324smilesClP(Cl)(Cl)(Cl)Clconfidence

10rclassUndefinedhasFeedbacknullfeedbacknullchildren[]metaD

ataborderColor28a30disExpandablefalseid5e89a30648260b00

0107d77fmetadataembedcomputedFieldscreatedOn15860784

70996createdByba7a9ee4-6de6-44bc-b0b0-

6eb17dc63ca8modifiedOn1586078470996modifiedByba7a9ee4-6de6-

44bc-b0b0-

6eb17dc63ca8moleculeId5b7b3cb0ec909700010e80aaretrosynthesisId

5e899c5948260b000107d777sequenceId5e899c5948260b000107d778pr

ojectId5e762b9648260b0001059324smilesOC1CCCCC1confidence10

rclassUndefinedhasFeedbacknullfeedbacknullchildren[]metaData

borderColor28a30disExpandablefalse]metaDatanullisExpandab

letrueisInteractivetrue]legend[]wizardParametersavailable_smiles

[]exclude_smiles[]exclude_substructures[]parametersmax_stepsla

belnulldescriptionnullvalue00nbeamslabelnulldescriptionnull

value00faplabelnulldescriptionnullvaluenullpruning_stepsla

belnulldescriptionnullvalue00availability_pricing_thresholdlabeln

ulldescriptionnullvalue10siblings[]metaDatanullmodelnullisI

nteractivetruemetadatauiMessageserrors[]infos[]warnings[]

extendedPagination

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 44 di 49

The entire process can be iterated until the domain experts decide it to be complete In this specific

example none of the children is expandable In the event where one of the children leaves is instead

expandable it is sufficient to iterate the API calls from 212 to 214 until desired (here above the

NODEID is highlighted in magenta)

The retrosynthesis is consequently updated in the web application under the user accountproject

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 45 di 49

215 Retrosynthesis retrieve queue status

URL BaseUrl +rxnapiapiv1retrosynthesisqueue-state

Method GET

2151 API response code

payload itemsInQueue 2 willBeCompletedOn null metadata uiMessages errors [] infos [] warnings [] extendedPagination

2152 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET

httpsrxnresibmcomrxnapiapiv1retrosynthesisqueue-state

Output

payloaditemsInQueue1willBeCompletedOn1585893597000metadat

auiMessageserrors[]infos[]warnings[]extendedPagination

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 46 di 49

216 Retrosynthesis retrieve PDF

URL BaseUrl +rxnapiapiv1retrosynthesisltRETROSYNTHESISIDgtsequenceslt

SEQUENCESIDgtdownload-pdf

Method GET

Mandatory fields

bull SEQUENCESID= this is the ID of the sequence returned by the

retrosynthesis API for which one wants to generate the PDF (es

5e788ae548260b770105ecf4)

bull RETROSYNTHESIS= this is the ID returned by the submission API of the

retrosynthesis (es 5e777d0b48260b134105bf2b)

2161 API response code

The answer to the API call contains the PDF (Content-type applicationpdf) in bytes

2162 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X GET -X GET

httpsrxnresibmcomrxnapiapiv1retrosynthesis5e777d0b48260b134105

bf2b sequences5e788ae548260b770105ecf4download-pdf

Output

PDF-14

ReportLab Generated PDF document httpwwwreportlabcom

1 0 obj

ltlt F1 2 0 R F2 4 0 R F3 6 0 R F4 7 0 R gtgt

endobj

2 0 obj

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 47 di 49

ltlt BaseFont Helvetica Encoding WinAnsiEncoding Name F1 Subtype

Type1 Type Font gtgt

endobj

3 0 obj

ltlt BitsPerComponent 8 ColorSpace DeviceRGB Filter [ ASCII85Decode

DCTDecode ] Height 180 Length 25441 Subtype Image

Type XObject Width 180 gtgt

stream

s4IA0_al8O`[ltE1+5ds8E6W-

=lt)6CQ+D54C2d`s+EfIl0H_cdF(oN)+A0q+AI7j)t51+=asEHP]+BlnVC4WlI50FIj7

(-

_eltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE

3ltE3ltE3ltE6$gAjSAltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE3ltE3

ltE3ltE3ltE3ltE3ltE3ltE3ltE3s1eUHQV43Zi^=Q3`5tbS6_uLkZ

6(ltE3ltltz-9eu7RLhGs24oFamp-)b4s8T-

sJi298EampIsBOElampg8tqqsjB9n14bR]U[_fkqn0BfEe4T)()If)C6^X-n-

Wamp2)[BQ3BBMq77Kdlt8P2oltElt1=^ltGASRgBkh^2F`qtRH$YrKnbA=M2II[PaQ

$R$jDUSO``Vl6SpZEppG[^WcW])A`Qsgtai`ampeCEfioB+]k3(smlLFHo_qPq

[hellip]

The PDF contains a human readable representation of that specific sequence

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 48 di 49

217 Paragraph to Actions

URL BaseUrl +rxnapiv1retrosynthesisparagraph-actions

Method POST

Mandatory fields

bull paragraph ldquotext describing a reciperdquo

2171 API response code

payload actionSequence ldquordquo metadatauiMessages errors[]infos[]warnings[]extendedPagination

2172 Example with curl

curl --header Content-Type applicationjson --header Authorizationapk-

have-here-your-own-key -X POST --data-binary paragraphTo a stirred

solution of 7-(difluoromethylsulfonyl)-4-fluoro-indan-1-one (110 mg 042 mmol)

in methanol (4 mL) was added sodium borohydride (24 mg 062 mmol) The

reaction mixture was stirred at ambient temperature for 1 hour Saturated

aqueous NH4Cl solution was added dropwise The mixture was extracted with

EtOAc The combined organic layers were washed with water and brine dried and

concentrated in vacuo to give 7-(difluoromethylsulfonyl)-4-fluoro-indan-1-ol (100

mg 90) which was used in the next step without further purification LCMS ESI

(+) mz 267 (M+H) ESI (u2212) mz 311 (Mu2212H+46)

httpsrxnresibmcomrxnapiapiv1retrosynthesisparagraph-actions

V

IBM RXN for Chemistry httpsrxnresibmcom

Page 49 di 49

Output

payloadactionSequenceltolgtltligtMAKESOLUTION with 7-

(difluoromethylsulfonyl)-4-fluoro-indan-1-one (110 mg 042 mmol) and methanol

(4 mL) ADD SLN ADD sodium borohydride (24 mg 062 mmol)ltligtltligtSTIR for 1

hour at ambient temperatureltligtltligtADD Saturated aqueous NH4Cl solution

dropwiseltligtltligtEXTRACT with EtOAcltligtltligtCOLLECTLAYER organic WASH with

water WASH with brine DRYWITHMATERIAL unknown CONCENTRATE YIELD 7-

(difluoromethylsulfonyl)-4-fluoro-indan-1-ol (100 mg

90)ltligtltligtNOACTIONltligtltolgtmetadatauiMessageserrors[]infos

[]warnings[]extendedPagination