The POST /ligand-detection endpoint allows you to update the ligand information you have for a previously registered structure in the database. It ensures ligands are correctly displayed and registered so the structure can be found through chemistry search.
You can use this endpoint anytime you find an error with a ligand in your structure, and you want to fix it without needing to delete and re-upload the corrected structure.
In this documentation, you will learn how this endpoint works and how to use it.
For a step-by-step Tutorial, refer to this page of the User Guide.
When you initiate ligand detection analysis, the following process occurs behind the scenes:
chem_comp_atom and chem_comp_bond categories store validated atom types and bond orders_chem_comp.model_details records which template type was used for the correction⚠️ Important: Ligand correction significantly improves structure quality by ensuring proper bond orders and chemical representation, but it will trigger automatic updates to related analyses including pocket detection, interaction registration, and mmCIF file generation. While this enhances search accuracy and database consistency, be aware that existing ligand annotations may need manual transfer to the new chemical entry, protein-ligand interactions will be recalculated, and previous search results based on the old ligand may no longer find this structure. These changes are intended improvements that ensure your structure data is scientifically accurate, though they may temporarily disrupt existing workflows - the benefits of having correct chemical data far outweigh any temporary inconveniences.
To use the ligand detection endpoint, you first need to access and activate the API (instructions in the Access page of this documentation).
To launch the ligand detection analysis, you need to use the API endpoint: POST /ligand-detection.
For a complete, step-by-step Tutorial, refer to this page of the User Guide.
externalCode: The structure external codetemplates: Array of ligand template objects defining the correct chemical structure. Each template requires:
residueCode: Three-letter ligand identifier from your structure (e.g., "LIG", "ATP")smiles: SMILES string representing the correct molecular structure with proper bond ordersinternalId: Internal compound database identifier (leave empty "" if not applicable)matchAndCorrect: Selective correction mode - When true, only corrects ligands that match your provided templates, leaving unmatched ligands unchanged. Useful for targeted fixes in multi-ligand structures (default = false)strictMatch: Quality assurance flag - When true, the operation fails if any provided template cannot be matched to a ligand in the structure, ensuring all expected corrections occur (default = false)commit: Database persistence control - Must be true to permanently save changes to the database. Set to false for validation runs without making actual modifications (default = false)NB. If templates is left empty, the system automatically tries to correct the ligands in the strucure with templates from the Chemical Component Dictionary and MOE-based inference from coordinates.
{
"externalCode": "ak5md7",
"templates": [
{
"residueCode": "LIG",
"smiles": "Clc1ccc(cc1)N2CCN(CC2)C(=O)C3=CC(=O)NC(=O)N3",
"internalId": ""
}
],
"matchAndCorrect": true,
"strictMatch": true,
"commit": true
}
curl -X POST "https://api.3decision.com/ligand-detection" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"externalCode": "ak5md7",
"templates": [
{
"residueCode": "LIG",
"smiles": "Clc1ccc(cc1)N2CCN(CC2)C(=O)C3=CC(=O)NC(=O)N3",
"internalId": ""
}
],
"matchAndCorrect": true,
"strictMatch": true,
"commit": true
}'
You can then check the status of the ligand detection analysis, using the API endpoint: GET /ligand-detection.
As an input, you need the structure external code.
If you get a "success" the analysis was successfully completed.
{
"state": "success",
"content": [
{
"small_mol_id": 144713,
"matching_template": "Clc1ccc(cc1)N2CCN(CC2)C(=O)C3=CC(=O)NC(=O)N3",
"residue_code": "LIG"
}
]
}