API quickstart

The recommended CHEESE API operation finds structural neighbors with ECFP4/Tanimoto scoring. It needs only a query molecule, chemical-space ID, and result count.

1. Set your API key

Create or copy a key in CHEESE account settings, then keep it in an environment variable. Never put keys in source code, notebooks committed to Git, or URLs.

export DMC_API_KEY='your-key'

The API base URL is https://api.deepmedchem.com. The interactive OpenAPI explorer for every v2 operation is served by the API itself at /api/v2/docs.

2. Search

curl --request POST 'https://api.deepmedchem.com/api/v2/search' \
  --header "x-api-key: $DMC_API_KEY" \
  --header 'content-type: application/json' \
  --data '{
    "query_smiles": "CC(=O)Nc1ccc(O)cc1",
    "database_id": "enamine-real-v5a",
    "limit": 20
  }'

Response

Truncated to the first hit. Result fields that stay null unless you opt into them (synthons, properties, ADMET and constraint evidence) are omitted here; see the endpoint reference for the complete schema.

{
  "request_id": "b30f5ad2-6ef0-4848-ad54-b24a572ca956",
  "query_smiles": "CC(=O)Nc1ccc(O)cc1",
  "database_id": "enamine-real-v5a",
  "database_release": "2026-08-29.1",
  "model_version": "rdkit-ecfp4-r2-n2048",
  "engine_version": "0.2.0",
  "scorer": "morgan",
  "metric": "ECFP4 Tanimoto",
  "shortlist_multiplier": 10,
  "effective_shortlist": 200,
  "results": [
    {
      "rank": 1,
      "smiles": "CC(=O)Nc1ccc(-c2ccc(O)cc2)cc1",
      "score": 0.8695652173913043,
      "metric": "ECFP4 Tanimoto",
      "proposal_score": 0.800000011920929,
      "product_id": "e0bf2c7e96e522ae7ad32e92",
      "reaction_id": "s_271570"
    }
  ],
  "counts": {
    "proposed": 200,
    "assembled": 200,
    "invalid": 0,
    "duplicate_tuples": 0,
    "duplicate_products": 33,
    "returned": 20
  },
  "timing_ms": {
    "query": 0.48,
    "proposal": 410.14,
    "assembly_and_scoring": 50.99,
    "total": 461.61
  },
  "warnings": []
}

score is exact assembled-product ECFP4 Tanimoto. proposal_score is an acquisition signal and is not interchangeable with the final score. Save database_release, engine/model versions, and the request body when reproducibility matters.

counts.returned can be lower than limit: proposals that assemble to the same canonical product are deduplicated (duplicate_products above), and small query molecules deduplicate heavily. Raise shortlist_multiplier if you need a full page.

Choose the next operation