Using the APIs directly

As mentioned in the [ASKCOS Overview](01 ASKCOS Overview), in ASKCOSv2, the frontend and the backend are fully separated. It is possible to query the backend APIs directly through the API gateway (and straight to the backend services if you know what you're doing). This might be particularly relevant in some settings, such as for batch jobs. By default, the interactive documentation is accessible at http://0.0.0.0:9100/docs once ASKCOS has been deployed.

As the documentation is automatically generated via FastAPI, it is guaranteed to be up-to-date. The endpoints have been organized by groups and many have been pre-filled with working sample queries. The most commonly used include forward, retro and tree-search. Here we will run a sample query with tree-search. Firstly, click on tree-search to expand the group and see the available endpoints.

Further expanding on the POST /api/tree-search/mcts/call-sync-without-token shows a short description of the endpoint as well as the sample query. Note: Here we selected the call-sync-without-token endpoint rather than the typical call-sync, as the latter requires authentication. Click on Try it out.

This will make the sample query editable so that parameters can be changed. We don't need to modify anything for this example. Click on Execute, which should send the API to the backend and return the results after 10 seconds, the time limit set for this sample query.

The above is the first part of the returned data which includes the actual CURL command used. This command that can be copied and executed from any terminal to reproduce the call. Scroll a little bit down and you will see the actual response.

Python script examples for API queries

If you are unfamiliar with APIs, we have provided some python examples in the askcos2_core repo. They do require the requests package, which is pip installable and also a pre-requisite as mentioned in the [introduction](01 Introduction). The logic is pretty straightforward in these sample .py scripts. Simply create a query template and send it with different target SMILES and other options each time. Feel free to modify them for your own use. For the sample scripts below, you'd need to change the HOST and PORT (which are set to 0.0.0.0 and 9100 by default) in the script to point to your actual host and port.

• To run a mcts tree search batch job on 100 test molecules

$ cd askcos2_core
$ python examples/mcts_query.py

These searches will take a while but can be interrupted at any time.

• To run a sample query for one-step retrosynthesis

$ cd askcos2_core
$ python examples/retro_query.py

• To run a sample query for reaction outcome prediction

$ cd askcos2_core
$ python examples/forward_query.py

• To run a sample query for reaction context recommendation

$ cd askcos2_core
$ python examples/context_recommendation_query.py

Using the APIs which require authentication

There are a few APIs which require authentication, such as /api/tree-search/expand-one/call-sync. In general we try to provide the equivalent non-authenticated endpoints (e.g., /api/tree-search/expand-one/call-sync-without-token). In case there is no equivalent endpoint, we can request a token and then send that token along with the query, as in a typical OAuth 2.0 workflow.

• Request a token from the /api/admin/token endpoint

Only the username and the password are needed, which would be the same as if there were used to log in the web interface. This translates to a sample CURL request

$ curl -X 'POST' \
  'http://you.got.the.ips:port/api/admin/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=&username=your_user&password=your_password&scope=&client_id=&client_secret='

which will return the token in the response

{
  "access_token": "your_token_as_a_long_string",
  "token_type": "bearer"
}

• Send the token in the header along with the query body to the endpoint

$ curl -X 'POST' \
  'http://you.got.the.ips:port/api/tree-search/expand-one/call-sync' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'cookie: access_token=bearer your_token_as_a_long_string;' \
  -d '{
  "smiles": "CN(C)CCOC(c1ccccc1)c1ccccc1",
  "retro_backend_options": [
    {
      "retro_backend": "template_relevance",
      "retro_model_name": "reaxys",
      "max_num_templates": 1000,
      "max_cum_prob": 0.995,
      "attribute_filter": [],
      "threshold": 0.3,
      "top_k": 10
    }
  ],
  "banned_chemicals": [],
  "banned_reactions": [],
  "use_fast_filter": true,
  "fast_filter_threshold": 0.75,
  "retro_rerank_backend": "relevance_heuristic",
  "cluster_precursors": false,
  "cluster_setting": {
    "feature": "original",
    "cluster_method": "hdbscan",
    "fp_type": "morgan",
    "fp_length": 512,
    "fp_radius": 1,
    "classification_threshold": 0.2
  },
  "extract_template": false,
  "return_reacting_atoms": true,
  "selectivity_check": false,
  "group_by_strategy": false
}'

Note how the token is passed in the last header (-H). We have switched to cookie-based authentication so that the access token needs to be sent in the cookie (remember the semi-colon at the end!), rather than in the more typical Authentication header. The endpoint should return the desired output if the token is succesfully verified from the backend.

We have similarly prepared a sample query script for endpoints requiring authentication.

$ cd askcos2_core
$ ASKCOS_USERNAME=your_username ASKCOS_PASSWORD=your_password python examples/mcts_query_async.py

This specific script sends asynchronous queries which are queued (to be executed 1 by 1 or a few by a few). Result entries will be immediately viewable from My Results at the frontend; the actual results will be ready as soon as each queued job is completed.