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.

Collection(s) [GET, POST, PUT, DELETE]

Avatar
Jacob Bloom

API calls related to collection objects:

Retrieve

Create

Update

Delete

Retrieve

GET /api/v1/vaults/<vault_id>/collections/<id>

Get a single collection.

Query Parameters (optional):

projects

Comma-separated list of project ids
Defaults to all available projects
Limits which molecules are returned in the Collection

Collection's project must be included for a vault_collection


GET /api/v1/vaults/<vault_id>/collections

Get all collections. The molecule ids are not returned by default.

Query Parameters (all optional):

collections Comma separated list of ids
Cannot be used with Date and Type parameters
async Boolean
If true, do an asynchronous export (see Async Export)
Use for large data sets. This is recommended any time you want to download more than page_size results. Note: any page_size parameter used in an API GET call that also uses the async=true parameter will be ignored. The GET call will return all valid data for the given GET call.
only_ids Boolean
If true, only the Collection IDs are returned, allowing for a smaller and faster response. (Async should still be used when many IDs are expected.)

 

Note: any page_size parameter used in an API GET call that also uses the only_ids=true parameter will be ignored. The GET call will return all valid data for the given GET call.


Default: false
include_molecule_ids Boolean
If true, the molecule ids will be returned as an array using the molecules JSON key.
Default: false
created_before Date (YYYY-MM-DDThh:mm:ss±hh:mm)
created_after Date (YYYY-MM-DDThh:mm:ss±hh:mm)
modified_before Date (YYYY-MM-DDThh:mm:ss±hh:mm)
modified_after Date (YYYY-MM-DDThh:mm:ss±hh:mm)
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. Note: any page_size parameter used in an API GET call that also uses the async=true parameter will be ignored. The GET call will return all valid data for the given GET call.
projects Comma-separated list of project ids
Defaults to all available projects
Limits scope of query
type Comma-separated list of collection types to return. Possible options are user_collection (private) and vault_collection (shared with project members).

Example

curl -H "X-CDD-Token: $TOKEN" -X GET "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/collections/<collection_id>"

Returns:

{
  "id": <collection_id>,
  "class": "user collection",
  "created_at": "2023-06-29T21:06:15.818Z",
  "modified_at": "2023-06-29T21:06:15.818Z",
  "molecules": [1,2],
  "name": "My Collection",
  "owner": "Jacob Bloom"
}

Notes on using JSON in environments that do not support writing and attaching temporary JSONs to a GET request

POST Query API Parameter


Passing JSON content in a GET API call is becoming a non-standard way of building REST APIs. As an example, Microsoft doesn't allow sending JSON content with GET requests.

To offer a solution to this limitation, the CDD Vault POST API call now includes a “query” parameter that, when used, will pass the JSON as desired to retrieve data from CDD Vault.

As an example, if you wanted to retrieve Molecules that meet a certain set of parameters, the GET Molecules API call might resemble this:


GET /api/v1/vaults/<vault_id>/collections

Using JSON written like:

{ 
"created_after":"2022-01-01", 
"projects":"6547", 
"no_structures":true 
}

 

If your infrastructure does not support passing JSON parameters with a GET Molecules API call, then you may now use a POST API call resembling this:

 

POST /api/v1/vaults/<vault_id>/molecules/query

Using JSON written like:

{ 
"created_after":"2022-01-01", 
"projects":"6547", 
"no_structures":true 
}

 

Noteworthy tips:

  • Note the “query” parameter is added to the end of the POST url. This allows the POST API call to retrieve data from CDD Vault instead of creating new data (which is the common function of a POST API call)
  • This “query” parameter is supported for all POST API calls in CDD Vault that have a corresponding GET API call.

Create

POST /api/v1/vaults/<vault_id>/collections

Create a new collection. 

Parameters

name The name of the collection. Required.
project The project with which the vault collection will be associated. If omitted, a user collection (private) will be created.
overwrite

Boolean

If the name conflicts with an existing collection, overwrite the original.

Default: false
molecules Array of molecule ids to add to the collection. Optional - either Molecules or Query parameter must be used with this POST API call.
query The CDD Vault POST API call now supports a “query” parameter that, when used, will pass the JSON as desired to retrieve data from CDD Vault. (Basically turns the POST API call into A GET API call.) Optional - either Query or Molecules parameter must be used with this POST API call.

Example

curl -H "X-CDD-Token: $TOKEN" -X POST "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/collections

Using JSON resembling this:

{
 "name":"New API Collection",
 "molecules":[123456789,987654321]
}

 

Returns:

{
  "id": 1,
  "class": "user collection",
  "created_at": "2023-06-29T21:06:15.818Z",
  "modified_at": "2023-06-29T21:06:15.818Z",
  "name": <collection_name>,
  "owner": "Jacob Bloom"
}

Update

PUT /api/v1/vaults/<vault_id>/collections/<collection_id>

Add molecules to a collection. 

There is no mechanism for removing a Molecule from an existing Collection via the API. The workflow to achieve this would be to:

  1. retrieve the MoleculeIDs in a current Collection,
  2. delete the existing Collection, and
  3. create a new Collection leaving out the Molecule ID(s) you wish to remove.

Parameters

molecules Array of molecule ids to add to the collection.

Example

curl -H "X-CDD-Token: $TOKEN" -X POST "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/collections/<collection_id>?molecules=1,2"

Returns:

{
  "id": <collection_id>,
  "class": "user collection",
  "created_at": "2023-06-28T21:06:15.818Z",
  "modified_at": "2023-06-29T21:08:45.858Z",
  "molecules": [1,2],
  "name": <collection_name>,
  "owner": "Jacob Bloom"
}

Delete

DELETE /api/v1/vaults/<vault_id>/collections/<id>

Delete a collection.

Example

curl -H "X-CDD-Token: $TOKEN" -X DELETE "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/collections/<collection_id>"

Returns:

{
  "message": "Object has been destroyed"
}