API reference

Molecular properties

Computed molecular properties from SMILES (formula, masses, cLogP, TPSA, Lipinski / Veber, PAINS / Brenk alerts), calculated on CogniChem servers. Free; structures are not sent to other services.

Compute molecular properties from SMILES

POST/api/v1/describe

API key or token

Formula, masses, cLogP, TPSA, H-bond counts, rings, charge, QED, Lipinski and Veber checks, and PAINS / Brenk alerts for up to 20 SMILES, in request order. A SMILES that cannot be described returns properties: null with an error code instead of failing the request. Values are computed on CogniChem servers and never sent to another service; they are calculated, not measured.

Request body

application/json · DescribeRequest

Request fields
Field	Type	Description
`smiles[]`required	`string[]`	Up to 20 SMILES (each 1-1000 characters). Limits: `min items 1, max items 20`

Example request

curl -X POST "https://api.cognichem.com/api/v1/describe" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "smiles": [
    "CC(=O)Oc1ccccc1C(=O)O"
  ]
}'

import os

import httpx

response = httpx.post(
    "https://api.cognichem.com/api/v1/describe",
    headers={"X-Api-Key": os.environ["COGNICHEM_API_KEY"]},
    json={"smiles": ["CC(=O)Oc1ccccc1C(=O)O"]},
)
response.raise_for_status()
print(response.json())

Uses httpx; the Python SDK has no method for this endpoint.

Responses

Successful Response · application/json · DescribeResponse

Response fields
Field	Type	Description
`items[]`required	`Description[]`
items.`error`	`string \| null`	unparseable: not valid SMILES. too_large: more than 200 heavy atoms. describe_failed: a property could not be computed. One of: `"unparseable", "too_large", "describe_failed"`
items.`properties`	`MolecularProperties \| null`
items.properties.`alerts`required	`StructuralAlerts`	RDKit FilterCatalog matches, by description.
items.properties.alerts.`brenk[]`required	`string[]`
items.properties.alerts.`pains[]`required	`string[]`
items.properties.`aromatic_rings`required	`integer`
items.properties.`clogp`required	`number`	Crippen cLogP.
items.properties.`formal_charge`required	`integer`	Net formal charge.
items.properties.`formula`required	`string`	Molecular formula (Hill order).
items.properties.`hba`required	`integer`	H-bond acceptors (Lipinski).
items.properties.`hbd`required	`integer`	H-bond donors (Lipinski).
items.properties.`heavy_atoms`required	`integer`
items.properties.`lipinski`required	`RuleCheck`	Rule of five: MW ≤ 500, cLogP ≤ 5, HBD ≤ 5, HBA ≤ 10; passes with at most one violation.
items.properties.lipinski.`pass`required	`boolean`	Within the rule.
items.properties.lipinski.`violations[]`required	`string[]`	Properties over their limit (mw, clogp, hbd, hba, tpsa, rotatable_bonds).
items.properties.`monoisotopic_mass`required	`number`	Monoisotopic (exact) mass, Da.
items.properties.`ms`	`MassSpecHints \| null`	Adduct m/z values and isotope pattern.
items.properties.ms.`adducts[]`required	`MsAdduct[]`	Common ESI adducts; empty for a charged structure.
items.properties.ms.`isotopes[]`required	`IsotopePeak[]`	First isotope peaks of the molecular formula (≥ 0.1%).
items.properties.`mw`required	`number`	Average molecular weight, g/mol.
items.properties.`qed`	`number \| null`	QED drug-likeness, 0-1; null if it cannot be scored.
items.properties.`rotatable_bonds`required	`integer`
items.properties.`tpsa`required	`number`	Topological polar surface area, Å².
items.properties.`veber`required	`RuleCheck`	TPSA ≤ 140 Å² and rotatable bonds ≤ 10.
items.properties.veber.`pass`required	`boolean`	Within the rule.
items.properties.veber.`violations[]`required	`string[]`	Properties over their limit (mw, clogp, hbd, hba, tpsa, rotatable_bonds).

Example 200 response

{
  "items": [
    {
      "properties": {
        "alerts": {
          "brenk": [
            "phenol_ester"
          ],
          "pains": []
        },
        "aromatic_rings": 1,
        "clogp": 1.31,
        "formal_charge": 0,
        "formula": "C9H8O4",
        "hba": 3,
        "hbd": 1,
        "heavy_atoms": 13,
        "lipinski": {
          "pass": true,
          "violations": []
        },
        "monoisotopic_mass": 180.0423,
        "mw": 180.159,
        "qed": 0.55,
        "rotatable_bonds": 2,
        "tpsa": 63.6,
        "veber": {
          "pass": true,
          "violations": []
        }
      }
    },
    {
      "error": "unparseable"
    }
  ]
}

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.