Utilities · Docs | CogniChem

A utility is a small, fast calculation, such as converting a molecule between formats or looking up a fluid property. Utilities differ from jobs in three ways:

No wallet charge. Each call counts toward your plan's monthly utility allowance instead (Plans and limits). At the limit, submits return 403 until the next month.
The answer comes back as data, not a zip file.
No estimate and no hardware choice.

Call a utility

Submit a utility process with a utility_type and its payload. It returns a process_id (utl-…).
Poll Get utility status until it finishes (usually seconds).
Read the answer from Get a utility result, then delete the process to clear it from your list.

The Python SDK does all three in one call:

from cognichem_client import CogniChem
 
client = CogniChem.from_env()
result = client.utils.run(
    "convert",
    {"input_data": "CCO", "input_format": "smiles", "output_format": "pdbblock"},
)
print(result.data)

As with jobs, calls made with an API key must send an Idempotency-Key (the SDK adds one for you).

Utility types

convert Convert one molecule or biopolymer between text formats (RDKit).

Payload fields
Field	Type	Description
`input_data`required	`string`	Limits: `min length 1`
`input_format`required	`string`	One of: `"fasta", "helm", "mol2block", "molblock", "mrvblock", "pdbblock", "scsrblock", "selfies", "sequence", "smarts", "smiles", "tplblock", "xyzblock", "inchi"`
`output_format`required	`string`	One of: `"inchi", "inchikey", "cmlblock", "cxsmarts", "cxsmiles", "fasta", "helm", "molblock", "mrvblock", "pdbblock", "selfies", "sequence", "smarts", "smiles", "tplblock", "v2kmolblock", "v3kmolblock", "xyzblock"`
`generate_3d`	`boolean`	Embed 3D coordinates before writing. Default: `false`
`add_hydrogens`	`boolean`	Add explicit hydrogens. Default: `false`
`remove_hydrogens`	`boolean`	Remove explicit hydrogens. Default: `false`

coolprop Single-state thermophysical property lookup (CoolProp HEOS or INCOMP; SI units). Give two state inputs, or a single T or P for saturation. For grids or curves submit the coolprop job.

Payload fields
Field	Type	Description
`fluid`required	`string`	CoolProp fluid name, e.g. Water. REFPROP is not supported. Limits: `min length 1, max length 128`
`backend`	`string`	Default: `"HEOS"`One of: `"HEOS", "INCOMP"`
`inputs`required	`object`	State inputs in SI units (T in K, P in Pa, H in J/kg, S in J/kg/K, D in kg/m^3, Q quality 0-1).
inputs.`T`	`number`
inputs.`P`	`number`
inputs.`H`	`number`
inputs.`S`	`number`
inputs.`D`	`number`
inputs.`Q`	`number`
`properties[]`	`string[]`	One of: `"A", "C", "Cp0mass", "Cpmass", "Cvmass", "D", "H", "P", "PIP", "Prandtl", "Q", "S", "T", "U", "conductivity", "dmass", "dmolar", "hmass", "hmolar", "phase", "smass", "smolar", "speed_of_sound", "surface_tension", "umass", "umolar", "viscosity"`Limits: `min items 1, max items 32`

druglikeness_filter Lipinski / Veber rules and structural alerts (PAINS, Brenk, NIH) for up to 50 molecules. For larger sets submit the druglikeness-filter job.

Payload fields
Field	Type	Description
`input_data`required	`string \| string[]`
`input_format`required	`string`	One of: `"inchi", "molblock", "smiles"`
`apply_lipinski`	`boolean`	Apply Lipinski rule of five. Default: `true`
`apply_veber`	`boolean`	Apply Veber rules. Default: `true`
`alert_sets[]`	`string[]`	Default: `["pains","brenk","nih"]`One of: `"brenk", "nih", "pains"`
`qed_min`	`number`	Limits: `≥ 0, ≤ 1`
`sa_max`	`number`	Limits: `≥ 1, ≤ 10`

molecule_rmsd RMSD between two molecular structures after alignment (and optional atom reordering).

Payload fields
Field	Type	Description
`input_data_1`required	`string`	Limits: `min length 1`
`input_format_1`required	`string`	One of: `"fasta", "helm", "mol2block", "molblock", "mrvblock", "pdbblock", "scsrblock", "selfies", "sequence", "smarts", "smiles", "tplblock", "xyzblock", "inchi"`
`input_data_2`required	`string`	Limits: `min length 1`
`input_format_2`required	`string`	One of: `"fasta", "helm", "mol2block", "molblock", "mrvblock", "pdbblock", "scsrblock", "selfies", "sequence", "smarts", "smiles", "tplblock", "xyzblock", "inchi"`
`rotation_method`	`string`	Default: `"kabsch"`One of: `"kabsch", "quaternion"`
`reorder_method`	`string`	Default: `"inertia-hungarian"`One of: `"inertia-hungarian", "qml"`
`add_hydrogens`	`boolean`	Add explicit hydrogens. Default: `false`
`remove_hydrogens`	`boolean`	Remove explicit hydrogens. Default: `false`

molecule_standardize Standardize one molecule (largest fragment, uncharge, canonical tautomer, stereo cleanup).

Payload fields
Field	Type	Description
`input_data`required	`string`	Limits: `min length 1`
`input_format`required	`string`	One of: `"inchi", "molblock", "sdf", "smiles"`
`largest_fragment`	`boolean`	Keep the largest fragment. Default: `true`
`uncharge`	`boolean`	Neutralize charges where possible. Default: `true`
`canonical_tautomer`	`boolean`	Pick the canonical tautomer. Default: `true`
`cleanup_stereo`	`boolean`	Clean up stereochemistry. Default: `true`

For larger inputs, several utilities have a job counterpart that runs in the background: Molecule Conversion (convert-batch), Molecule Standardizer (molecule-standardize), and Drug-likeness & Structural Alerts (druglikeness-filter).