M1 RetroScore API User Guide

Getting started

Create a search

Request

POST

http://localhost:2222/api/v2/batch-search

Body application/json

#targets

array of strings

required

Target chemical compounds in SMILES format.

Example value: ["COC", "OCC(N)(CO)CCc1ccc(cc1)CCCCCCC"]

Maximum length: 100 000

#detail_level

'best_path' | 'all_paths'

optional

Controls detail level of system output. Possible values:

best_path - return the best synthetic pathway and its properties: score, price of starting materials and number of steps.
all_paths - if specified, the system will include the best found synthesis pathway and alternative pathways that can be viewed in SciFinderⁿ.

Default value: 'best_path'

#invalid_target_strategy

'reject' | 'pass'

optional

If set to 'pass', targets that cannot be canonized by our SMILES parser won't cause the whole search request to be rejected.

Default value: 'reject'

#name

string

optional

Name of the search search.

Default value: part of the generated search ID

#parameters

dictionary

optional

Additional parameters to further configure the search request. Overrides parameters defined by preset.

#availability_tier

integer

optional

Limits starting materials to those that fulfill the availibility criteria of the specified tiers:

1 - All starting materials ship in 1-5 business days.
2 - All starting materials ship in 2-10 business days.
3 - All starting materials ship within 4 weeks.
4 - Starting materials may require synthesis and are usually shipped within 12 weeks.
5 - Starting materials require custom quote (POA).

Default value: 3

#length

'regular' | 'short'

optional

Defines how long the search is running and for how many different intermediate compounds the system proposes reactions leading to them. 'short' search is sufficient for compounds where you expect the synthetic pathway to be no longer than 5 steps.

Default value: 'short'

#model

'metro' | 'transformer'

optional

Machine Learning model used.

'metro' - Fast, template based system. Reactions generated by this system are almost always supported by literature references. Results have high quality, although they cover only commonly used chemistry.
'transformer' - System that utilizes transformer architecture to propose reactions. It yields both diverse and robust results although it's slower than other systems.

Default value: 'transformer'

#synthesis_scale

'kilogram' | 'molar' | 'millimolar' | 'micromolar'

optional

The amount of compound that the system optimizes the synthesis for. Higher scale will result in a longer synthetic pathway, starting at cheaper starting materials.

Default value: 'millimolar'

#reaction_confidence_threshold

'high' | 'low'

optional

Reaction confidence threshold.

'high' - High threshold reduces the number of possible pathways, ensuring that only the most certain reactions are included.
'low' - Low threshold expands the pool of possible pathways, offering more diversity but risking the inclusion of incorrect reactions.

Default value: 'high'

#min_reference_count

integer

optional

Minimum reference count.

Minimum number of references citing similar reaction center and mechanism. Higher values favor well-documented and commonly used reactions (potentially excluding those with uncommon reaction centers).

Note: Setting this parameter to 0 may include reactions without any literature backing. Additionally, when reaction_confidence_threshold is set to 'low', this may lead to the inclusion of multiple incorrect reactions. We strongly recommend setting this to 1 or higher.

Default value: 10

Range: 0 - 1000

#preset

string

optional

Enables the usage of the parameter sets created in the RetroScore web application. The value is the unique name specified during parameter set creation.

Example value: "base-parameters"

Default value: synthesis plan parameters chosen as "Default for API" in the RetroScore interface

#priority

integer

optional

Use the priority attribute in order to prioritize some jobs over other ones. Higher value translates to higher priority.

Range: 1 - 10

Default value: 5

#targets_metadata

nested dictionary

optional

Targets metadata enables the naming of some compounds of the request. Each key of the parent dictionary should relate to an index of a target in the targets array. Please note that the indices are numbered from 0. As naming compounds is optional, targets_metadata should only contain the keys of targets that you want to name.

Example value: {"0": {"name": "Dicarbon monoxide"}}

Example

curl http://localhost:2222/api/v2/batch-search -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiToken-v1 YOUR_API_TOKEN" \
  -d '{
    "targets": [
      "OCC(N)(CO)CCc1ccc(cc1)CCCCCCC",
      "O=C(Nc1cc(Nc2nc(-c3cnccc3)ccn2)c(cc1)C)c3ccc(cc3)CN3CCN(CC3)C",
      "COC"
    ],
    "detail_level": "best_path",
    "invalid_target_strategy": "reject",
    "name": "my-search",
    "parameters": {
      "availability_tier": 3,
      "length": "short",
      "model": "metro",
      "synthesis_scale": "millimolar",
      "reaction_confidence_threshold": "high",
      "min_reference_count": 10
    },
    "preset": "base-parameters",
    "priority": 3,
    "targets_metadata": { "2": { "name": "Dicarbon monoxide" } }
  }'

Response

Body application/json

#id

string

Search ID.

#name

string

Search name.

Default value: part of the generated search ID if not specified in request

#size

integer

Number of targets specified in the search request.

#inputParams

dictionary

parameters specified in the search request.

#searchParams

dictionary

Final parameters used to create the search request. They are a combination of inputParams and presetParams.

#priority

integer

priority specified in the search request or its default value.

#createdAt

string

Search created date and time as an ISO 8601 formatted string.

#source

'WEB' | 'API_V2'

Origin of the search request.

#presetParams

dictionary

Parameters specified by chosen preset in the search request.

Default value: "Default for search" preset configured in the RetroScore interface

#presetName

string

Name of the preset applied to the search request.

Example

{
  "id": "bcd34242-70c3-46f0-819d-e261eaf876f0",
  "name": "my-search",
  "size": 3,
  "inputParams": {
    "availability_tier": 3,
    "length": "short",
    "model": "metro",
    "synthesis_scale": "millimolar",
    "reaction_confidence_threshold": "high",
    "min_reference_count": 10
  },
  "searchParams": {
    "detail_level": "best_path",
    "presets": {
      "model": "metro",
      "length": "short",
      "datasets": [{ "id": "emolecules" }],
      "synthesis_scale": "millimolar",
      "availability_tier": 3,
      "reaction_confidence_threshold": "high",
      "min_reference_count": 10
    }
  },
  "priority": 3,
  "createdAt": "2023-04-07T10:13:29.932Z",
  "source": "API_V2",
  "presetParams": {
    "availability_tier": 3,
    "datasets": [{ "id": "emolecules" }],
    "model": "metro",
    "length": "regular",
    "synthesis_scale": "millimolar",
    "reaction_confidence_threshold": "high",
    "min_reference_count": 10
  },
  "presetName": "base-parameters"
}