Cheminformatics

RDKit API

Molecule properties, standardization and substructure search, and explicit bond edits from atom-mapped reactions.

RDKit is the open-source cheminformatics toolkit. Given SMILES or an SD file, a run reports canonical structures with descriptors, Lipinski counts, standardized parent forms, InChI, molecule hashes, Murcko scaffolds, ring and stereochemistry analysis, SMARTS substructure matches, fingerprints and the maximum common substructure of the set. Given atom-mapped reaction SMILES, it reports the reaction's participants, its element and formal-charge balance, the quality of its atom mapping, and the bonds formed, broken or changed in order -- the reaction centre a precedent search or an enzyme design starts from.

Web form Documentation ↗ Input parameters ↗ Examples ↗ Home page ↗ Source code ↗ License ↗

Submit POST /api/rdkit/

Queues a run and returns 202 with the job.

Schema GET /api/rdkit/

Returns this tool's metadata and the fields below, as JSON.

Input method

Set input_mode to choose how inputs are supplied. Only fields for the selected method are used.

text: Enter SMILES
upload: Upload a file

Example presets

Send {"preset": "descriptors"} to load an example and its bundled inputs. Add other request fields to override its settings. The schema includes all presets under tool.presets.

preset	Description
`descriptors`	The molecules RDKit's Getting Started guide reads and draws -- benzoic acid, toluene, cyclobutane, phenol, oxirane, a staurosporine aglycone and sucrose -- through the common descriptor set, with InChIKeys for matching them against a database. Source ↗
`murcko_scaffolds`	The four molecules the Cookbook's scaffold recipe decomposes, reported with their Bemis-Murcko scaffolds, the generic form of each, and the molecule hashes that say which of them share a framework. Source ↗
`nitrile_substructure`	The Cookbook's functional-group recipe: the nitrile pattern [NX1]#[CX2] matched against butyronitrile and benzonitrile, and against an amide and an amine that are not nitriles, so a match and a non-match are both visible in the table. Source ↗
`mcs_and_fingerprints`	The three molecules Getting Started runs rdFMCS.FindMCS over, with Morgan fingerprints at radius 2 beside the table. The maximum common substructure is one answer for the whole set and is reported in the run's JSON rather than as a column. Source ↗
`oxidations`	The three oxidations Getting Started uses as reaction examples, atom-mapped so the bond edits can be read off: each turns a C-O single bond into a double bond, which is what the reaction centre reports. None of them names the oxidant that takes the two hydrogens, so each is also flagged as not element-balanced -- which is exactly what the balance check is for. Source ↗
`ester_hydrolysis`	Methyl acetate and water to acetic acid and methanol, fully atom-mapped: a reaction that is element- and charge-balanced, whose mapping is complete, and whose bond edits are therefore reliable. A useful reference for what a well-formed mapped reaction looks like. Source ↗

Tasks

Pick a mode with `task`

Fields belonging to another task are ignored, so send only the ones for the task you chose.

task	Mode
`molecule` default	Molecule
`reaction`	Reaction

Request body

Fields

The same names the web form posts. See the field type table for what each kind means over HTTP.

Name	Type	Required	Default	Description
`job_name`	string text	no	`rdkit-demo`	Job name Names the table this run leaves: <job name>.csv. up to 80 characters.
`smiles` molecule	string textarea	yes	`CC(=O)OC1=CC=CC=C1C(=O)O aspirin CN1C=NC2=C1C(=O)N(C)C(=O)N2C caffeine CC(C)Cc1ccc(cc1)C(C …`	Molecules One molecule per line, in the format RDKit's SmilesMolSupplier reads: a SMILES string, then optionally whitespace and a name. Lines beginning with # are ignored. Up to 5000 molecules and 200,000 characters per run. In this form: A molecule RDKit cannot parse is reported as a row with an error rather than failing the run, so one bad line in a list does not lose the rest. up to 200000 characters.
`reaction_smiles` reaction	string textarea	yes	`[CH3:1][C:2](=[O:3])[O:4][CH3:5].[OH2:6]>>[CH3:1][C:2](=[O:3])[OH:6].[OH:4][CH3:5] methyl- …`	Reactions One reaction per line as reactants>>products, or reactants>agents>products, then optionally whitespace and a name. Atom maps are required for reliable bond-edit extraction: every atom should be mapped exactly once per side. Up to 1000 reactions per run. up to 200000 characters.
`inputs_file`	string file	no	`—`	Molecule or reaction file Upload a SMILES list (.smi, .txt, .csv) or an SD file (.sdf, .mol); an SD file is recognised by its own connection table and read with RDKit's SDMolSupplier, keeping the _Name field as each molecule's name. For the reaction task, upload one reaction SMILES per line. file types .smi,.smiles,.csv,.txt,.sdf,.mol,.rxn.
`descriptor_set` molecule	string select	no	`common`	Descriptors The common set is formula, molecular weight and exact mass, cLogP, TPSA, hydrogen-bond donors and acceptors, rotatable bonds, rings, aromatic rings, heavy atoms, fraction of sp3 carbons, formal charge and the number of Lipinski rule-of-five violations. Every descriptor is RDKit's own Descriptors.CalcMolDescriptors, which is upwards of two hundred columns. One of: `common`, `all`, `none`.
`standardize` molecule	boolean checkbox	no	`false`	Standardized parent forms Adds the four rdMolStandardize parents as columns: cleanup, fragment parent (the largest fragment), charge parent (neutralized) and tautomer parent. Useful as search keys; keep the original charged, stereospecific molecule for anything that has to account for mass or charge.
`include_inchi` molecule	boolean checkbox	no	`false`	InChI and InChIKey Adds InChI and InChIKey columns, when the RDKit build includes InChI support. The InChIKey is the usual key for matching a molecule across databases.
`hashes` molecule	boolean checkbox	no	`false`	Molecule hash strings Adds the rdMolHash strings from the Cookbook's molecule-hash recipe: canonical SMILES, the tautomer-insensitive HetAtomTautomer hash, the Murcko scaffold hash, the anonymous graph and the net charge. Two molecules that agree on a hash are the same under that hash's notion of sameness.
`murcko_scaffold` molecule	boolean checkbox	no	`false`	Murcko scaffold Adds the Bemis-Murcko scaffold (the ring systems and the linkers between them, with side chains removed) and its generic form, where every atom becomes carbon and every bond single.
`ring_analysis` molecule	boolean checkbox	no	`false`	Rings and aromaticity Adds the number of rings in the symmetrized smallest set of smallest rings, the number of ring systems (fused rings counted once), the number of aromatic rings and the number of aromatic atoms.
`stereo` molecule	boolean checkbox	no	`false`	Stereochemistry Adds the stereocentres and stereo bonds RDKit's FindPotentialStereo finds, and how many of them are unspecified in the input -- which is what says whether a SMILES string names one stereoisomer or a family of them.
`substructure_smarts` molecule	string text	no	`—`	Substructure query (SMARTS) A SMARTS pattern matched against every molecule, as in the Cookbook's functional-group recipes: for example [NX1]#[CX2] for a nitrile or [CX3](=O)[OX2H1] for a carboxylic acid. Adds the number of matches and the atom indices of the first one. Leave empty to skip. up to 2000 characters.
`find_mcs` molecule	boolean checkbox	no	`false`	Maximum common substructure Runs rdFMCS.FindMCS across every molecule that parsed and reports the largest substructure they all share, as SMARTS, with its atom and bond counts. This is one answer for the whole set rather than a column, so it is reported in the run's JSON rather than the table. Needs at least two molecules.
`mcs_timeout` molecule	number number	no	`20`	MCS timeout (seconds) rdFMCS.FindMCS's own timeout. A search that runs out of time still returns the largest substructure it had found, flagged as having timed out. minimum 1, maximum 600.
`fingerprint` molecule	string select	no	`none`	Fingerprint Adds a fingerprint column as a bit string, through rdFingerprintGenerator. Morgan with radius 2 is the usual ECFP4 analogue. MACCS keys are a fixed 166-bit set and ignore the size and radius below. One of: `none`, `morgan`, `rdkit`, `atom_pair`, `topological_torsion`, `maccs`.
`fingerprint_bits` molecule	number number	no	`2048`	Fingerprint size (bits) The folded length of the fingerprint. Ignored for MACCS keys. minimum 32, maximum 16384.
`fingerprint_radius` molecule	number number	no	`2`	Morgan radius How far from each atom the Morgan environment reaches. Radius 2 corresponds to ECFP4. Used only by the Morgan fingerprint. minimum 1, maximum 6.
`reaction_participants` reaction	boolean checkbox	no	`true`	Per-participant summaries Reports each reactant, agent and product on its own: canonical SMILES, formula, formal charge, and how many of its atoms carry a map number.
`reaction_balance` reaction	boolean checkbox	no	`true`	Element and charge balance Counts every element, implicit hydrogens included, and the formal charge on each side, and reports the difference. Agents are excluded from the count, as they are from the bond edits.
`reaction_bond_edits` reaction	boolean checkbox	no	`true`	Bonds formed, broken and changed Compares the mapped bonds on each side and reports the bonds formed, the bonds broken, the bonds whose order changed, and the atom maps making up the reaction centre. Only reliable when the atom mapping is complete, which is reported alongside it.

Example

A request that runs

These are the defaults, exactly as the web form would post them.

curl -X POST https://athanortools.com/api/rdkit/ \
  -H 'Content-Type: application/json' \
  -d '{
  "task": "molecule",
  "input_mode": "text",
  "job_name": "rdkit-demo",
  "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O aspirin\nCN1C=NC2=C1C(=O)N(C)C(=O)N2C caffeine\nCC(C)Cc1ccc(cc1)C(C)C(=O)O ibuprofen\nCC(=O)Nc1ccc(O)cc1 paracetamol\n",
  "descriptor_set": "common",
  "standardize": false,
  "include_inchi": false,
  "hashes": false,
  "murcko_scaffold": false,
  "ring_analysis": false,
  "stereo": false,
  "substructure_smarts": "",
  "find_mcs": false,
  "mcs_timeout": 20,
  "fingerprint": "none",
  "fingerprint_bits": 2048,
  "fingerprint_radius": 2
}'

The reply is 202 with a queued job; poll its status_url until status is succeeded or failed. See the quick start for the whole exchange.

Responses

What comes back

status	Meaning
`queued`	Accepted, waiting for the jobs ahead of it. `position` counts how many those are.
`running`	The tool is executing now.
`succeeded`	Finished; `result` holds the tool's output and `license` the terms it came under.
`failed`	Finished; `error` holds a code and a message.
`cancelled`	Abandoned at the submitter's request; there is no result. A job cancelled before its turn never ran at all.

Errors

code	Meaning
`invalid_input`	The client supplied invalid or incomplete input.
`tool_unavailable`	The requested third-party dependency is not available on this host.
`execution_failed`	A configured third-party tool exited unsuccessfully.
`internal_error`	An adapter failed in a way it does not describe. The detail is in the server log, not the response.
`not_found`	No job has that id. Finished jobs are dropped eventually.