This tutorial demonstrates how to use the 3decision API to perform a pocket similarity search. The pocket similarity search helps identify pockets with similar geometric and physicochemical properties across different structures.
This analysis is useful for:
The tutorial covers authentication, structure identification, pocket selection, and executing the similarity search.
⚠️ API Version Notice: This tutorial includes instructions for both API versions ≤2.2 and version 2.3+. Look for the version-specific sections marked with 📌.
To access the 3decision API endpoints, follow these steps to set up authentication:
GET /auth/api/loginTo identify the query structure, you can use several search methods. Each matching structure will return a structure_id.
Search for a PDB code (e.g. 8h4r) or 3decision structure code (e.g. hfzbcu) using:
GET /search/{query}/exact-match/sync?mode=STRUCTURE_CODE
Note: Use lowercase codes for this API call.
curl -X 'GET' \
'https://3decision-[customer]-api.discngine.cloud/search/8h4r/exact-match/sync?mode=STRUCTURE_CODE' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer ey*********W8'
{
"STRUCTURE_ID": [
789192
],
"number_of_hits": 1
}
Search using a UniProt code (e.g. CDK3_HUMAN) or gene name (e.g. CDK3):
GET /search/{query}/exact-match/sync?mode=BIOMOL_CODEGET /search/{query}/exact-match/sync?mode=GENE_NAMEcurl -X 'GET' \
'https://3decision-[customer]-api.discngine.cloud/search/CDK3_HUMAN/exact-match/sync?mode=BIOMOL_CODE' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer ey*********W8'
{
"STRUCTURE_ID": [
773550,
789192,
800591
],
"number_of_hits": 3
}
There are two methods to identify a pocket of interest and get the required information for the pocket similarity search.
📌 What you need to collect:
- API ≤2.2:
cavityId(internal pocket ID) +pocket residues- API 2.3+:
external_code(e.g. "8h4r") +pocket residues
This method is suitable when you want to use a pocket that contains a ligand of interest.
Retrieve all ligands in a structure using the API endpoint GET /structures/info/ligand. Use the structure_id retrieved in step 2 as input (e.g. 789192). The call can also be made for multiple structures at once. See examples below.
⚠️ Deprecation Notice (API 2.3+): The
bond_orderandligand_2d_similarity_vs_ref_smiparameters are deprecated and will be removed in version 2.4.0. You can omit these parameters in your requests.
curl -X 'GET' \
'https://3decision-[customer]-api.discngine.cloud/structures/info/ligand?structure_id=789192&bond_order=true&remove_non_drug_like_ligands=true&ligand_2d_similarity_vs_ref_smi=false' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********htE'
curl -X 'GET' \
'https://3decision-[customer]-api.discngine.cloud/structures/info/ligand?structure_id=773550&structure_id=789192&structure_id=800591&bond_order=true&remove_non_drug_like_ligands=true&ligand_2d_similarity_vs_ref_smi=false' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********htE'
[
{
"STRUCTURE_ID": 789192,
"LIGANDS_INFO": [
{
"NUMRINGS": 1,
"SINGL_BOND_FRACTION": 0.8333333333333334,
"isDruglike": true,
"small_mol_id": 87397,
"Data": {
"SMALL_MOL_ID": 87397,
"EXTERNAL_CODE": "8h4r",
"STR_RESIDUE_NUMBER": 406,
"RESIDUE_CODE": "MES",
"MW": 195.23,
"NUMRINGS": 1,
"SINGL_BOND_FRACTION": 0.8333333333333334,
"isDruglike": true,
"CTAB": "\n RDKit 2D\n\n 12 12 0 0 0 0 0 0 0 0999 V2000\n 6.7500 -1.2990 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 5.2500 -1.2990 0.0000 S 0 0 0 0 0 0 0 0 0 0 0 0\n 5.2500 -2.7990 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 5.2500 0.2010 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 3.7500 -1.2990 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 3.0000 0.0000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 1.5000 0.0000 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n 0.7500 -1.2990 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -0.7500 -1.2990 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -1.5000 0.0000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n -0.7500 1.2990 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.7500 1.2990 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 1 2 1 0\n 2 3 2 0\n 2 4 2 0\n 2 5 1 0\n 5 6 1 0\n 6 7 1 0\n 7 8 1 0\n 8 9 1 0\n 9 10 1 0\n 10 11 1 0\n 11 12 1 0\n 12 7 1 0\nM END\n",
"SMILES": "OS(=O)(=O)CCN1CCOCC1"
},
"ligandConformations": [
{
"SMALL_MOL_ID": 87397,
"SMALL_MOL_CONF_ID": 5830048,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "B",
"STR_RESIDUE_NUMBER": 406,
"RESIDUE_CODE": "MES",
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/1/N:3,5,7,2,6,8,4,10,11,12,1,9/E:(1,2)(4,5)(8,9,10)/CRV:12.6/rA:12OCCN+CCCCSO-OO/rB:s1;s2;s3;s4;s1s5;P4;s7;s8;P9;d9;d9;/rC:7.899,-58.302,8.057;7.747,-56.894,8.158;9.034,-56.178,7.833;9.545,-56.567,6.479;9.597,-58.056,6.353;8.268,-58.656,6.732;10.89,-55.956,6.215;10.797,-54.605,5.531;12.218,-53.572,5.819;13.287,-54.452,6.206;12.48,-52.906,4.574;11.838,-52.662,6.866;"
}
]
},
{
"NUMRINGS": 0,
"SINGL_BOND_FRACTION": 0.5,
"isDruglike": false,
"small_mol_id": 87402,
"Data": {
"SMALL_MOL_ID": 87402,
"EXTERNAL_CODE": "8h4r",
"STR_RESIDUE_NUMBER": 402,
"RESIDUE_CODE": "SO4",
"MW": 96.06,
"NUMRINGS": 0,
"SINGL_BOND_FRACTION": 0.5,
"isDruglike": false,
"CTAB": "\n RDKit 2D\n\n 5 4 0 0 0 0 0 0 0 0999 V2000\n 0.0000 0.0000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1.2990 0.7500 0.0000 S 0 0 0 0 0 0 0 0 0 0 0 0\n 2.0490 -0.5490 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 0.5490 2.0490 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 2.5981 1.5000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1 2 1 0\n 2 3 2 0\n 2 4 2 0\n 2 5 1 0\nM CHG 2 1 -1 5 -1\nM END\n",
"SMILES": "[O-]S(=O)(=O)[O-]"
},
"ligandConformations": [
{
"SMALL_MOL_ID": 87402,
"SMALL_MOL_CONF_ID": 5830049,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "A",
"STR_RESIDUE_NUMBER": 402,
"RESIDUE_CODE": "SO4",
"POCKET_ID": 49928382,
"POCKET_NUMBER": 3,
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/1/N:2,3,4,5,1/E:(1,2,3,4)/CRV:5.6/rA:5SO-O-OO/rB:N1;s1;d1;d1;/rC:35.35,-79.963,6.567;36.075,-79.786,5.331;33.936,-79.88,6.313;35.659,-81.248,7.136;35.731,-78.932,7.499;",
"STATE_NUMBER": 1
},
{
"SMALL_MOL_ID": 87402,
"SMALL_MOL_CONF_ID": 5830050,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "B",
"STR_RESIDUE_NUMBER": 401,
"RESIDUE_CODE": "SO4",
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/1/N:2,3,4,5,1/E:(1,2,3,4)/CRV:5.6/rA:5SO-O-OO/rB:N1;s1;d1;d1;/rC:12.355,-85.563,-1.228;11.961,-84.768,-2.371;12.801,-86.875,-1.636;11.229,-85.722,-.353;13.431,-84.885,-.551;"
},
{
"SMALL_MOL_ID": 87402,
"SMALL_MOL_CONF_ID": 5830051,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "B",
"STR_RESIDUE_NUMBER": 402,
"RESIDUE_CODE": "SO4",
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/1/N:2,3,4,5,1/E:(1,2,3,4)/CRV:5.6/rA:5SO-O-OO/rB:N1;s1;d1;d1;/rC:52.773,-66.255,.274;53.894,-66.763,-.467;52.373,-64.974,-.268;51.682,-67.195,.195;53.155,-66.085,1.647;"
},
{
"SMALL_MOL_ID": 87402,
"SMALL_MOL_CONF_ID": 5830052,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "B",
"STR_RESIDUE_NUMBER": 403,
"RESIDUE_CODE": "SO4",
"POCKET_ID": 49928387,
"POCKET_NUMBER": 8,
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/1/N:2,3,4,5,1/E:(1,2,3,4)/CRV:5.6/rA:5SO-O-OO/rB:N1;s1;d1;d1;/rC:43.954,-58.778,-23.697;44.208,-58.758,-25.113;42.786,-59.576,-23.438;45.085,-59.349,-23.018;43.736,-57.433,-23.221;",
"STATE_NUMBER": 1
},
{
"SMALL_MOL_ID": 87402,
"SMALL_MOL_CONF_ID": 5830053,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "B",
"STR_RESIDUE_NUMBER": 404,
"RESIDUE_CODE": "SO4",
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/1/N:2,3,4,5,1/E:(1,2,3,4)/CRV:5.6/rA:5SO-O-OO/rB:N1;s1;d1;d1;/rC:49.349,-71.051,-18.532;50,-71.714,-19.635;48.035,-70.627,-18.942;49.268,-71.989,-17.426;50.097,-69.875,-18.142;"
},
{
"SMALL_MOL_ID": 87402,
"SMALL_MOL_CONF_ID": 5830054,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "B",
"STR_RESIDUE_NUMBER": 405,
"RESIDUE_CODE": "SO4",
"POCKET_ID": 49928384,
"POCKET_NUMBER": 5,
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/1/N:2,3,4,5,1/E:(1,2,3,4)/CRV:5.6/rA:5SO-O-OO/rB:N1;s1;d1;d1;/rC:45.596,-77.208,-13.544;45.709,-75.81,-13.868;44.543,-77.801,-14.334;45.278,-77.35,-12.148;46.85,-77.861,-13.81;",
"STATE_NUMBER": 1
}
]
},
{
"NUMRINGS": 4,
"SINGL_BOND_FRACTION": 0.78125,
"isDruglike": true,
"small_mol_id": 152940,
"Data": {
"SMALL_MOL_ID": 152940,
"EXTERNAL_CODE": "8h4r",
"STR_RESIDUE_NUMBER": 401,
"RESIDUE_CODE": "1QK",
"MW": 397.502,
"NUMRINGS": 4,
"SINGL_BOND_FRACTION": 0.78125,
"isDruglike": true,
"CTAB": "\n RDKit 2D\n\n 29 32 0 0 0 0 0 0 0 0999 V2000\n 3.5260 -1.2990 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 2.7760 0.0000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 1.2760 0.0000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.3943 1.2135 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.7062 2.6807 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n -0.4086 3.6844 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -1.8351 3.2209 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -2.1470 1.7537 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -3.5736 1.2902 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n -4.6883 2.2939 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -6.1149 1.8303 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -7.2296 2.8340 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -8.6562 2.3705 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -8.9681 0.9033 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -7.8533 -0.1004 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n -8.1652 -1.5676 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n -6.4268 0.3631 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -1.0323 0.7500 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n -1.0323 -0.7500 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n 0.3943 -1.2135 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -0.0967 5.1517 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n 1.3299 5.6152 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 1.6418 7.0824 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.5271 8.0861 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -0.8995 7.6226 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -1.2114 6.1554 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -2.6380 5.6918 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -3.7527 6.6955 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -5.1793 6.2320 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1 2 1 0\n 2 3 1 0\n 3 4 2 0\n 4 5 1 0\n 5 6 2 0\n 6 7 1 0\n 7 8 2 0\n 8 9 1 0\n 9 10 1 0\n 10 11 1 0\n 11 12 2 0\n 12 13 1 0\n 13 14 2 0\n 14 15 1 0\n 15 16 1 0\n 15 17 2 0\n 8 18 1 0\n 18 19 1 0\n 19 20 2 0\n 6 21 1 0\n 21 22 1 0\n 22 23 1 0\n 23 24 1 0\n 24 25 1 0\n 25 26 1 0\n 26 27 1 6\n 27 28 1 0\n 28 29 1 0\n 20 3 1 0\n 26 21 1 0\n 18 4 1 0\n 17 11 1 0\nM CHG 1 15 1\nM END\n",
"SMILES": "CCC1=C2N=C(C=C(NCC3=CC=C[N+](O)=C3)N2N=C1)N1CCCC[C@H]1CCO"
},
"ligandConformations": [
{
"SMALL_MOL_ID": 152940,
"SMALL_MOL_CONF_ID": 5830045,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "A",
"STR_RESIDUE_NUMBER": 401,
"RESIDUE_CODE": "1QK",
"POCKET_ID": 49928380,
"POCKET_NUMBER": 1,
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/0/N:13,14,7,28,24,4,11,9,5,6,12,1,3,16,26,23,15,8,22,21,19,2,17,20,25,10,18,29,27/CRV:25+1/rA:29CNCCCCCC.oCNCCCCCCNNCNCCCCN+COCO/rB:;s2;;;;;;N8;s6s8;s7s8;s9;;s13;s14;s15;d16;s17;d15s18;s19;s1s10d20;d1s2s18;s3d4;s4d5;s5;s23d25;s25;s6s7;s12;/rC:24.123,-99.297,12.53;22.384,-100.925,12.161;23.13,-102.061,12.662;24.44,-102.149,14.809;23.35,-102.096,16.951;26.821,-98.439,13.236;27.723,-96.558,14.676;26.2,-96.12,12.719;27.295,-95.934,11.657;25.756,-97.541,12.765;26.619,-95.669,14.11;26.871,-96.279,10.239;22.441,-95.156,8.654;21.766,-95.376,9.993;21.719,-96.814,10.414;20.702,-97.755,10.186;20.963,-98.936,10.751;22.172,-98.752,11.341;22.655,-97.489,11.152;23.833,-97.032,11.623;24.557,-97.942,12.315;22.889,-99.702,12.023;23.212,-102.081,14.164;24.51,-102.158,16.196;22.143,-102.035,16.273;22.042,-102.017,14.907;20.975,-101.969,17.01;27.321,-98.028,14.604;25.675,-95.59,9.887;",
"STATE_NUMBER": 1
}
]
},
{
"NUMRINGS": 0,
"SINGL_BOND_FRACTION": 1,
"isDruglike": false,
"small_mol_id": 87403,
"Data": {
"SMALL_MOL_ID": 87403,
"EXTERNAL_CODE": "8h4r",
"STR_RESIDUE_NUMBER": 403,
"RESIDUE_CODE": "GOL",
"MW": 92.094,
"NUMRINGS": 0,
"SINGL_BOND_FRACTION": 1,
"isDruglike": false,
"CTAB": "\n RDKit 2D\n\n 6 5 0 0 0 0 0 0 0 0999 V2000\n -1.2990 0.7500 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 0.0000 0.0000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 1.2990 0.7500 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 1.2990 2.2500 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 2.5981 -0.0000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 3.8971 0.7500 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1 2 1 0\n 2 3 1 0\n 3 4 1 0\n 3 5 1 0\n 5 6 1 0\nM END\n",
"SMILES": "OCC(O)CO"
},
"ligandConformations": [
{
"SMALL_MOL_ID": 87403,
"SMALL_MOL_CONF_ID": 5830046,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "A",
"STR_RESIDUE_NUMBER": 403,
"RESIDUE_CODE": "GOL",
"POCKET_ID": 49928381,
"POCKET_NUMBER": 2,
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/0/N:1,5,3,2,6,4/E:(1,2)(4,5)/rA:6COCOCO/rB:s1;s1;P3;s3;s5;/rC:26.387,-86.497,-7.124;26.855,-85.349,-6.423;25.141,-87.08,-6.489;24.581,-86.119,-5.595;24.081,-87.523,-7.483;24.623,-88.158,-8.642;",
"STATE_NUMBER": 1
},
{
"SMALL_MOL_ID": 87403,
"SMALL_MOL_CONF_ID": 5830047,
"EXTERNAL_CODE": "8h4r",
"CHAIN_CODE": "B",
"STR_RESIDUE_NUMBER": 407,
"RESIDUE_CODE": "GOL",
"MOLECULE_INCHI_AUX_INFO": "AuxInfo=1/0/N:1,5,3,2,6,4/E:(1,2)(4,5)/rA:6COCOCO/rB:s1;s1;P3;s3;s5;/rC:49.846,-76.932,-20.612;48.613,-77.484,-21.07;49.697,-76.273,-19.255;49.648,-77.265,-18.227;50.796,-75.275,-18.951;50.456,-74.444,-17.845;"
}
]
}
]
}
]
Identify the ligand(s) of interest by checking the isDruglike property in the response. Looking at the ligands:
isDruglike is true but no POCKET_ID is listedisDruglike is falseisDruglike is true and bound in pocket with POCKET_ID 49928380📌 API 2.3+ Improvement: The
remove_non_drug_like_ligands=trueparameter now actually filters out ligands whereisDruglikeis false. In API 2.3+, the response will only contain drug-like ligands, so you no longer need to manually check theisDruglikeproperty. In earlier versions, this parameter had no effect and you had to filter manually.
In this example, ligand "1QK" bound in pocket 49928380 will be used as the query pocket for the similarity search. Note that some ligands may have multiple conformations (ligandConformations) in different pockets - select the POCKET_ID matching your pocket of interest.
This method allows finding pockets of interest without requiring a bound ligand. Retrieve all pockets in a structure using the API endpoint GET /structures/info/pocket. Use the structure_id retrieved in step 2 as input (e.g. 789192). If needed, the call can be made for multiple structures at once. See examples below.
curl -X 'GET' \
'https://3decision-[customer]-api.discngine.cloud/structures/info/pocket?structure_id=789192&state_number=1&ligand_fraction=0.4' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********htE'
curl -X 'GET' \
'https://3decision-[customer]-api.discngine.cloud/structures/info/pocket?structure_id=773550&structure_id=789192&structure_id=800591&state_number=1&ligand_fraction=0.4' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********htE'
[
{
"POCKET_INFO": [
{
"CAVITY_ID": 49928411,
"CAVITY_NUMBER": 32,
"STATE_NUMBER": 1,
"IS_EXPLICIT": "0",
"DRUGGABILITY_SCORE": 0.003,
"VOLUME": 513.7178,
"SMALL_MOL_CONF_ID": [],
"STR_RES_NUM": [
"159",
"160",
"161",
"162",
"204",
"205",
"206",
"351",
"352",
"353",
"356",
"359",
"360",
"157",
"158"
],
"STR_RESIDUE_NUMBER": [
345,
346,
347,
348,
390,
391,
392,
537,
538,
539,
542,
545,
546,
156,
157
],
"CHAIN_CODE": [
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"A",
"A"
],
"STR_RES_ID": [
567337778,
567337779,
567337780,
567337781,
567337823,
567337824,
567337825,
567337970,
567337971,
567337972,
567337975,
567337978,
567337979,
567337589,
567337590
]
},
{
"CAVITY_ID": 49928412,
"CAVITY_NUMBER": 33,
"STATE_NUMBER": 1,
"IS_EXPLICIT": "0",
"DRUGGABILITY_SCORE": 0.0001,
"VOLUME": 185.4955,
"SMALL_MOL_CONF_ID": [],
"STR_RES_NUM": [
"124",
"127",
"128",
"129",
"292",
"293",
"294",
"295",
"296"
],
"STR_RESIDUE_NUMBER": [
310,
313,
314,
315,
478,
479,
480,
481,
482
],
"CHAIN_CODE": [
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B",
"B"
],
"STR_RES_ID": [
567337743,
567337746,
567337747,
567337748,
567337911,
567337912,
567337913,
567337914,
567337915
]
},
{
"CAVITY_ID": 49928413,
"CAVITY_NUMBER": 35,
"STATE_NUMBER": 1,
"IS_EXPLICIT": "1",
"DRUGGABILITY_SCORE": 0.9999,
"VOLUME": 993.973,
"SMALL_MOL_CONF_ID": [
5830045
],
"STR_RES_NUM": [
"8",
"9",
"10",
"11",
"12",
"13",
"18",
"20",
"31",
"33",
"51",
"64",
"80",
"81",
"82",
"83",
"84",
"85",
"86",
"89",
"131",
"132",
"134",
"144",
"145"
],
"STR_RESIDUE_NUMBER": [
7,
8,
9,
10,
11,
12,
17,
19,
30,
32,
50,
63,
79,
80,
81,
82,
83,
84,
85,
88,
130,
131,
133,
143,
144
],
"CHAIN_CODE": [
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A",
"A"
],
"STR_RES_ID": [
567337440,
567337441,
567337442,
567337443,
567337444,
567337445,
567337450,
567337452,
567337463,
567337465,
567337483,
567337496,
567337512,
567337513,
567337514,
567337515,
567337516,
567337517,
567337518,
567337521,
567337563,
567337564,
567337566,
567337576,
567337577
]
}
],
"STRUCTURE_ID": 789192
}
]
Looking at the response body, pocket with CAVITY_ID 49928413 has:
DRUGGABILITY_SCORE: 0.9999)SMALL_MOL_CONF_ID: [5830045])Extract the pocket residue selection needed for the pocket similarity search in step 4:
CAVITY_ID: 49928413 (needed for API ≤2.2)EXTERNAL_CODE: "8h4r" (needed for API 2.3+)STR_RES_NUM: ["8", "9", "10", "11", "12", "13", "18", "20", "31", "33", "51", "64", "80", "81", "82", "83", "84", "85", "86", "89", "131", "132", "134", "144", "145"]CHAIN_CODE: ["A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A", "A"]The pocket similarity search can be launched using the API endpoint POST /search/subpocket.
⚠️ Breaking Change in API 2.3: The request body format has been completely redesigned. See both versions below.
curl -X 'GET' \
'https://3decision-[customer]-api.discngine.cloud/search/subpocket' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********htE' \
-H 'Content-Type: application/json' \
-d '{
"cavityId": 49928413,
"residueSelection": [
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 8
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 9
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 10
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 11
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 12
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 13
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 18
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 20
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 31
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 33
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 51
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 64
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 80
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 81
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 82
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 83
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 84
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 85
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 86
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 89
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 131
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 132
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 134
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 144
},
{
"chainCode": "A",
"insertionCode": "",
"residueNumber": 145
}
],
"filteringCriteria": "Matching ratio",
"filteringCutoff": 0.2,
"maxAngularDeviation": 0.1,
"topologyDistanceMargin": 0.5,
"distanceSdSmall": 0.2,
"distanceSdLarge": 0.5,
"thetaSd": 0.1
}
def format_pocket_search_input(cavity_id, residues, chains):
"""Format pocket data for similarity search input (API ≤2.2).
Args:
cavity_id (int): ID of the cavity/pocket
residues (list): List of residue numbers
chains (list): List of chain codes
Returns:
dict: Formatted JSON input
"""
residue_selection = [
{
"chainCode": chain,
"insertionCode": "",
"residueNumber": residue
}
for residue, chain in zip(residues, chains)
]
return {
"cavityId": cavity_id,
"residueSelection": residue_selection,
"filteringCriteria": "Matching ratio",
"filteringCutoff": 0.2,
"maxAngularDeviation": 0.1,
"topologyDistanceMargin": 0.5,
"distanceSdSmall": 0.2,
"distanceSdLarge": 0.5,
"thetaSd": 0.1
}
curl -X 'POST' \
'https://3decision-[customer]-api.discngine.cloud/search/subpocket' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********htE' \
-H 'Content-Type: application/json' \
-d '{
"queryExternalCode": "8h4r",
"queryResidueSelection": [
{"chainCode": "A", "insertionCode": "", "residueNumber": 8},
{"chainCode": "A", "insertionCode": "", "residueNumber": 9},
{"chainCode": "A", "insertionCode": "", "residueNumber": 10},
{"chainCode": "A", "insertionCode": "", "residueNumber": 11},
{"chainCode": "A", "insertionCode": "", "residueNumber": 12},
{"chainCode": "A", "insertionCode": "", "residueNumber": 13},
{"chainCode": "A", "insertionCode": "", "residueNumber": 18},
{"chainCode": "A", "insertionCode": "", "residueNumber": 20},
{"chainCode": "A", "insertionCode": "", "residueNumber": 31},
{"chainCode": "A", "insertionCode": "", "residueNumber": 33},
{"chainCode": "A", "insertionCode": "", "residueNumber": 51},
{"chainCode": "A", "insertionCode": "", "residueNumber": 64},
{"chainCode": "A", "insertionCode": "", "residueNumber": 80},
{"chainCode": "A", "insertionCode": "", "residueNumber": 81},
{"chainCode": "A", "insertionCode": "", "residueNumber": 82},
{"chainCode": "A", "insertionCode": "", "residueNumber": 83},
{"chainCode": "A", "insertionCode": "", "residueNumber": 84},
{"chainCode": "A", "insertionCode": "", "residueNumber": 85},
{"chainCode": "A", "insertionCode": "", "residueNumber": 86},
{"chainCode": "A", "insertionCode": "", "residueNumber": 89},
{"chainCode": "A", "insertionCode": "", "residueNumber": 131},
{"chainCode": "A", "insertionCode": "", "residueNumber": 132},
{"chainCode": "A", "insertionCode": "", "residueNumber": 134},
{"chainCode": "A", "insertionCode": "", "residueNumber": 144},
{"chainCode": "A", "insertionCode": "", "residueNumber": 145}
],
"filteringCutoff": 0.2,
"filterDuplicates": true,
"explicitPocketsOnly": true,
"bestMatchOnly": false
}'
def format_pocket_search_input_v23(external_code, residues, chains, **options):
"""Format pocket data for similarity search input (API 2.3+).
Args:
external_code (str): External code of the structure (e.g. "8h4r")
residues (list): List of residue numbers
chains (list): List of chain codes
**options: Optional parameters
Returns:
dict: Formatted JSON input
"""
residue_selection = [
{
"chainCode": chain,
"insertionCode": "",
"residueNumber": residue
}
for residue, chain in zip(residues, chains)
]
request = {
"queryExternalCode": external_code,
"queryResidueSelection": residue_selection,
"filteringCutoff": options.get("filteringCutoff", 0.2),
"filterDuplicates": options.get("filterDuplicates", True),
"explicitPocketsOnly": options.get("explicitPocketsOnly", True),
"bestMatchOnly": options.get("bestMatchOnly", False)
}
# Add optional filters
for key in ["structureCodes", "excludeStructureCodes", "biomolCodes", "speciesNames"]:
if key in options:
request[key] = options[key]
return request
Example usage:
import json
residues = ["8", "9", "10", "11", "12", "13"]
chains = ["A", "A", "A", "A", "A", "A"]
# 📌 API ≤2.2
cavity_id = 49928413
search_input = format_pocket_search_input(cavity_id, residues, chains)
# 📌 API 2.3+
external_code = "8h4r"
search_input = format_pocket_search_input_v23(external_code, residues, chains)
print(json.dumps(search_input, indent=2))
The pocket similarity search is launched as an asynchronous job and returns a job ID. Use this ID with the GET /search/subpocket/{jobId} endpoint to check the job status until it completes.
Once the job is complete, you'll receive a list of similar pockets with the following information for each hit:
⚠️ Response Change in API 2.3: The
match_scoreproperty has been renamed toscore.
The results are ordered by descending score.
{
"state": "success",
"content": [
{
"cavity_id": 49928413,
"structure_id": 789192,
"external_code": "8h4r",
"title": "CDK3 structure...",
"match_score": 0.99,
"matched_fps": 52,
"transform": [...],
"rmsd": 1.85e-7
}
]
}
{
"id": "31",
"state": "completed",
"content": {
"message": "Subpocket search completed",
"results": [
{
"biomol_id": 11018539,
"cavity_id": 54227482,
"structure_id": 824537,
"external_code": "8kcp",
"title": "Cryo-EM structure of human gamma-secretase in complex with Crenigacestat",
"score": 0.375,
"match_score": 33,
"matched_fps": 50,
"matched_residues": {
"res_f1": ["B:379", "B:377", "B:85", "..."],
"res_f2": ["B:381", "B:379", "B:418", "..."],
"ref_res_f1": ["A:68", "A:171", "A:174", "..."],
"ref_res_f2": ["A:72", "A:129", "A:129", "..."]
},
"transform": [
0.5926358263541793, -0.7232592562434628, -0.3545120951105223, 76.26526204523275,
-0.6439495103622995, -0.6898251788973078, 0.3308628880117123, 118.60591578175115,
-0.4838510157327911, 0.032206689017183175, -0.8745575588587046, 100.88955426833392,
0, 0, 0, 1
],
"rmsd": 0.6173748287716441
}
],
"progress": 100,
"processingStats": {
"totalBatches": 409,
"completedBatches": 409,
"totalResultsFound": 1,
"lastUpdate": "2026-01-26T13:31:09.535Z"
}
}
}
To retrieve additional details about the hits from Step 4, you can use the following endpoints:
/structures/info/batch?metadataType=general,chain — Structure metadata/structures/info/pocket — Pocket information & ligand codes/structures/info/ligand — Full ligand detailsIf you're interested in a Python script that automates this workflow and post‑processes the results, feel free to contact 3decision Support.
Automates Pocket Similarity Searches in 3decision and exports results enriched with structure and ligand metadata.