API calls related to molecule objects:
Retrieve
GET /api/v1/vaults/<vault_id>/molecules/<id>
Return a single molecule and its batches
GET /api/v1/vaults/<vault_id>/molecules
Return a list of molecules and their batches, based on the parameters.
If batch date constraints are specified, only batches matching the search criteria are included in the returned molecule object.
Query Parameters (all optional):
molecules |
Comma separated list of ids | Cannot be used with other parameters |
names |
Comma separated list of names/synonyms | |
async |
Boolean If true, do an asynchronous export (see Async Export) Use for large data sets |
This is strongly recommended any time you want to download more than page_size results. |
no_structures |
Boolean If true, omit structure representations for a smaller and faster response. Default: false |
|
created_before |
Date (YYYY-MM-DD) | |
created_after |
Date (YYYY-MM-DD) | |
modified_before |
Date (YYYY-MM-DD) | |
modified_after |
Date (YYYY-MM-DD) | |
batch_created_before |
Date (YYYY-MM-DD) | A molecule with any batch that has a creation date on or before the parameter will be included |
batch_created_after |
Date (YYYY-MM-DD) | A molecule with any batch that has a creation date on or after the parameter will be included |
batch_field_before_name |
Batch field name | Specifes a user-defined batch field for batch_field_before_date |
batch_field_before_date |
Date (YYYY-MM-DD) | A molecule with any batch that has a batch_field_before_name value date on or before the parameter will be included |
batch_field_after_name |
Batch field name | Specifes a user-defined batch field for batch_field_after_date |
|
Date (YYYY-MM-DD) | A molecule with any batch that has a batch_field_after_name value date on or after the parameter will be included |
offset |
The index of the first object actually returned. Defaults to 0. | |
page_size |
The maximum number of objects to return in this call. Default is 50, maximum is 1000. | If the response exceeds the page_size , we strongly recommend using the async option instead of downloading multiple chunks. |
projects |
Comma-separated list of project ids Defaults to all available projects Limits scope of query |
|
data_sets |
Comma-separated list of public dataset ids Defaults to no data sets Limits scope of query |
Examples
curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/489978881/molecules/927454016
Returns:
{
"id": 927454016,
"class": "molecule",
"name": "Taurine",
"synonyms": [ "Taurine" ],
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
},
{
"name": "Super User Private Stuff",
"id": 3870925
} ],
"collections": [
{
"name": "super user hits",
"id": 90769562
} ],
"owner": "Super User",
"created_at": "2010-11-17",
"modified_at": "2017-12-12",
"smiles": "NCCS(O)(=O)=O",
"cxsmiles": "NCCS(O)(=O)=O",
"inchi": "InChI=1S/C2H7NO3S/c3-1-2-7(4,5)6/h1-3H2,(H,4,5,6)",
"inchi_key": "XOAAWQZATWQOTB-UHFFFAOYSA-N",
"iupac_name": "2-aminoethane-1-sulfonic acid",
"molfile": "taurine\n Mrv1770 12121711132D \n\n 7 6 0 0 0 0 999 V2000\n 0.1105 -2.0625 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n 0.1105 -1.2375 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8250 -0.8250 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8250 0.0000 0.0000 S 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8250 0.8250 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1.6500 -0.0000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 0.0000 0.0000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1 2 1 0 0 0 0\n 2 3 1 0 0 0 0\n 3 4 1 0 0 0 0\n 4 5 1 0 0 0 0\n 4 6 2 0 0 0 0\n 4 7 2 0 0 0 0\nM END\n",
"molecular_weight": 125.14,
"log_p": -2.61469,
"log_d": -2.61939,
"log_s": 0.996488,
"num_h_bond_donors": 2,
"num_h_bond_acceptors": 4,
"num_rule_of_5_violations": 0,
"formula": "C2H7NO3S",
"isotope_formula": "C2H7NO3S",
"dot_disconnected_formula": "C2H7NO3S",
"p_k_a": -1.49,
"p_k_a_type": "Acidic",
"exact_mass": 125.014664263,
"heavy_atom_count": 7,
"composition": "C (19.2%), H (5.64%), N (11.19%), O (38.35%), S (25.62%)",
"isotope_composition": "C (19.2%), H (5.64%), N (11.19%), O (38.35%), S (25.62%)",
"topological_polar_surface_area": 80.39,
"num_rotatable_bonds": 2,
"cns_mpo_score": 4.82803,
"fsp3": 1.0,
"batches": [
{
"id": 136660530,
"class": "batch",
"owner": "Super User",
"created_at": "2007-02-04",
"modified_at": "2007-12-31",
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
},
{
"name": "Super User Private Stuff",
"id": 3870925
} ]
} ]
}
To retrieve molecule with IDs 3 and 927454016
curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/489978881/molecules?molecules=3,927454016
Returns:
{
"count": 2,
"offset": 0,
"page_size": 50,
"objects": [
{
"id": 3,
"class": "molecule",
"name": "Cyanide",
"synonyms": [ "Cyanide" ],
"cdd_registry_number": 3,
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
} ],
"collections": [
{
"name": "super user hits",
"id": 90769562
},
{
"name": "all",
"id": 557113845
} ],
"owner": "Full-Access User",
"created_at": "1999-01-01",
"modified_at": "1999-01-01",
"smiles": "C#N",
"cxsmiles": "C#N",
"inchi": "InChI=1S/CHN/c1-2/h1H",
"inchi_key": "LELOWRISYMNNSU-UHFFFAOYSA-N",
"iupac_name": "formonitrile",
"molfile": "\n Mrv1770 12121711262D \n\n 2 1 0 0 0 0 999 V2000\n 0.8250 0.0000 0.0000 N 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 2 3 0 0 0 0\nM END\n",
"molecular_weight": 27.026,
"log_p": -0.346198,
"log_d": -0.339047,
"log_s": 0.321662,
"num_h_bond_donors": 0,
"num_h_bond_acceptors": 1,
"num_rule_of_5_violations": 0,
"formula": "CHN",
"isotope_formula": "CHN",
"dot_disconnected_formula": "CHN",
"p_k_a": 9.5,
"p_k_a_type": "Acidic",
"exact_mass": 27.010899036,
"heavy_atom_count": 2,
"composition": "C (44.44%), H (3.73%), N (51.83%)",
"isotope_composition": "C (44.44%), H (3.73%), N (51.83%)",
"topological_polar_surface_area": 23.79,
"num_rotatable_bonds": 0,
"cns_mpo_score": 5.1895,
"fsp3": 0.0,
"batches": [
{
"id": 618771089,
"class": "batch",
"name": "KGB-51AD88",
"owner": "Full-Access User",
"created_at": "2007-02-04",
"modified_at": "2007-12-31",
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
} ],
"formula_weight": 27.026
} ]
},
{
"id": 927454016,
"class": "molecule",
"name": "Taurine",
"synonyms": [ "Taurine" ],
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
},
{
"name": "Super User Private Stuff",
"id": 3870925
} ],
"collections": [
{
"name": "super user hits",
"id": 90769562
} ],
"owner": "Super User",
"created_at": "2010-11-17",
"modified_at": "2017-12-12",
"smiles": "NCCS(O)(=O)=O",
"cxsmiles": "NCCS(O)(=O)=O",
"inchi": "InChI=1S/C2H7NO3S/c3-1-2-7(4,5)6/h1-3H2,(H,4,5,6)",
"inchi_key": "XOAAWQZATWQOTB-UHFFFAOYSA-N",
"iupac_name": "2-aminoethane-1-sulfonic acid",
"molfile": "taurine\n Mrv1770 12121711262D \n\n 7 6 0 0 0 0 999 V2000\n 0.1105 -2.0625 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n 0.1105 -1.2375 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8250 -0.8250 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8250 0.0000 0.0000 S 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8250 0.8250 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1.6500 -0.0000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 0.0000 0.0000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n 1 2 1 0 0 0 0\n 2 3 1 0 0 0 0\n 3 4 1 0 0 0 0\n 4 5 1 0 0 0 0\n 4 6 2 0 0 0 0\n 4 7 2 0 0 0 0\nM END\n",
"molecular_weight": 125.14,
"log_p": -2.61469,
"log_d": -2.61939,
"log_s": 0.996488,
"num_h_bond_donors": 2,
"num_h_bond_acceptors": 4,
"num_rule_of_5_violations": 0,
"formula": "C2H7NO3S",
"isotope_formula": "C2H7NO3S",
"dot_disconnected_formula": "C2H7NO3S",
"p_k_a": -1.49,
"p_k_a_type": "Acidic",
"exact_mass": 125.014664263,
"heavy_atom_count": 7,
"composition": "C (19.2%), H (5.64%), N (11.19%), O (38.35%), S (25.62%)",
"isotope_composition": "C (19.2%), H (5.64%), N (11.19%), O (38.35%), S (25.62%)",
"topological_polar_surface_area": 80.39,
"num_rotatable_bonds": 2,
"cns_mpo_score": 4.82803,
"fsp3": 1.0,
"batches": [
{
"id": 136660530,
"class": "batch",
"owner": "Super User",
"created_at": "2007-02-04",
"modified_at": "2007-12-31",
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
},
{
"name": "Super User Private Stuff",
"id": 3870925
} ]
} ]
} ]
}
Create
POST /api/v1/vaults/<vault_id>/molecules/
Creates a new molecule.
Note: this operation is not permitted in registration vaults. Creation of new molecules in registration vaults must be accomplished using POST batch.
Allowed JSON keys for molecules:
class |
Optional. If present, must be “molecule” |
smiles |
Only one of these fields can be present. “structure” accepts SMILES strings, IUPAC names, or Molfiles as values For molfiles, replace all new lines with \n (JSON requirement) |
name |
String (Required) |
description |
String |
synonyms |
An array of strings |
udfs (user defined fields) |
{<udf_name>: <udf_value>, ... } |
projects |
An array of project ids and/or names (Required) |
collections |
An array of project ids and/or names |
Example
curl -H "X-CDD-Token: $TOKEN" -X POST -H "Content-Type: application/json" -d "@data.json" https://app.collaborativedrug.com/api/v1/vaults/489978881/molecules
File data.json:
{
"name": "methane",
"projects": [938429932, "Super User Private Stuff"],
"udfs": {
"field1": "value1",
"field2": "value2"
},
"molfile": "\n MJ171500 \n\n 1 0 0 0 0 0 0 0 0 0999 V2000\n -0.4464 1.3727 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\nM END\n"
}
Returns:
{
"id": 1070752025,
"class": "molecule",
"name": "methane",
"synonyms": [ "methane" ],
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
},
{
"name": "Super User Private Stuff",
"id": 3870925
}
],
"owner": "Super User",
"created_at": "2017-12-12",
"modified_at": "2017-12-12",
"smiles": "C",
"cxsmiles": "C",
"inchi": "InChI=1S/CH4/h1H4",
"inchi_key": "VNWKTOKETHGBQD-UHFFFAOYSA-N",
"iupac_name": "methane",
"molfile": "\n MJ171500 \n\n 1 0 0 0 0 0 0 0 0 0999 V2000\n -0.4464 1.3727 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\nM END\n",
"molecular_weight": 16.043,
"log_p": 1.08092,
"log_d": 1.08092,
"log_s": 0.588218,
"num_h_bond_donors": 0,
"num_h_bond_acceptors": 0,
"num_rule_of_5_violations": 0,
"formula": "CH4",
"isotope_formula": "CH4",
"dot_disconnected_formula": "CH4",
"exact_mass": 16.0313001288,
"heavy_atom_count": 1,
"composition": "C (74.87%), H (25.13%)",
"isotope_composition": "C (74.87%), H (25.13%)",
"topological_polar_surface_area": 0.0,
"num_rotatable_bonds": 0,
"cns_mpo_score": 5,
"fsp3": 1.0,
"udfs":
{
"field1": "value1",
"field2": "value2"
}
}
Update
PUT /api/v1/vaults/<vault_id>/molecules/id
Updates an existing molecule.
See Create for valid fields. Fields not specified in the JSON are not changed.
To delete a molecule, simply submit with an empty projects array.
Note that the ID for the molecule is specified as part of the URL, not in the JSON (the JSON can contain an ID field as long as its value matches the URL).
Notes on how particular fields are processed:
name |
If this field is supplied, the old name is automatically added as a synonym. To delete a molecule name, you must exclude it from the list of synonyms. Names cannot be changed in registration vaults. |
synonyms |
If supplied, the list of synonyms replaces the existing list |
udfs |
Only fields explicitly mentioned will be changed. A user-defined field can be removed by using the value null (no quotes). |
Examples
curl -H "X-CDD-Token: $TOKEN" -X PUT -H "Content-Type: application/json" -d "@data.json" https://app.collaborativedrug.com/api/v1/vaults/489978881/molecules/1070752025
File data.json:
{
"name": "a new name",
"udfs": {
"field1": null
}
}
Returns:
{
"id": 1070752025,
"class": "molecule",
"name": "a new name",
"synonyms": [ "methane", "a new name" ],
"projects": [
{
"name": "McKerrow Vault",
"id": 938429932
},
{
"name": "Super User Private Stuff",
"id": 3870925
}
],
"owner": "Super User",
"created_at": "2017-12-12",
"modified_at": "2017-12-12",
"smiles": "C",
"cxsmiles": "C",
"inchi": "InChI=1S/CH4/h1H4",
"inchi_key": "VNWKTOKETHGBQD-UHFFFAOYSA-N",
"iupac_name": "methane",
"molfile": "\n MJ171500 \n\n 1 0 0 0 0 0 0 0 0 0999 V2000\n -0.4464 1.3727 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\nM END\n",
"molecular_weight": 16.043,
"log_p": 1.08092,
"log_d": 1.08092,
"log_s": 0.588218,
"num_h_bond_donors": 0,
"num_h_bond_acceptors": 0,
"num_rule_of_5_violations": 0,
"formula": "CH4",
"isotope_formula": "CH4",
"dot_disconnected_formula": "CH4",
"exact_mass": 16.0313001288,
"heavy_atom_count": 1,
"composition": "C (74.87%), H (25.13%)",
"isotope_composition": "C (74.87%), H (25.13%)",
"topological_polar_surface_area": 0.0,
"num_rotatable_bonds": 0,
"cns_mpo_score": 5.0,
"fsp3": 1.0,
"udfs":
{
"field2": "value2"
}
}
Deleting a molecule
curl -H "X-CDD-Token: $TOKEN" -X PUT -H "Content-Type: application/json" -d "@data.json" https://app.collaborativedrug.com/api/v1/vaults/489978881/molecules/1070752025
File data.json:
{
"projects": []
}
Returns:
{
"message": "Object has been removed from all projects, so it has been deleted"
}
(Note: this is only possible in a "non-registration" vault; the majority of vaults are so called "registration" vaults. To be able to delete a molecule in the latter, you have to do this on the batch level; review this API related article. )