Information submitted through the support site is private but is not hosted within your secure CDD Vault. Please do not include sensitive intellectual property in your support requests.

Molecule(s) [GET, POST, PUT]

API calls related to molecule objects:

Retrieve

Create

Update

Retrieve

These calls return the JSON representations of a single molecule or set of molecules, using


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. 


Parameters (all optional):

moleculescomma separated list of ids 

 ParameterValueNotes

names comma separated list of names/synonyms  
created_before date  
created_after date  
modified_before date  
modified_after date  
batch_created_before date a molecule with any batch that has a creation date on or before the parameter will be included
batch_created_after date 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 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

batch_field_after_date

date a molecule with any batch that has a batch_field_after_name value date on or after the parameter will be included


Constraints:
The molecules and names parameters cannot be combined with others.

 

 

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.

 

The body of the POST must contain a JSON structure specifying the molecule attributes. The structure is roughly the same format as what is returned by a GET call but with some restrictions and additions.

 

Allowed JSON keys:

class

Optional. If present, must be “molecule”

smiles, cxsmiles, iupac_name, molfile, structure

At most one of these fields can be present. “structure” accepts SMILES strings, IUPAC names, or Molfiles as values

name, description, synonyms, udfs

These fields are treated just as they are in a GET

projects, collections

The value of these fields are JSON arrays. Each element of the array can be an id number, the name of the project or collection as a string, or a dictionary of the form {"name": "My project", "id": 232323}

 

The minimum information required to create a new molecule is a Molecule Name and a Project to which the new molecule will be associated. In the example below, a new molecule with no structure will be created.

{

"name": "No Structure Molecule 3",

"projects": [{"name":"Test 1"}]

}

 

In the next example, a molecule is created based on the structure in the smiles string:

{

"name": "Aspirin",

"projects": [{"name":"Test 1"}] ,

"smiles": "CC(=O)Oc1ccccc1C(=O)O"

}

 

Here is an example of a richer data set. Note how the projects field is an array of objects, whereas the synonyms field is an array of strings. In this example, the new molecule is associated with two projects, "Test 1" and Test 2".

{

 "name": "Aspirin",

 "synonyms":  ["Acetylsalicylic Acid","2-Acetoxybenzoic acid","O-Acetylsalicylic acid"],

 "projects": [{"name":"Test 1"},{"name":"Test 2"}] ,

 "smiles": "CC(=O)Oc1ccccc1C(=O)O",

 "description": "Benchmark NSAID",

 "udfs":

    {

      "Predicted MP":"245°C",

      "Patent Application":"1234-B"

     }

}

 

For molfiles: Be sure to replace the linefeeds (or carriage return+line feeds in Windows) with “\n”, as the JSON parser will not accept the line feeds within strings.

 

Update

 

PUT /api/v1/vaults/<vault_id>/molecules/id

Updates an existing molecule.

 

The body of the PUT must contain a JSON structure specifying changes to molecule attributes. The structure is roughly the same format as what is returned by a GET call but with some restrictions and additions. Fields that are not specified in the JSON are not changed. See the documentation for the POST call to see what JSON keys are allowed.

 

Note that the ID of the molecule being updated 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

If supplied, the value is a dictionary. Only fields explicitly mentioned in the dictionary will be changed. A user-defined field can be removed by using the value null (no quotes).

id

If supplied, must match the one in the URL

 

Examples: Consider the aspirin molecule we POSTED previously:

{

 "name": "Aspirin",

 "synonyms":  ["Acetylsalicylic Acid","2-Acetoxybenzoic acid","O-Acetylsalicylic acid"],

 "projects": [{"name":"Test 1"},{"name":"Test 2"}] ,

 "smiles": "CC(=O)Oc1ccccc1C(=O)O",

 "description": "Benchmark NSAID",

 "udfs":

    {

      "Predicted MP":"245°C",

      "Patent Application":"1234-B"

     }

}

 

This JSON in a PUT will change just the description of the molecule with the id 123456: https://app.collaborativedrug.com/api/v1/vaults/<vaultNumber>/molecules/123456

{

"description": "A useful anti inflammatory"

}

 

This JSON will change the Name and the Structure. The old name, Aspirin, will be automatically added as a synonym.

{

"name": "Ibuprofen",

"smiles": "CC(C)Cc1ccc(cc1)C(C)C(=O)O"

}

 

If you want to make this change and delete the old name, the JSON would be as follows.

{

"name": "Ibuprofen",

"smiles": "CC(C)Cc1ccc(cc1)C(C)C(=O)O",

"synonyms":  ["Acetylsalicylic Acid","2-Acetoxybenzoic acid","O-Acetylsalicylic acid"],

}

 

Manipulation of the projects array can be used to add or remove project associations to the molecule. For example, this JSON will remove the association of the molecule with Project "Test 2"  (or any other projects besides "Test 1").

{

"projects": [{"name":"Test 1"}]

}

 

This JSON will restore the association with "Test 2", as well as adding an association with "Test 3".

{

             "projects": [{"name":"Test 1"}, {"name":"Test 2"}, {"name":"Test 3"}]

}

 

To delete the molecule from all of your projects, submit the following JSON.

{

"projects":[ ]

}

 

UDFs (user defined fields for molecules) are handled as follows: To add new UDFs to an existing molecule (for example, where the id=123456).

{

"udfs":

    {"Predicted MP":"245°C",

     "Patent Application":"1234-B"

  }

}

Any previously existing UDFs for that molecule would be unchanged.

 

To change the value of one or more UDFs, set the value of the UDF to the desired string. This JSON will alter the "Predicted MP" UDF value for molecule 123456 from "245°C"  to "145°C", again leaving the other UDFs unchanged

{

"udfs":

    {"Predicted MP":"145°C"}

}

 

To remove one or more UDFs, set the value of the UDF to an empty or null string. This JSON will remove the "Patent Application" UDF from molecule 123456, leaving the other UDFs unchanged.

{

"udfs":

    {"Patent Application":""}

}

 

The HTTP response contains the full JSON representation of the updated molecule (as would be returned from a GET)

 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.