Home

CDD API

v1.0.0
Base URL
https://app.collaborativedrug.com/api/v1

Collaborative Drug Discovery provides an API (Application Programming Interface) that can be used for secure programmatic access to your vault data. Using the API, client applications such as Microsoft Office, Pipeline Pilot, Knime and others can be configured to directly access and process chemical and biological data from CDD Vault.

Download the full specification: OpenAPI YAML · OpenAPI JSON. Import it into Postman, an SDK/client generator, or your IDE.

For LLMs / AI tools: llms.txt (concise index) · llms-full.txt (full documentation text).

Using the API

The API is designed using RESTful principles: objects (resources) are identified by URLs, and actions are specified by HTTP verbs. (If that doesn't mean anything to you, don't worry — it isn't necessary for using the API.) API URLs closely mirror the URLs of the web application.

As in the web application, access to data is scoped by vault, so most API URLs contain a vault identifier. The majority of API calls return a JSON structure as the response body.

Object IDs

Vaults, saved searches, and other objects are identified by an integer ID. When you retrieve a list of objects (vaults, saved searches, projects, etc.) each object has both a name and an ID, and you typically supply the numeric ID in subsequent calls. Some parameters take lists of objects, expressed as a comma-separated list of IDs.

The same IDs appear in the web interface URLs, so you can often copy a number from the browser into an API call:

  • Browser: https://app.collaborativedrug.com/vaults/4657/searches
  • API: https://app.collaborativedrug.com/api/v1/vaults/4657/searches

Authentication & security

Every request must include your API key in the X-CDD-Token header, and all requests must be made over HTTPS so the token and data are encrypted in transit.

Access is controlled at several levels:

  • Token — tokens are issued per user/account and carry a role (set of capabilities); the effective capabilities depend on the token owner's role in the vault(s) being accessed. See the support site for how to obtain a token.
  • Vault — even with a valid token, data is only available from vaults that have API access enabled. A vault administrator can request this by emailing CDD Support.
  • Project — a user can only access data in projects they have permission for. The projects a user can access in a vault can be listed via the API.

POST /query endpoints

Most list and read endpoints accept their parameters either as URL query parameters on the GET request, or as a JSON body on a companion POST request at the same path with /query appended (for example POST /molecules/query instead of GET /molecules). The /query form exists because many HTTP client libraries cannot send a body with a GET request, and because long or complex filters are easier to express as JSON. The two forms accept the same parameters and return the same responses; the POST /query form is recommended for anything beyond a trivial request.

Pagination

List endpoints are paginated. Use page_size to set the number of records per page (default 50, maximum 1000 for synchronous requests) and offset to skip records. Paginated responses include the total count alongside the returned objects. To page through a large result set, increase offset by page_size until you have retrieved count records.

Asynchronous requests (async=true)

For large result sets, pass async=true to a query endpoint. Instead of returning the data inline, the request creates an export and returns its details (including an export id). Asynchronous exports allow a larger page_size (up to 10000). Poll GET /export_progress/{export_id} until the export reports that it is finished, then download the result from GET /exports/{export_id}. GET /exports lists all of your in-progress exports (including those started from the web application).

Rate limits and throttling

CDD Vault does not limit the total number of API requests you can make, but it does throttle usage in two ways. Please optimize your integrations to use the API efficiently, and contact CDD Support if any limit poses a problem.

  • 3 concurrent requests. Each user may have up to 3 requests in flight at once, so an integration can use up to 3 threads/processes that each issue a new request as soon as the previous one completes. This limit is per user, not per API key — important if you run multiple integrations.
  • 30 queued exports. Every request that uses async=true (and every saved-search download) launches a background export. Up to 3 run at a time and the rest queue, up to a maximum of 30 queued exports.

Use of the API is monitored; abuse may result in suspension of access and further investigation.

Authentication

ApiKeyAuthapiKey

API Key: X-CDD-Token in header

API Executions

Track asynchronous API request executions

API usage in seconds

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/api_executions

Return the API usage (both async and sync) in seconds between a particular timeframe. Use after and before parameters to specify a date range. By default and if before is used with no after, the previous 30 days are returned. The time returned is for the current API key only.

Parameters

vault_idintegerrequiredpath
afterstring<date-time>query

Start of the date range (YYYY-MM-DDThh:mm:ss±hh:mm). Defaults to 30 days before before when omitted.

beforestring<date-time>query

End of the date range (YYYY-MM-DDThh:mm:ss±hh:mm). Defaults to the current date and time when omitted.

Response

200OKobject

API usage data

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
API usage in seconds
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/api_executions' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/api_executions',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/api_executions', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "My API key": {
    "after": "2023-01-01T07:00:00.000Z",
    "before": "2023-01-22T08:12:34.000Z",
    "seconds": 20.3
  }
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Batch Move Jobs

Asynchronous batch move jobs

Get all batch move jobs

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs

Get all batch move jobs. Requires the user to be a vault administrator.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of all batch move jobs

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get all batch move jobs
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "batch": 0,
    "class": "batch move job",
    "created_at": "2024-01-15T09:30:00Z",
    "fail_on_molecule_deletion": true,
    "id": 0,
    "modified_at": "2024-01-15T09:30:00Z",
    "molecule": 0,
    "name": "string",
    "queued_job_position": 0,
    "requested_by": 0,
    "status": "requested",
    "status_message": "string"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Create a new batch move job

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs

Create a batch move job to move a batch to a different molecule in the same vault. Requires the user to be a vault administrator.

Body

application/json

Parameters for creating a batch move job, which moves a batch to a different molecule in the same vault.

batchintegerrequired

The ID of the batch to move.

fail_on_molecule_deletionbooleantrue

Fail the job if moving the batch would trigger removal of the originating molecule. Defaults to true.

moleculeintegerrequired

The ID of the molecule to move the batch to.

namestring

A new name for the batch. Optional, and only allowed for vaults without a registration system.

Parameters

vault_idintegerrequiredpath

Response

200OKobject

Batch move job created

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Create a new batch move job
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "batch": 618771089,
      "molecule": 1,
      "fail_on_molecule_deletion": true
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "batch": 618771089,
        "molecule": 1,
        "fail_on_molecule_deletion": true
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "batch": 618771089,
      "molecule": 1,
      "fail_on_molecule_deletion": true
    }),
});

const data = await response.json();
Request Body
{
  "batch": 618771089,
  "molecule": 1,
  "fail_on_molecule_deletion": true
}
{
  "batch": 0,
  "class": "batch move job",
  "created_at": "2024-01-15T09:30:00Z",
  "fail_on_molecule_deletion": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule": 0,
  "name": "string",
  "queued_job_position": 0,
  "requested_by": 0,
  "status": "requested",
  "status_message": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Retrieve a single batch move job

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}

Retrieve a single batch move job. Requires the user to be a vault administrator.

Parameters

vault_idintegerrequiredpath
job_idintegerrequiredpath

Response

200OKobject

Batch move job details

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Retrieve a single batch move job
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "batch": 0,
  "class": "batch move job",
  "created_at": "2024-01-15T09:30:00Z",
  "fail_on_molecule_deletion": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule": 0,
  "name": "string",
  "queued_job_position": 0,
  "requested_by": 0,
  "status": "requested",
  "status_message": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Cancel a single batch move job

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}

Cancel a single batch move job. Once a job has started it can no longer be canceled. Requires the user to be a vault administrator.

Parameters

vault_idintegerrequiredpath
job_idintegerrequiredpath

Response

200OKobject

Batch move job canceled

401Unauthorizedobject

Missing or invalid API key

405Method Not Allowedobject

The job is no longer in a cancelable state (it has already started or finished). The current job is returned unchanged.

Authorization

ApiKeyAuthapiKey in header
Cancel a single batch move job
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batch_move_jobs/{job_id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "batch": 0,
  "class": "batch move job",
  "created_at": "2024-01-15T09:30:00Z",
  "fail_on_molecule_deletion": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule": 0,
  "name": "string",
  "queued_job_position": 0,
  "requested_by": 0,
  "status": "requested",
  "status_message": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "batch": 0,
  "class": "batch move job",
  "created_at": "2024-01-15T09:30:00Z",
  "fail_on_molecule_deletion": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule": 0,
  "name": "string",
  "queued_job_position": 0,
  "requested_by": 0,
  "status": "requested",
  "status_message": "string"
}

Batches

Batches handling

Create a batch

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches

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. Note that in a registration vault, POST batch is the only way to create a new molecule, since the registration of a new molecule must be accompanied by a first batch. In this case, the JSON describing the batch will include a "molecule" field with detailed information on the new molecule.

Body

application/json
One of
batch_fieldsobject

Only in registration vaults

Each vault has its own settings on the minimum information required to create a new Batch (for a Vault Administrator, see Settings > Vault > Batch Fields, to change which Batch fields are required).

{: , ... }

moleculeobject | object | object
namestring
projectsArray<integer | string>

An array of project ids or names

Show child attributes
One of
integer
string
salt_namestring

A two-letter code or Salt vendor string as listed in the All Available Salts table (https://app.collaborativedrug.com/support/salts). The salt is determined automatically when the salt is included in the molecular structure.

solvent_of_crystallization_namestring

Name of the solvent of crystallization. List available at https://support.collaborativedrug.com/hc/en-us/articles/214359563-Salts-and-solvent-of-crystallization#solvents_of_crystallization

stoichiometryobject

Only in registration vaults

Show child attributes
core_countinteger
salt_countinteger
solvent_of_crystallization_countinteger

Parameters

vault_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Create a batch
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "batch_fields": {},
      "molecule": {
        "cxsmiles": "string",
        "duplicate_resolution": "first",
        "id": 0,
        "name": "string",
        "registration_type": "CHEMICAL_STRUCTURE",
        "smiles": "string",
        "structure": "string"
      },
      "name": "Batch 1",
      "projects": [
        0
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "batch_fields": {},
        "molecule": {
            "cxsmiles": "string",
            "duplicate_resolution": "first",
            "id": 0,
            "name": "string",
            "registration_type": "CHEMICAL_STRUCTURE",
            "smiles": "string",
            "structure": "string"
        },
        "name": "Batch 1",
        "projects": [
            0
        ],
        "salt_name": "string",
        "solvent_of_crystallization_name": "string",
        "stoichiometry": {
            "core_count": 0,
            "salt_count": 0,
            "solvent_of_crystallization_count": 0
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "batch_fields": {},
      "molecule": {
        "cxsmiles": "string",
        "duplicate_resolution": "first",
        "id": 0,
        "name": "string",
        "registration_type": "CHEMICAL_STRUCTURE",
        "smiles": "string",
        "structure": "string"
      },
      "name": "Batch 1",
      "projects": [
        0
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }),
});

const data = await response.json();
Request Body
{
  "batch_fields": {},
  "molecule": {
    "cxsmiles": "string",
    "duplicate_resolution": "first",
    "id": 0,
    "name": "string",
    "registration_type": "CHEMICAL_STRUCTURE",
    "smiles": "string",
    "structure": "string"
  },
  "name": "Batch 1",
  "projects": [
    0
  ],
  "salt_name": "string",
  "solvent_of_crystallization_name": "string",
  "stoichiometry": {
    "core_count": 0,
    "salt_count": 0,
    "solvent_of_crystallization_count": 0
  }
}
{
  "batch_fields": {},
  "class": "batch",
  "created_at": "2024-01-15",
  "formula_weight": 0,
  "id": 42,
  "modified_at": "2024-01-15",
  "molecule": {
    "class": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 0,
    "modified_at": "2024-01-15T09:30:00Z",
    "name": "string",
    "owner": "string",
    "projects": [
      {
        "id": 1,
        "name": "Project 1"
      }
    ],
    "registration_type": "string",
    "synonyms": [
      "string"
    ]
  },
  "molecule_batch_identifier": "DEMO-1000211-001",
  "name": "Batch 1",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "salt_name": "string",
  "solvent_of_crystallization_name": "string",
  "stoichiometry": {
    "core_count": 0,
    "salt_count": 0,
    "solvent_of_crystallization_count": 0
  }
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get multiple batches

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/query

Get the information from multiple batches. We still support the now deprecated GET queries on the enpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.

Body

application/json
One of
asyncboolean

If true, do an asynchronous export. Use for large data sets.

batch_fieldsArray<string>

Array of Batch field names to include in the resulting JSON. Defaults to all available fields.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

collection_criteriaArray<object>

Array of collection criteria objects. Filters results to only include batches whose molecules match the collection criteria, with support for AND/OR/XOR junctions and exclusion (NOT IN) logic.

Show child attributes
collection_idintegerrequired

The ID of the collection to filter by.

junctionstringANDORXORAND

How to combine this criterion with the previous one. The first criterion's junction is ignored. Defaults to "AND".

not_inbooleanfalse

If true, excludes batches whose molecules belong to this collection instead of including them. Defaults to false.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

data_setsArray<integer>

Array of public dataset ids. Defaults to all data sets.

fields_searchArray<object | object | object>

Array of Batch field names & values. Used to filter Batches returned based on query values

Show child attributes
One of
namestring

Name of the field to search

text_valuestring

Text value to search for

namestring

Name of the field to search

number_valuenumber

Number value to search for

date_valuestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

namestring

Name of the field to search

include_original_structuresbooleanfalse

If true, include the original structure in the response. This is independent of no_structures.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_batch_identifierstring

A Molecule-Batch ID used to query the Vault. Use this parameter to limit the number of Molecule UDF Fields to return

molecule_created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_fieldsArray<string>

Array of Molecule field names to include in the resulting JSON. Defaults to all available fields.

no_structuresbooleanfalse

If true, omit structure representations for a smaller and faster response.

offsetinteger
only_idsbooleanfalse

If true, only return the ids of the molecules in the batch.

only_molecule_idsbooleanfalse

If true, the full Batch details are still returned but the Molecule-level information is left out of the JSON results. (Only the IDs of the Molecules are still included.)

page_sizeinteger50

Requested page size (maximum value 1000).

projectsArray<integer>

Array of project ids. Defaults to all available projects.

protocol_criteriaArray<object>

Array of protocol-based filters restricting results to batches with (or without) matching protocol readout data. Criteria are combined using each entry's junction.

Show child attributes
protocol_idinteger

Id of the protocol to filter on (provide this or data_set_id).

data_set_idinteger

Id of the data set to filter on (provide this or protocol_id).

run_criterionstringanyrecentrun_daterun_id

Which runs to consider.

run_idinteger

Run id to match (when run_criterion is run_id).

run_afterstring<date>

Include runs on/after this date (when run_criterion is run_date).

run_beforestring<date>

Include runs on/before this date (when run_criterion is run_date).

since_days_agointeger

Number of days back to include (when run_criterion is recent).

readout_definition_idinteger

Id of the readout definition to filter on.

operatorstring=!=<>≤≥containsdoes not containfrom

Comparison operator applied to readout_value.

readout_valuestring

Value to compare the readout against.

readout_value_maximumstring

Upper bound of a range (when operator is from).

calculation_error_typestring

Filter by calculation error type.

criterion_typestringdata set or protocolrun dateprotocol field

The kind of protocol criterion.

fieldstring

Protocol field name (when criterion_type is protocol field).

querystring

Protocol field search value (when criterion_type is protocol field).

protocol_condition_idsArray<integer>

Restrict to these protocol condition ids.

negatedbooleanfalse

If true, exclude rather than include matches.

junctionstringANDORAND

How to combine this criterion with the previous one (ignored for the first criterion).

structure_criterionobject

A structure-property filter object. Each property is filtered by an optional _minimum and/or _maximum bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same <property>_minimum / <property>_maximum convention.

Show child attributes
heavy_atom_count_minimuminteger
heavy_atom_count_maximuminteger
cd_molweight_minimumnumber
cd_molweight_maximumnumber
exact_mass_minimumnumber
exact_mass_maximumnumber
log_p_minimumnumber
log_p_maximumnumber
log_d_minimumnumber
log_d_maximumnumber
log_s_minimumnumber
log_s_maximumnumber
num_aromatic_rings_minimuminteger
num_aromatic_rings_maximuminteger
num_h_bond_acceptors_minimuminteger
num_h_bond_acceptors_maximuminteger
num_h_bond_donors_minimuminteger
num_h_bond_donors_maximuminteger
num_rotatable_bonds_minimuminteger
num_rotatable_bonds_maximuminteger
num_rule_of_5_violations_minimuminteger
num_rule_of_5_violations_maximuminteger
topological_polar_surface_area_minimumnumber
topological_polar_surface_area_maximumnumber
batchesArray<integer>

Comma separated list of batch ids. Cannot be used with other parameters

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get multiple batches
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/query' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "async": true,
      "batch_fields": [
        "string"
      ],
      "created_after": "string",
      "collection_criteria": [
        {
          "collection_id": 0,
          "junction": "AND",
          "not_in": false
        }
      ],
      "created_before": "string",
      "data_sets": [
        0
      ],
      "fields_search": [
        {
          "name": "string",
          "text_value": "string"
        }
      ],
      "include_original_structures": false,
      "modified_after": "string",
      "modified_before": "string",
      "molecule_batch_identifier": "string",
      "molecule_created_after": "string",
      "molecule_created_before": "string",
      "molecule_fields": [
        "string"
      ],
      "no_structures": false,
      "offset": 0,
      "only_ids": false,
      "only_molecule_ids": false,
      "page_size": 50,
      "projects": [
        0
      ],
      "protocol_criteria": [
        {
          "protocol_id": 0,
          "data_set_id": 0,
          "run_criterion": "any",
          "run_id": 0,
          "run_after": "string",
          "run_before": "string",
          "since_days_ago": 0,
          "readout_definition_id": 0,
          "operator": "=",
          "readout_value": "string",
          "readout_value_maximum": "string",
          "calculation_error_type": "string",
          "criterion_type": "data set or protocol",
          "field": "string",
          "query": "string",
          "protocol_condition_ids": [
            0
          ],
          "negated": false,
          "junction": "AND"
        }
      ],
      "structure_criterion": {
        "heavy_atom_count_minimum": 0,
        "heavy_atom_count_maximum": 0,
        "cd_molweight_minimum": 0,
        "cd_molweight_maximum": 0,
        "exact_mass_minimum": 0,
        "exact_mass_maximum": 0,
        "log_p_minimum": 0,
        "log_p_maximum": 0,
        "log_d_minimum": 0,
        "log_d_maximum": 0,
        "log_s_minimum": 0,
        "log_s_maximum": 0,
        "num_aromatic_rings_minimum": 0,
        "num_aromatic_rings_maximum": 0,
        "num_h_bond_acceptors_minimum": 0,
        "num_h_bond_acceptors_maximum": 0,
        "num_h_bond_donors_minimum": 0,
        "num_h_bond_donors_maximum": 0,
        "num_rotatable_bonds_minimum": 0,
        "num_rotatable_bonds_maximum": 0,
        "num_rule_of_5_violations_minimum": 0,
        "num_rule_of_5_violations_maximum": 0,
        "topological_polar_surface_area_minimum": 0,
        "topological_polar_surface_area_maximum": 0
      }
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/query',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "async": true,
        "batch_fields": [
            "string"
        ],
        "created_after": "string",
        "collection_criteria": [
            {
                "collection_id": 0,
                "junction": "AND",
                "not_in": false
            }
        ],
        "created_before": "string",
        "data_sets": [
            0
        ],
        "fields_search": [
            {
                "name": "string",
                "text_value": "string"
            }
        ],
        "include_original_structures": false,
        "modified_after": "string",
        "modified_before": "string",
        "molecule_batch_identifier": "string",
        "molecule_created_after": "string",
        "molecule_created_before": "string",
        "molecule_fields": [
            "string"
        ],
        "no_structures": false,
        "offset": 0,
        "only_ids": false,
        "only_molecule_ids": false,
        "page_size": 50,
        "projects": [
            0
        ],
        "protocol_criteria": [
            {
                "protocol_id": 0,
                "data_set_id": 0,
                "run_criterion": "any",
                "run_id": 0,
                "run_after": "string",
                "run_before": "string",
                "since_days_ago": 0,
                "readout_definition_id": 0,
                "operator": "=",
                "readout_value": "string",
                "readout_value_maximum": "string",
                "calculation_error_type": "string",
                "criterion_type": "data set or protocol",
                "field": "string",
                "query": "string",
                "protocol_condition_ids": [
                    0
                ],
                "negated": false,
                "junction": "AND"
            }
        ],
        "structure_criterion": {
            "heavy_atom_count_minimum": 0,
            "heavy_atom_count_maximum": 0,
            "cd_molweight_minimum": 0,
            "cd_molweight_maximum": 0,
            "exact_mass_minimum": 0,
            "exact_mass_maximum": 0,
            "log_p_minimum": 0,
            "log_p_maximum": 0,
            "log_d_minimum": 0,
            "log_d_maximum": 0,
            "log_s_minimum": 0,
            "log_s_maximum": 0,
            "num_aromatic_rings_minimum": 0,
            "num_aromatic_rings_maximum": 0,
            "num_h_bond_acceptors_minimum": 0,
            "num_h_bond_acceptors_maximum": 0,
            "num_h_bond_donors_minimum": 0,
            "num_h_bond_donors_maximum": 0,
            "num_rotatable_bonds_minimum": 0,
            "num_rotatable_bonds_maximum": 0,
            "num_rule_of_5_violations_minimum": 0,
            "num_rule_of_5_violations_maximum": 0,
            "topological_polar_surface_area_minimum": 0,
            "topological_polar_surface_area_maximum": 0
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/query', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "async": true,
      "batch_fields": [
        "string"
      ],
      "created_after": "string",
      "collection_criteria": [
        {
          "collection_id": 0,
          "junction": "AND",
          "not_in": false
        }
      ],
      "created_before": "string",
      "data_sets": [
        0
      ],
      "fields_search": [
        {
          "name": "string",
          "text_value": "string"
        }
      ],
      "include_original_structures": false,
      "modified_after": "string",
      "modified_before": "string",
      "molecule_batch_identifier": "string",
      "molecule_created_after": "string",
      "molecule_created_before": "string",
      "molecule_fields": [
        "string"
      ],
      "no_structures": false,
      "offset": 0,
      "only_ids": false,
      "only_molecule_ids": false,
      "page_size": 50,
      "projects": [
        0
      ],
      "protocol_criteria": [
        {
          "protocol_id": 0,
          "data_set_id": 0,
          "run_criterion": "any",
          "run_id": 0,
          "run_after": "string",
          "run_before": "string",
          "since_days_ago": 0,
          "readout_definition_id": 0,
          "operator": "=",
          "readout_value": "string",
          "readout_value_maximum": "string",
          "calculation_error_type": "string",
          "criterion_type": "data set or protocol",
          "field": "string",
          "query": "string",
          "protocol_condition_ids": [
            0
          ],
          "negated": false,
          "junction": "AND"
        }
      ],
      "structure_criterion": {
        "heavy_atom_count_minimum": 0,
        "heavy_atom_count_maximum": 0,
        "cd_molweight_minimum": 0,
        "cd_molweight_maximum": 0,
        "exact_mass_minimum": 0,
        "exact_mass_maximum": 0,
        "log_p_minimum": 0,
        "log_p_maximum": 0,
        "log_d_minimum": 0,
        "log_d_maximum": 0,
        "log_s_minimum": 0,
        "log_s_maximum": 0,
        "num_aromatic_rings_minimum": 0,
        "num_aromatic_rings_maximum": 0,
        "num_h_bond_acceptors_minimum": 0,
        "num_h_bond_acceptors_maximum": 0,
        "num_h_bond_donors_minimum": 0,
        "num_h_bond_donors_maximum": 0,
        "num_rotatable_bonds_minimum": 0,
        "num_rotatable_bonds_maximum": 0,
        "num_rule_of_5_violations_minimum": 0,
        "num_rule_of_5_violations_maximum": 0,
        "topological_polar_surface_area_minimum": 0,
        "topological_polar_surface_area_maximum": 0
      }
    }),
});

const data = await response.json();
Request Body
{
  "async": true,
  "batch_fields": [
    "string"
  ],
  "created_after": "2024-01-15",
  "collection_criteria": [
    {
      "collection_id": 0,
      "junction": "AND",
      "not_in": false
    }
  ],
  "created_before": "2024-01-15",
  "data_sets": [
    0
  ],
  "fields_search": [
    {
      "name": "string",
      "text_value": "string"
    }
  ],
  "include_original_structures": false,
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "molecule_batch_identifier": "string",
  "molecule_created_after": "2024-01-15",
  "molecule_created_before": "2024-01-15",
  "molecule_fields": [
    "string"
  ],
  "no_structures": false,
  "offset": 0,
  "only_ids": false,
  "only_molecule_ids": false,
  "page_size": 50,
  "projects": [
    0
  ],
  "protocol_criteria": [
    {
      "protocol_id": 0,
      "data_set_id": 0,
      "run_criterion": "any",
      "run_id": 0,
      "run_after": "2024-01-15",
      "run_before": "2024-01-15",
      "since_days_ago": 0,
      "readout_definition_id": 0,
      "operator": "=",
      "readout_value": "string",
      "readout_value_maximum": "string",
      "calculation_error_type": "string",
      "criterion_type": "data set or protocol",
      "field": "string",
      "query": "string",
      "protocol_condition_ids": [
        0
      ],
      "negated": false,
      "junction": "AND"
    }
  ],
  "structure_criterion": {
    "heavy_atom_count_minimum": 0,
    "heavy_atom_count_maximum": 0,
    "cd_molweight_minimum": 0,
    "cd_molweight_maximum": 0,
    "exact_mass_minimum": 0,
    "exact_mass_maximum": 0,
    "log_p_minimum": 0,
    "log_p_maximum": 0,
    "log_d_minimum": 0,
    "log_d_maximum": 0,
    "log_s_minimum": 0,
    "log_s_maximum": 0,
    "num_aromatic_rings_minimum": 0,
    "num_aromatic_rings_maximum": 0,
    "num_h_bond_acceptors_minimum": 0,
    "num_h_bond_acceptors_maximum": 0,
    "num_h_bond_donors_minimum": 0,
    "num_h_bond_donors_maximum": 0,
    "num_rotatable_bonds_minimum": 0,
    "num_rotatable_bonds_maximum": 0,
    "num_rule_of_5_violations_minimum": 0,
    "num_rule_of_5_violations_maximum": 0,
    "topological_polar_surface_area_minimum": 0,
    "topological_polar_surface_area_maximum": 0
  }
}
[
  {
    "batch_fields": {},
    "class": "batch",
    "created_at": "2024-01-15",
    "formula_weight": 0,
    "id": 42,
    "modified_at": "2024-01-15",
    "molecule": {
      "class": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "name": "string",
      "owner": "string",
      "projects": [
        {
          "id": 1,
          "name": "Project 1"
        }
      ],
      "registration_type": "string",
      "synonyms": [
        "string"
      ]
    },
    "molecule_batch_identifier": "DEMO-1000211-001",
    "name": "Batch 1",
    "owner": "Charlie Weatherall",
    "projects": [
      {
        "id": 1,
        "name": "Project 1"
      }
    ],
    "salt_name": "string",
    "solvent_of_crystallization_name": "string",
    "stoichiometry": {
      "core_count": 0,
      "salt_count": 0,
      "solvent_of_crystallization_count": 0
    }
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get a single batch

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}

Get the information about a single batch

Parameters

vault_idintegerrequiredpath
batch_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get a single batch
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "batch_fields": {},
  "class": "batch",
  "created_at": "2024-01-15",
  "formula_weight": 0,
  "id": 42,
  "modified_at": "2024-01-15",
  "molecule": {
    "class": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 0,
    "modified_at": "2024-01-15T09:30:00Z",
    "name": "string",
    "owner": "string",
    "projects": [
      {
        "id": 1,
        "name": "Project 1"
      }
    ],
    "registration_type": "string",
    "synonyms": [
      "string"
    ]
  },
  "molecule_batch_identifier": "DEMO-1000211-001",
  "name": "Batch 1",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "salt_name": "string",
  "solvent_of_crystallization_name": "string",
  "stoichiometry": {
    "core_count": 0,
    "salt_count": 0,
    "solvent_of_crystallization_count": 0
  }
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Update a batch

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}

See Create for valid fields. (An exception to this is the Molecule field - this PUT Batches call should not be used to update the chemical structure of the parent Molecule - use the PUT Molecules API call to achieve this.) Fields not specified in the JSON are not changed.

To delete a Batch, simply submit with an empty projects array. (For safety/security purposes, Batches which have data associated with them cannot be deleted via this PUT Batches API call. Data (such as rows of readout data in a Protocol Run) must be removed prior to using the PUT Batches API call to delete a Batch.)

Note that the ID for the batch 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).

Body

application/json
One of
batch_fieldsobject

Only in registration vaults

Each vault has its own settings on the minimum information required to create a new Batch (for a Vault Administrator, see Settings > Vault > Batch Fields, to change which Batch fields are required).

{: , ... }

moleculeobject | object | object
namestring
projectsArray<integer | string>

An array of project ids or names

Show child attributes
One of
integer
string
salt_namestring

A two-letter code or Salt vendor string as listed in the All Available Salts table (https://app.collaborativedrug.com/support/salts). The salt is determined automatically when the salt is included in the molecular structure.

solvent_of_crystallization_namestring

Name of the solvent of crystallization. List available at https://support.collaborativedrug.com/hc/en-us/articles/214359563-Salts-and-solvent-of-crystallization#solvents_of_crystallization

stoichiometryobject

Only in registration vaults

Show child attributes
core_countinteger
salt_countinteger
solvent_of_crystallization_countinteger

Parameters

vault_idintegerrequiredpath
batch_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Update a batch
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "batch_fields": {},
      "molecule": {
        "cxsmiles": "string",
        "duplicate_resolution": "first",
        "id": 0,
        "name": "string",
        "registration_type": "CHEMICAL_STRUCTURE",
        "smiles": "string",
        "structure": "string"
      },
      "name": "Batch 1",
      "projects": [
        0
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "batch_fields": {},
        "molecule": {
            "cxsmiles": "string",
            "duplicate_resolution": "first",
            "id": 0,
            "name": "string",
            "registration_type": "CHEMICAL_STRUCTURE",
            "smiles": "string",
            "structure": "string"
        },
        "name": "Batch 1",
        "projects": [
            0
        ],
        "salt_name": "string",
        "solvent_of_crystallization_name": "string",
        "stoichiometry": {
            "core_count": 0,
            "salt_count": 0,
            "solvent_of_crystallization_count": 0
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "batch_fields": {},
      "molecule": {
        "cxsmiles": "string",
        "duplicate_resolution": "first",
        "id": 0,
        "name": "string",
        "registration_type": "CHEMICAL_STRUCTURE",
        "smiles": "string",
        "structure": "string"
      },
      "name": "Batch 1",
      "projects": [
        0
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }),
});

const data = await response.json();
Request Body
{
  "batch_fields": {},
  "molecule": {
    "cxsmiles": "string",
    "duplicate_resolution": "first",
    "id": 0,
    "name": "string",
    "registration_type": "CHEMICAL_STRUCTURE",
    "smiles": "string",
    "structure": "string"
  },
  "name": "Batch 1",
  "projects": [
    0
  ],
  "salt_name": "string",
  "solvent_of_crystallization_name": "string",
  "stoichiometry": {
    "core_count": 0,
    "salt_count": 0,
    "solvent_of_crystallization_count": 0
  }
}
{
  "batch_fields": {},
  "class": "batch",
  "created_at": "2024-01-15",
  "formula_weight": 0,
  "id": 42,
  "modified_at": "2024-01-15",
  "molecule": {
    "class": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 0,
    "modified_at": "2024-01-15T09:30:00Z",
    "name": "string",
    "owner": "string",
    "projects": [
      {
        "id": 1,
        "name": "Project 1"
      }
    ],
    "registration_type": "string",
    "synonyms": [
      "string"
    ]
  },
  "molecule_batch_identifier": "DEMO-1000211-001",
  "name": "Batch 1",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "salt_name": "string",
  "solvent_of_crystallization_name": "string",
  "stoichiometry": {
    "core_count": 0,
    "salt_count": 0,
    "solvent_of_crystallization_count": 0
  }
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Collections

Collections of molecules

Create a collection

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections

Create a collection, the name should be unique unless you want to overwrite an existing collection.

Body

application/json
One of
classstringuser collection
created_atstring<date>
modified_atstring<date>
moleculesArray<integer>

The list of molecules in the collection.

namestring
ownerstring

Parameters

vault_idintegerrequiredpath

Response

200OKobject & object

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Create a collection
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "class": "user collection",
      "created_at": "string",
      "modified_at": "string",
      "molecules": [
        0
      ],
      "name": "Rare compounds",
      "owner": "Jacob Bloom"
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "class": "user collection",
        "created_at": "string",
        "modified_at": "string",
        "molecules": [
            0
        ],
        "name": "Rare compounds",
        "owner": "Jacob Bloom"
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "class": "user collection",
      "created_at": "string",
      "modified_at": "string",
      "molecules": [
        0
      ],
      "name": "Rare compounds",
      "owner": "Jacob Bloom"
    }),
});

const data = await response.json();
Request Body
{
  "class": "user collection",
  "created_at": "2024-01-15",
  "modified_at": "2024-01-15",
  "molecules": [
    0
  ],
  "name": "Rare compounds",
  "owner": "Jacob Bloom"
}
{
  "id": 42,
  "class": "user collection",
  "created_at": "2024-01-15",
  "modified_at": "2024-01-15",
  "molecules": [
    0
  ],
  "name": "Rare compounds",
  "owner": "Jacob Bloom"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get multiple collections

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/query

Get the information from multiple collections. We still support the now deprecated GET queries on the enpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.

Body

application/json
One of
One of
collectionsArray<integer>

The list of collections id to return

asyncboolean

If true, do an asynchronous export. Use for large data sets. You will get an export id that you can use with the async export function.

include_molecule_idsboolean

If true, include the ids of the molecules in the collection.

offsetinteger

The offset of the first collection in the result set. The offset is 0-based. That is, the first collection in the result set has offset 0.

only_idsboolean

If true, only return the ids of the matching collections.

page_sizeinteger50

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 call that also uses the async=true parameter will be ignored. The async call will return all valid data once executed.

projectsArray<integer>

Array of project ids. Defaults to all available projects.

asyncboolean

If true, do an asynchronous export. Use for large data sets. You will get an export id that you can use with the async export function.

include_molecule_idsboolean

If true, include the ids of the molecules in the collection.

offsetinteger

The offset of the first collection in the result set. The offset is 0-based. That is, the first collection in the result set has offset 0.

only_idsboolean

If true, only return the ids of the matching collections.

page_sizeinteger50

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 call that also uses the async=true parameter will be ignored. The async call will return all valid data once executed.

projectsArray<integer>

Array of project ids. Defaults to all available projects.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

typestringuser_collectionvault_collection

The type of collection user collections are private, vault collections are shared with project members.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object & object>

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get multiple collections
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/query' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "collections": [
        0
      ],
      "async": true,
      "include_molecule_ids": true,
      "offset": 0,
      "only_ids": true,
      "page_size": 50,
      "projects": [
        0
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/query',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "collections": [
            0
        ],
        "async": true,
        "include_molecule_ids": true,
        "offset": 0,
        "only_ids": true,
        "page_size": 50,
        "projects": [
            0
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/query', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "collections": [
        0
      ],
      "async": true,
      "include_molecule_ids": true,
      "offset": 0,
      "only_ids": true,
      "page_size": 50,
      "projects": [
        0
      ]
    }),
});

const data = await response.json();
Request Body
{
  "collections": [
    0
  ],
  "async": true,
  "include_molecule_ids": true,
  "offset": 0,
  "only_ids": true,
  "page_size": 50,
  "projects": [
    0
  ]
}
[
  {
    "id": 42,
    "class": "user collection",
    "created_at": "2024-01-15",
    "modified_at": "2024-01-15",
    "molecules": [
      0
    ],
    "name": "Rare compounds",
    "owner": "Jacob Bloom"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get a single collection

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}

Get the information about a single collection

Parameters

vault_idintegerrequiredpath
collection_idintegerrequiredpath

Response

200OKobject & object

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get a single collection
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "id": 42,
  "class": "user collection",
  "created_at": "2024-01-15",
  "modified_at": "2024-01-15",
  "molecules": [
    0
  ],
  "name": "Rare compounds",
  "owner": "Jacob Bloom"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Update a collection

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}

Body

application/json
One of
moleculesArray<integer>

The list of molecules to add to the collection. Note that you cannot remove molecules from a collection. You have to recreate the collection without the molecule.

Parameters

vault_idintegerrequiredpath
collection_idintegerrequiredpath

Response

200OKobject & object

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Update a collection
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "molecules": [
        0
      ]
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "molecules": [
            0
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "molecules": [
        0
      ]
    }),
});

const data = await response.json();
Request Body
{
  "molecules": [
    0
  ]
}
{
  "id": 42,
  "class": "user collection",
  "created_at": "2024-01-15",
  "modified_at": "2024-01-15",
  "molecules": [
    0
  ],
  "name": "Rare compounds",
  "owner": "Jacob Bloom"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Delete a collection

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}

Delete a collection. The molecules in the collection are not affected.

Parameters

vault_idintegerrequiredpath
collection_idintegerrequiredpath

Numeric identifier of the collection

Response

200OKobject

The collection was deleted

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Collection not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Delete a collection
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/collections/{collection_id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "message": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Control Layouts

Control well layouts for protocols and runs

Get control layouts

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts

List the control layouts in the vault. Supports pagination via page_size and offset, and the usual created_after/modified_after filters.

Parameters

vault_idintegerrequiredpath
page_sizeintegerquery

Maximum number of records to return (default 50, maximum 1000).

offsetintegerquery

Number of records to skip (for pagination).

asyncbooleanquery

If true, run the listing as an asynchronous export.

only_idsbooleanquery

If true, return only the ids of the matching control layouts.

projectsstringquery

Comma-separated project ids to filter by.

created_afterstring<date-time>query

Only include layouts created on or after this time.

created_beforestring<date-time>query

Only include layouts created on or before this time.

modified_afterstring<date-time>query

Only include layouts modified on or after this time.

modified_beforestring<date-time>query

Only include layouts modified on or before this time.

Response

200OKobject

A page of control layouts

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get control layouts
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "count": 0,
  "objects": [
    {
      "class": "control layout",
      "control_wells": [
        {
          "col": 0,
          "control_state": "+",
          "row": 0
        }
      ],
      "created_at": "2024-01-15T09:30:00Z",
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "plate_id": 0,
      "protocol": 0,
      "run": 0,
      "size": 0
    }
  ],
  "offset": 0,
  "page_size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Create a control layout

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts

Create a control layout for a protocol or run. The layout dimensions are set with either size or plate, and the target with either protocol or run.

Body

application/json

Attributes for creating a control layout. Specify the target with exactly one of protocol or run, and the layout dimensions with exactly one of size or plate.

One of
any
any
One of
any
any

Parameters

vault_idintegerrequiredpath

Response

200OKobject

The created control layout

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Create a control layout
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "protocol": 321,
      "size": 96,
      "control_wells": [
        {
          "row": 0,
          "col": 0,
          "control_state": "+"
        },
        {
          "pos": "H12",
          "control_state": "-"
        }
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "protocol": 321,
        "size": 96,
        "control_wells": [
            {
                "row": 0,
                "col": 0,
                "control_state": "+"
            },
            {
                "pos": "H12",
                "control_state": "-"
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "protocol": 321,
      "size": 96,
      "control_wells": [
        {
          "row": 0,
          "col": 0,
          "control_state": "+"
        },
        {
          "pos": "H12",
          "control_state": "-"
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "protocol": 321,
  "size": 96,
  "control_wells": [
    {
      "row": 0,
      "col": 0,
      "control_state": "+"
    },
    {
      "pos": "H12",
      "control_state": "-"
    }
  ]
}
{
  "class": "control layout",
  "control_wells": [
    {
      "col": 0,
      "control_state": "+",
      "row": 0
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "plate_id": 0,
  "protocol": 0,
  "run": 0,
  "size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a control layout

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}

Retrieve a single control layout.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the control layout

Response

200OKobject

The control layout

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Control layout not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a control layout
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "class": "control layout",
  "control_wells": [
    {
      "col": 0,
      "control_state": "+",
      "row": 0
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "plate_id": 0,
  "protocol": 0,
  "run": 0,
  "size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Delete a control layout

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}

Delete a control layout.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the control layout

Response

200OK

The control layout was deleted

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Control layout not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Delete a control layout
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/control_layouts/{id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Datasets

Public and vault datasets

Get dataset

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/data_sets

List datasets

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

Success

404Not Found

Unauthorized or not found

Authorization

ApiKeyAuthapiKey in header
Get dataset
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/data_sets' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/data_sets',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/data_sets', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
200
[
  {
    "id": 0,
    "name": "string"
  }
]

Deep Learning Bioisosteres

Deep learning bioisostere suggestions

Find bioisosteric replacements (hierarchical)

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres

Submit a chemical structure and receive bioisosteric replacement suggestions grouped by fragment. Requires the vault to have Deep Learning enabled.

Body

application/json
structurestringrequired

SMILES or MOL representation of structure to find bioisosteric replacements for.

number_suggestionsinteger

Number of bioisosteric suggestions per fragment. Defaults to 5, max 200.

return_known_identifiersboolean

Include known identifiers (InChIKey, etc.) in response. Defaults to false.

lookup_internal_identifiersboolean

Opt in to server-side enrichment with internal vault identifiers. When true, each bioisostere's InChIKey is used to find molecules in the Vault. The 14-character prefix of the InChIKey is used to catch stereochemical variants. The internal identifiers are appended to the identifiers array as an Internal collection. Defaults to false.

filter_structure_alertsboolean

Filter out suggestions with additional structural alerts. Defaults to true.

filter_by_atom_indicesArray<integer>

List of atom indices identifying which fragments to include in fragmentation. Each suggestion fragment whose atom_indices overlaps this list is kept. If omitted, all fragments are used.

Parameters

vault_idintegerrequiredpath

ID of the current vault.

X-CDD-Tokenstringrequiredheader

API key token for authentication.

Response

200OKobject

Success — returns bioisosteric suggestions grouped by fragment.

400Bad Requestobject

Bad request — missing or invalid parameters.

401Unauthorizedobject

Unauthorized — Deep Learning not enabled for this vault or user lacks access.

Find bioisosteric replacements (hierarchical)
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres' \
  -H 'Content-Type: application/json' \
  -d '{
      "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
      "number_suggestions": 5,
      "return_known_identifiers": false,
      "lookup_internal_identifiers": false,
      "filter_structure_alerts": true,
      "filter_by_atom_indices": [
        0,
        1
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres',
    json={
        "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
        "number_suggestions": 5,
        "return_known_identifiers": false,
        "lookup_internal_identifiers": false,
        "filter_structure_alerts": true,
        "filter_by_atom_indices": [
            0,
            1
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
      "number_suggestions": 5,
      "return_known_identifiers": false,
      "lookup_internal_identifiers": false,
      "filter_structure_alerts": true,
      "filter_by_atom_indices": [
        0,
        1
      ]
    }),
});

const data = await response.json();
Request Body
{
  "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
  "number_suggestions": 5,
  "return_known_identifiers": false,
  "lookup_internal_identifiers": false,
  "filter_structure_alerts": true,
  "filter_by_atom_indices": [
    0,
    1
  ]
}
{
  "status": "OK",
  "mocked_service": true,
  "result": {
    "query": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
    "suggestions": [
      {
        "fragment": "[16*]c1ccc(Cl)cc1Cl",
        "size": 8,
        "atom_indices": [
          0,
          1
        ],
        "bioisosteres": [
          {
            "fragment": "[16*]c1ccc(F)cc1Cl",
            "inchikey": "QCNPSEBNVBYHLY-UHFFFAOYSA-N",
            "structure": "c1ccncc1",
            "tanimoto": 0.875,
            "atom_indices": [
              0,
              1
            ],
            "synthetic_feasibility": {
              "synthetic_feasibility_score": 0.9,
              "profile_overlap": 0.8,
              "bits_missing": 0.1,
              "fraction_missing": 0.2
            },
            "alerts": [
              {
                "filter_set": "Brenk",
                "description": "aniline"
              }
            ],
            "identifiers": [
              {
                "name": "SCHEMBL11832241",
                "collection": "SureChEMBL",
                "patent": {
                  "count": 1,
                  "first_date": "1976-01-20T00:00:00.000Z",
                  "first_patent": "US-3933824-A"
                },
                "cdd_public": {
                  "molecule_id": 123456
                },
                "cdd_private": {
                  "id": 123456,
                  "standard_inchi_key": "QCNPSEBNVBYHLY-UHFFFAOYSA-N",
                  "exact": true
                }
              }
            ]
          }
        ]
      }
    ]
  }
}
{
  "error": "structure parameter is required",
  "code": 400
}
{
  "error": "Dl bioisosteres endpoint only accessible in vaults with Deep Learning enabled",
  "code": 401
}

Find bioisosteric replacements (flat list)

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/flat

Submit a chemical structure and receive bioisosteric replacement suggestions as a flat list. Requires the vault to have Deep Learning enabled.

Body

application/json
structurestringrequired

SMILES or MOL representation of structure to find bioisosteric replacements for.

number_suggestionsinteger

Number of bioisosteric suggestions per fragment. Defaults to 5, max 200.

return_known_identifiersboolean

Include known identifiers (InChIKey, etc.) in response. Defaults to false.

lookup_internal_identifiersboolean

Opt in to server-side enrichment with internal vault identifiers. When true, each bioisostere's InChIKey is used to find molecules in the Vault. The 14-character prefix of the InChIKey is used to catch stereochemical variants. The internal identifiers are appended to the identifiers array as an Internal collection. Defaults to false.

filter_structure_alertsboolean

Filter out suggestions with additional structural alerts. Defaults to true.

filter_by_atom_indicesArray<integer>

List of atom indices identifying which fragments to include in fragmentation. Each suggestion fragment whose atom_indices overlaps this list is kept. If omitted, all fragments are used.

Parameters

vault_idintegerrequiredpath

ID of the current vault.

X-CDD-Tokenstringrequiredheader

API key token for authentication.

Response

200OKobject

Success — returns bioisosteric suggestions as a flat list.

400Bad Requestobject

Bad request — missing or invalid parameters.

401Unauthorizedobject

Unauthorized — Deep Learning not enabled for this vault or user lacks access.

Find bioisosteric replacements (flat list)
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/flat' \
  -H 'Content-Type: application/json' \
  -d '{
      "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
      "number_suggestions": 5,
      "return_known_identifiers": false,
      "lookup_internal_identifiers": false,
      "filter_structure_alerts": true,
      "filter_by_atom_indices": [
        0,
        1
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/flat',
    json={
        "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
        "number_suggestions": 5,
        "return_known_identifiers": false,
        "lookup_internal_identifiers": false,
        "filter_structure_alerts": true,
        "filter_by_atom_indices": [
            0,
            1
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/flat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
      "number_suggestions": 5,
      "return_known_identifiers": false,
      "lookup_internal_identifiers": false,
      "filter_structure_alerts": true,
      "filter_by_atom_indices": [
        0,
        1
      ]
    }),
});

const data = await response.json();
Request Body
{
  "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
  "number_suggestions": 5,
  "return_known_identifiers": false,
  "lookup_internal_identifiers": false,
  "filter_structure_alerts": true,
  "filter_by_atom_indices": [
    0,
    1
  ]
}
{
  "query": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
  "suggestions": [
    {
      "structure": "Fc1ccc(-c2n[nH]c3c2CCNCC3)cc1F",
      "fragment": "[16*]c1ccc(Cl)cc1Cl",
      "replacement_fragment": "[16*]c1ccc(F)cc1F",
      "tanimoto": 0.875,
      "synthetic_feasibility_score": 0.9,
      "identifiers": "SCHEMBL11832241, CHEMBL12345678",
      "alerts": "acid_halide,carbonyl_halide"
    }
  ]
}
{
  "error": "structure parameter is required",
  "code": 400
}
{
  "error": "Dl bioisosteres endpoint only accessible in vaults with Deep Learning enabled",
  "code": 401
}

Fragment a chemical structure

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/get_fragmentation

Submit a chemical structure and receive its fragmentation without bioisosteric suggestions. Requires the vault to have Deep Learning enabled.

Body

application/json
structurestringrequired

SMILES or MOL representation of structure to fragment.

Parameters

vault_idintegerrequiredpath

ID of the current vault.

X-CDD-Tokenstringrequiredheader

API key token for authentication.

Response

200OKobject

Success — returns the fragmentation of the structure.

400Bad Requestobject

Bad request — missing or invalid parameters.

401Unauthorizedobject

Unauthorized — Deep Learning not enabled for this vault or user lacks access.

Fragment a chemical structure
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/get_fragmentation' \
  -H 'Content-Type: application/json' \
  -d '{
      "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1"
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/get_fragmentation',
    json={
        "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1"
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/bioisosteres/get_fragmentation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1"
    }),
});

const data = await response.json();
Request Body
{
  "structure": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1"
}
{
  "status": "OK",
  "mocked_service": true,
  "result": {
    "query": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1",
    "suggestions": [
      {
        "fragment": "[16*]c1ccc(Cl)cc1Cl",
        "size": 8,
        "atom_indices": [
          0,
          1
        ]
      }
    ]
  }
}
{
  "error": "structure parameter is required",
  "code": 400
}
{
  "error": "Dl bioisosteres endpoint only accessible in vaults with Deep Learning enabled",
  "code": 401
}

Deep Learning Similarity

Deep learning molecular similarity

Find similar structures using Deep Learning

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/similarity

Submit a chemical structure and receive a ranked list of similar structures using the Deep Learning similarity model. Requires the vault to have Deep Learning enabled.

Body

application/json
structurestringrequired

SMILES or MOL representation to find similar structures for.

countinteger

Number of similar structures to return. Defaults to 10, max 300.

collectionsArray<string>

List of collection identifiers to filter results by. If omitted, all collections are included.

return_patentsboolean

Whether to include patent information for compounds in results. Defaults to true.

lookup_internal_identifiersboolean

Opt in to server-side enrichment with internal vault identifiers. When true, each hit's InChIKey is used to find molecules in the Vault. The 14-character prefix of the InChIKey is used to catch stereochemical variants. The internal identifiers are appended to the identifiers array as an Internal collection. Defaults to false.

Parameters

vault_idintegerrequiredpath

ID of the current vault.

X-CDD-Tokenstringrequiredheader

API key token for authentication.

Response

200OKobject

Success — returns similar structures ranked by Tanimoto similarity.

400Bad Requestobject

Bad request — missing or invalid parameters.

401Unauthorizedobject

Unauthorized — Deep Learning not enabled for this vault or user lacks access.

Find similar structures using Deep Learning
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/similarity' \
  -H 'Content-Type: application/json' \
  -d '{
      "structure": "c1ccccc1",
      "count": 10,
      "collections": [
        "SureChEMBL",
        "ChEMBL"
      ],
      "return_patents": true,
      "lookup_internal_identifiers": false
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/similarity',
    json={
        "structure": "c1ccccc1",
        "count": 10,
        "collections": [
            "SureChEMBL",
            "ChEMBL"
        ],
        "return_patents": true,
        "lookup_internal_identifiers": false
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/ai/similarity', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "structure": "c1ccccc1",
      "count": 10,
      "collections": [
        "SureChEMBL",
        "ChEMBL"
      ],
      "return_patents": true,
      "lookup_internal_identifiers": false
    }),
});

const data = await response.json();
Request Body
{
  "structure": "c1ccccc1",
  "count": 10,
  "collections": [
    "SureChEMBL",
    "ChEMBL"
  ],
  "return_patents": true,
  "lookup_internal_identifiers": false
}
{
  "status": "OK",
  "mocked_service": true,
  "result": {
    "query": "Nc1ccccc1CCCC",
    "query_scaffold": "c1ccccc1",
    "hits": [
      {
        "structure": "Cc1ccncc1",
        "inchikey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
        "identifiers": [
          {
            "name": "SCHEMBL11832241",
            "collection": "SureChEMBL",
            "patent": {
              "count": 1,
              "first_date": "1976-01-20T00:00:00.000Z",
              "first_patent": "US-3933824-A"
            },
            "cdd_public": {
              "molecule_id": 123456
            },
            "cdd_private": {
              "id": 123456,
              "standard_inchi_key": "QCNPSEBNVBYHLY-UHFFFAOYSA-N",
              "exact": true
            }
          }
        ],
        "names": [
          "Compound A",
          "CDD-123456"
        ],
        "scaffold": "c1ccncc1",
        "similarity": 0.851,
        "tanimoto": 0.123,
        "distance": 10.15
      }
    ],
    "metadata": [
      {
        "collection": "CDD Public",
        "search_engine": "faiss",
        "metric": "Metric.L2",
        "count": 123456,
        "release": "2024-06"
      }
    ]
  }
}
{
  "error": "structure parameter is required",
  "code": 400
}
{
  "error": "Dl similarity endpoint only accessible in vaults with Deep Learning enabled",
  "code": 401
}

Dose Response Calculations

Protocol dose response calculations management

List dose response calculations for a protocol

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations

Get all dose response calculations for a protocol.

Parameters

vault_idintegerrequiredpath
protocol_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Protocol not found

Authorization

ApiKeyAuthapiKey in header
List dose response calculations for a protocol
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "objects": [
    {
      "id": 12345,
      "class": "dose response calculation",
      "inputs": {},
      "outputs": {},
      "fit_parameters": {
        "min": {
          "modifier": "=",
          "value": 0
        },
        "max": {
          "modifier": ">=",
          "value": 100
        }
      },
      "minimum_activity": {
        "lower": 10,
        "upper": 90
      }
    }
  ],
  "count": 5
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a single dose response calculation

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}

Get the details of a single dose response calculation

Parameters

vault_idintegerrequiredpath
protocol_idintegerrequiredpath
dose_response_calculation_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Protocol or dose response calculation not found

Authorization

ApiKeyAuthapiKey in header
Get a single dose response calculation
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "id": 12345,
  "class": "dose response calculation",
  "inputs": {},
  "outputs": {},
  "fit_parameters": {
    "min": {
      "modifier": "=",
      "value": 0
    },
    "max": {
      "modifier": ">=",
      "value": 100
    }
  },
  "minimum_activity": {
    "lower": 10,
    "upper": 90
  }
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a dose response calculation

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}

Update a dose response calculation's fit parameters and/or minimum activity bounds.

To set a fixed constraint, use modifier "=" with a value. To set a range constraint, use modifier "from" with a range object containing min and max. To set a comparison constraint, use modifier ">", ">=", "<", or "<=" with a value. To clear all fit parameter constraints, pass an empty fit_parameters object.

Body

application/json

Request body for updating a dose response calculation

fit_parametersobject

Fit parameter constraints for the calculation. Setting this to an empty object clears all constraints. The available parameters depend on the calculation's equation_type:

  • Hill: min, max, slope
  • Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2
  • Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2
  • Linear: slope, y_intercept
  • Exponential Decay: c_0, c_min, k
  • Michaelis-Menten: b_max, k_d
minimum_activityobject

Minimum activity (inactivity) bounds

Show child attributes
lowernumber | null

The lower bound for the inactive range

uppernumber | null

The upper bound for the inactive range

modifierstring

The modifier type. If not specified, it is inferred from the bounds (">", "<", or "from" for range).

Parameters

vault_idintegerrequiredpath
protocol_idintegerrequiredpath
dose_response_calculation_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key or insufficient permissions

404Not Foundobject

Protocol or dose response calculation not found

422Unprocessable Entityobject

Validation error. Possible causes include: unknown fit parameter, invalid modifier, range where lower > upper, non-numeric value, or unrecognized parameters.

Authorization

ApiKeyAuthapiKey in header
Update a dose response calculation
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "fit_parameters": {},
      "minimum_activity": {
        "lower": 10,
        "upper": 90,
        "modifier": "from"
      }
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "fit_parameters": {},
        "minimum_activity": {
            "lower": 10,
            "upper": 90,
            "modifier": "from"
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "fit_parameters": {},
      "minimum_activity": {
        "lower": 10,
        "upper": 90,
        "modifier": "from"
      }
    }),
});

const data = await response.json();
Request Body
{
  "fit_parameters": {},
  "minimum_activity": {
    "lower": 10,
    "upper": 90,
    "modifier": "from"
  }
}
{
  "id": 12345,
  "class": "dose response calculation",
  "inputs": {},
  "outputs": {},
  "fit_parameters": {
    "min": {
      "modifier": "=",
      "value": 0
    },
    "max": {
      "modifier": ">=",
      "value": 100
    }
  },
  "minimum_activity": {
    "lower": 10,
    "upper": 90
  }
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Dose Response Data Series

Dose response data series management

List dose response data series for a dose response calculation

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series

Get all dose response data series for a dose response calculation. Each data series represents the curve data for a specific batch/run combination.

Parameters

vault_idintegerrequiredpath
protocol_idintegerrequiredpath
dose_response_calculation_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Protocol or dose response calculation not found

Authorization

ApiKeyAuthapiKey in header
List dose response data series for a dose response calculation
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "objects": [
    {
      "id": 67890,
      "fit_parameters": {
        "min": {
          "modifier": "=",
          "value": 0
        },
        "max": {
          "modifier": ">=",
          "value": 100
        }
      },
      "updated_at": "2026-01-30T14:42:24.000Z"
    }
  ],
  "count": 10
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a single dose response data series

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}

Get the details of a single dose response data series

Parameters

vault_idintegerrequiredpath
protocol_idintegerrequiredpath
dose_response_calculation_idintegerrequiredpath
dose_response_data_series_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Protocol, dose response calculation, or dose response data series not found

Authorization

ApiKeyAuthapiKey in header
Get a single dose response data series
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "id": 67890,
  "fit_parameters": {
    "min": {
      "modifier": "=",
      "value": 0
    },
    "max": {
      "modifier": ">=",
      "value": 100
    }
  },
  "updated_at": "2026-01-30T14:42:24.000Z"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a dose response data series

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}

Update a dose response data series's fit parameters. These constraints override the calculation-level constraints for this specific curve.

To set a fixed constraint, use modifier "=" with a value. To set a range constraint, use modifier "from" with a range object containing min and max. To set a comparison constraint, use modifier ">", ">=", "<", or "<=" with a value. To set unconstrained (best fit), use modifier "best fit" (data series only).

Body

application/json

Request body for updating a data series

fit_parametersobject

Fit parameter constraints for this data series. These override the calculation-level constraints for this specific curve. The available parameters depend on the calculation's equation_type:

  • Hill: min, max, slope
  • Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2
  • Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2
  • Linear: slope, y_intercept
  • Exponential Decay: c_0, c_min, k
  • Michaelis-Menten: b_max, k_d Data series support "best fit" modifier for unconstrained fitting.

Parameters

vault_idintegerrequiredpath
protocol_idintegerrequiredpath
dose_response_calculation_idintegerrequiredpath
dose_response_data_series_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key or insufficient permissions

404Not Foundobject

Protocol, dose response calculation, or dose response data series not found

422Unprocessable Entityobject

Validation error. Possible causes include: unknown fit parameter, invalid modifier, range where lower > upper, or non-numeric value.

Authorization

ApiKeyAuthapiKey in header
Update a dose response data series
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "fit_parameters": {}
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "fit_parameters": {}
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "fit_parameters": {}
    }),
});

const data = await response.json();
Request Body
{
  "fit_parameters": {}
}
{
  "id": 67890,
  "fit_parameters": {
    "min": {
      "modifier": "=",
      "value": 0
    },
    "max": {
      "modifier": ">=",
      "value": 100
    }
  },
  "updated_at": "2026-01-30T14:42:24.000Z"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

ELN Entries

Electronic lab notebook entries

Create an ELN entry

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries

The body of the POST must contain a JSON structure specifying the desired ELN entry attributes.

Note: Files may be inserted into existing ELN entries using the POST Files API call.

Body

application/json
One of
append_to_bodyArray<object | object | object>

Ordered list of content nodes appended to the body of the entry. Each node has a type; the supported types are:

  • text — a paragraph of text. Provide text (defaults to an empty string).
  • link — a hyperlink. Provide url (required; must be a valid http/https/ftp/mailto URL) and an optional label for the display text. Use this to link to a batch, molecule, protocol, or any external resource.
  • file — an attachment that was already uploaded. Provide file, the id of an accessible uploaded file. (Files can also be attached to an existing entry with the POST /files API.)
Show child attributes
One of
textstring

Text content (defaults to an empty string).

typestringrequired
labelstring

Display text for the link (optional).

typestringrequired
urlstringrequired

Target URL (must be a valid http/https/ftp/mailto URL).

fileintegerrequired

Id of an already-uploaded, accessible file.

typestringrequired
eln_fieldsobject

The ELN fields of the entry

projectinteger | string
titlestring

The title of the entry

Parameters

vault_idintegerrequiredpath

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Create an ELN entry
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "title": "Synthesis of compound 42",
      "project": 7,
      "eln_fields": {
        "Reaction type": "Suzuki coupling"
      },
      "append_to_body": [
        {
          "type": "text",
          "text": "Procedure followed the standard protocol."
        },
        {
          "type": "link",
          "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
          "label": "Starting material CDD-12345"
        },
        {
          "type": "file",
          "file": 98765
        }
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "title": "Synthesis of compound 42",
        "project": 7,
        "eln_fields": {
            "Reaction type": "Suzuki coupling"
        },
        "append_to_body": [
            {
                "type": "text",
                "text": "Procedure followed the standard protocol."
            },
            {
                "type": "link",
                "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
                "label": "Starting material CDD-12345"
            },
            {
                "type": "file",
                "file": 98765
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "title": "Synthesis of compound 42",
      "project": 7,
      "eln_fields": {
        "Reaction type": "Suzuki coupling"
      },
      "append_to_body": [
        {
          "type": "text",
          "text": "Procedure followed the standard protocol."
        },
        {
          "type": "link",
          "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
          "label": "Starting material CDD-12345"
        },
        {
          "type": "file",
          "file": 98765
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "title": "Synthesis of compound 42",
  "project": 7,
  "eln_fields": {
    "Reaction type": "Suzuki coupling"
  },
  "append_to_body": [
    {
      "type": "text",
      "text": "Procedure followed the standard protocol."
    },
    {
      "type": "link",
      "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
      "label": "Starting material CDD-12345"
    },
    {
      "type": "file",
      "file": 98765
    }
  ]
}
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 42,
  "status": "new",
  "updated_at": "2024-01-02T03:04:05.000Z"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get all or some ELN entries

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/query

Returns a summary of all available ELN entries for the Vault specified if async=false (default). If async=true, returns a zip file containing the export of all available ELN entries.

For security purposes, the GET and POST ELN Entries CDD Vault API commands documented here are only available for Vault Administrators.

Body

application/json
One of
asyncbooleanfalse

Perform an asynchronous export If true, do an asynchronous export (see Async Export) Use if you wish to retrieve a zip file containing exports of the actual ELN entries along with any files attached within the ELN entries. Note: any page_size parameter used in the call call that also uses the async=true parameter will be ignored. The call will return all matching entries as a zip file with their content.

authorArray<string>

List of ELN author IDs. We do not match by names, you need to use the users call.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

eln_entriesArray<string>

List of ELN entry IDs

finalized_date_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

finalized_date_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

offsetinteger0

Index of the first object actually returned

only_idsbooleanfalse

Return only ELN Entry IDs

only_summarybooleanfalse

Return only a csv summary file, async is still recommended

page_sizeinteger50

Maximum number of objects to return in this call This parameter is ignored is async is true.

projectsArray<string>

List of project IDs

statusstringopensubmittedfinalized

Status of ELN entries (open, submitted, finalized)

submitted_date_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

submitted_date_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get all or some ELN entries
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/query' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "async": false,
      "author": [
        "string"
      ],
      "created_after": "string",
      "created_before": "string",
      "eln_entries": [
        "string"
      ],
      "finalized_date_after": "string",
      "finalized_date_before": "string",
      "modified_after": "string",
      "modified_before": "string",
      "offset": 0,
      "only_ids": false,
      "only_summary": false,
      "page_size": 50,
      "projects": [
        "string"
      ],
      "status": "open",
      "submitted_date_after": "string",
      "submitted_date_before": "string"
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/query',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "async": false,
        "author": [
            "string"
        ],
        "created_after": "string",
        "created_before": "string",
        "eln_entries": [
            "string"
        ],
        "finalized_date_after": "string",
        "finalized_date_before": "string",
        "modified_after": "string",
        "modified_before": "string",
        "offset": 0,
        "only_ids": false,
        "only_summary": false,
        "page_size": 50,
        "projects": [
            "string"
        ],
        "status": "open",
        "submitted_date_after": "string",
        "submitted_date_before": "string"
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/query', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "async": false,
      "author": [
        "string"
      ],
      "created_after": "string",
      "created_before": "string",
      "eln_entries": [
        "string"
      ],
      "finalized_date_after": "string",
      "finalized_date_before": "string",
      "modified_after": "string",
      "modified_before": "string",
      "offset": 0,
      "only_ids": false,
      "only_summary": false,
      "page_size": 50,
      "projects": [
        "string"
      ],
      "status": "open",
      "submitted_date_after": "string",
      "submitted_date_before": "string"
    }),
});

const data = await response.json();
Request Body
{
  "async": false,
  "author": [
    "string"
  ],
  "created_after": "2024-01-15",
  "created_before": "2024-01-15",
  "eln_entries": [
    "string"
  ],
  "finalized_date_after": "2024-01-15",
  "finalized_date_before": "2024-01-15",
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "offset": 0,
  "only_ids": false,
  "only_summary": false,
  "page_size": 50,
  "projects": [
    "string"
  ],
  "status": "open",
  "submitted_date_after": "2024-01-15",
  "submitted_date_before": "2024-01-15"
}
[
  {
    "created_at": "2024-01-02T03:04:05.000Z",
    "id": 42,
    "status": "new",
    "updated_at": "2024-01-02T03:04:05.000Z"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Update an ELN entry

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}

Update an existing ELN entry. Only the attributes supplied in the body are changed. Content supplied in append_to_body (text, links, files) is appended to the existing entry body.

Body

application/json

Attributes used to create or update an ELN entry. The same body is accepted by POST /eln/entries (create) and PUT /eln/entries/{id} (update); on update, only the supplied fields are changed.

append_to_bodyArray<object | object | object>

Ordered list of content nodes appended to the body of the entry. Each node has a type; the supported types are:

  • text — a paragraph of text. Provide text (defaults to an empty string).
  • link — a hyperlink. Provide url (required; must be a valid http/https/ftp/mailto URL) and an optional label for the display text. Use this to link to a batch, molecule, protocol, or any external resource.
  • file — an attachment that was already uploaded. Provide file, the id of an accessible uploaded file. (Files can also be attached to an existing entry with the POST /files API.)
Show child attributes
One of
textstring

Text content (defaults to an empty string).

typestringrequired
labelstring

Display text for the link (optional).

typestringrequired
urlstringrequired

Target URL (must be a valid http/https/ftp/mailto URL).

fileintegerrequired

Id of an already-uploaded, accessible file.

typestringrequired
eln_fieldsobject

The ELN fields of the entry

projectinteger | string
titlestring

The title of the entry

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the ELN entry

Response

200OKobject

Success

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

ELN entry not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Update an ELN entry
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "title": "Synthesis of compound 42",
      "project": 7,
      "eln_fields": {
        "Reaction type": "Suzuki coupling"
      },
      "append_to_body": [
        {
          "type": "text",
          "text": "Procedure followed the standard protocol."
        },
        {
          "type": "link",
          "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
          "label": "Starting material CDD-12345"
        },
        {
          "type": "file",
          "file": 98765
        }
      ]
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "title": "Synthesis of compound 42",
        "project": 7,
        "eln_fields": {
            "Reaction type": "Suzuki coupling"
        },
        "append_to_body": [
            {
                "type": "text",
                "text": "Procedure followed the standard protocol."
            },
            {
                "type": "link",
                "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
                "label": "Starting material CDD-12345"
            },
            {
                "type": "file",
                "file": 98765
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "title": "Synthesis of compound 42",
      "project": 7,
      "eln_fields": {
        "Reaction type": "Suzuki coupling"
      },
      "append_to_body": [
        {
          "type": "text",
          "text": "Procedure followed the standard protocol."
        },
        {
          "type": "link",
          "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
          "label": "Starting material CDD-12345"
        },
        {
          "type": "file",
          "file": 98765
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "title": "Synthesis of compound 42",
  "project": 7,
  "eln_fields": {
    "Reaction type": "Suzuki coupling"
  },
  "append_to_body": [
    {
      "type": "text",
      "text": "Procedure followed the standard protocol."
    },
    {
      "type": "link",
      "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
      "label": "Starting material CDD-12345"
    },
    {
      "type": "file",
      "file": 98765
    }
  ]
}
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 42,
  "status": "new",
  "updated_at": "2024-01-02T03:04:05.000Z"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Perform an ELN entry status action

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}/status

Perform a witnessing/status action on an ELN entry (submit, approve, reject, cancel, reopen, finalize, or discard). Requires vault administrator access and write permission. The valid actions depend on whether ELN witnessing is enabled for the vault.

Body

application/json

A witnessing/status action to perform on an ELN entry. The set of valid status_action values depends on whether ELN witnessing is enabled for the vault:

  • Witnessing enabled: submit (requires witness), approve, reject (requires reason), cancel, reopen (requires reason), discard.
  • Witnessing disabled: finalize, reopen (requires reason), discard.
reasonstring

Reason for the action (required for reject and reopen).

status_actionstringsubmitapproverejectcancelreopenfinalizediscardrequired

The action to perform.

witnessinteger

Id of the witnessing user (required for submit).

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the ELN entry

Response

200OKobject

The updated ELN entry

400Bad Requestobject

Invalid or missing status_action

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

ELN entry (or witness) not found, or vault is unauthorized

409Conflictobject

The entry cannot transition from its current status

Authorization

ApiKeyAuthapiKey in header
Perform an ELN entry status action
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}/status' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "status_action": "submit",
      "witness": 6021
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}/status',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "status_action": "submit",
        "witness": 6021
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/eln/entries/{id}/status', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "status_action": "submit",
      "witness": 6021
    }),
});

const data = await response.json();
Request Body
{
  "status_action": "submit",
  "witness": 6021
}
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 42,
  "status": "new",
  "updated_at": "2024-01-02T03:04:05.000Z"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Exports

Asynchronous data exports

Get progress of an export

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/export_progress/{export_id}

Check on the status of your export task. Repeat this call every 5-10 seconds (suggested interval) until the status is “finished”

Parameters

vault_idintegerrequiredpath
export_idintegerrequiredpath

Response

200OKobject

Successful operation

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Couldn't find this export

Authorization

ApiKeyAuthapiKey in header
Get progress of an export
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/export_progress/{export_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/export_progress/{export_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/export_progress/{export_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "queued_job_position": 0,
  "status": "new"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "error": "Couldn't find export with 'id'={export_id}"
}

Check All Current Exports

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports

Check how many async API export tasks are currently running and see the current status of the user's queue. The endpoint does not accept any normal API parameters and lists all of a user's exports, including any exports initiated via the GUI/front-end. Note: This GET Exports API call will return ALL exports across all Vaults applicable to the API Token specified, regardless of the Vault ID used in the API url.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of all active exports

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Check All Current Exports
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "created_at": "2024-01-02T03:04:05.000Z",
    "id": 1,
    "modified_at": "2024-01-02T03:04:05.000Z",
    "queued_job_position": 0,
    "status": "new"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get the output of an export

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}

Retrieve the output of an export once it is ready. An export is created whenever a query endpoint is called with async=true (for example POST /molecules/query, POST /batches/query, or an ELN entries query), as well as when running a saved search. This single endpoint returns the finished output for any of them. If the export is not finished it returns 403 together with the export's async progress details; poll GET /export_progress/{export_id} until it is ready. The output format (JSON, CSV, SDF, etc.) depends on the format requested when the export was created.

Depending on server configuration the file may be served directly (200) or via a 302 redirect to a temporary download URL (e.g. S3). Configure your client to follow redirects — with curl, pass -L.

Parameters

vault_idintegerrequiredpath
export_idintegerrequiredpath

Response

200OK

Successful operation; the response body is the export file. The format depends on what was requested when the export was created (JSON, CSV, SDF, etc.).

302Found

Redirect to a temporary download URL for the file (used when files are served directly from S3). Follow the Location header (curl: -L).

401Unauthorizedobject

Missing or invalid API key

403Forbiddenobject

The export is not ready yet

404Not Foundobject

Couldn't find this export

Authorization

ApiKeyAuthapiKey in header
Get the output of an export
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "queued_job_position": 0,
  "status": "new"
}
{
  "error": "Couldn't find export with 'id'={export_id}"
}

Cancel Export

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}

Cancels an export if possible

Parameters

vault_idintegerrequiredpath
export_idintegerrequiredpath

Response

200OKobject

The export was canceled (its status becomes canceled).

401Unauthorizedobject

Missing or invalid API key

405Method Not Allowedobject

The export was not in a cancelable state (for example it has already finished or was already canceled). The export's current state is returned unchanged.

Authorization

ApiKeyAuthapiKey in header
Cancel Export
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/exports/{export_id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "queued_job_position": 0,
  "status": "new"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "queued_job_position": 0,
  "status": "new"
}

Fields

Vault field definitions

Retrieve all fields

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields

Get all the fields both internal and user defined

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of all fields

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Retrieve all fields
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "batch": [
      {
        "data_type_name": "string",
        "id": 0,
        "name": "string",
        "overwritable": true,
        "required_group_number": 0,
        "type": "string",
        "unique_value": true
      }
    ],
    "internal": [
      {
        "data_type_name": "string",
        "id": 0,
        "name": "string",
        "overwritable": true,
        "required_group_number": 0,
        "type": "string",
        "unique_value": true
      }
    ],
    "molecule": [
      {
        "data_type_name": "string",
        "id": 0,
        "name": "string",
        "overwritable": true,
        "required_group_number": 0,
        "type": "string",
        "unique_value": true
      }
    ],
    "protocol": [
      {
        "data_type_name": "string",
        "id": 0,
        "name": "string",
        "overwritable": true,
        "required_group_number": 0,
        "type": "string",
        "unique_value": true
      }
    ]
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get pick list values

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values

List the pick list values for a vault field definition.

Parameters

vault_idintegerrequiredpath
field_idintegerrequiredpath

Numeric identifier of the field definition

page_sizeintegerquery

Maximum number of records to return (default 50, maximum 1000).

offsetintegerquery

Number of records to skip (for pagination).

Response

200OKobject

A page of pick list values

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get pick list values
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "count": 0,
  "objects": [
    {
      "created_at": "2024-01-15T09:30:00Z",
      "hidden": true,
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "value": "string"
    }
  ],
  "offset": 0,
  "page_size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Create a pick list value

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values

Create a pick list value on a field definition. Requires vault administrator access.

Body

application/json

Attributes for creating or updating a pick list value.

hiddenbooleanfalse

Whether the value is hidden from users.

valuestringrequired

Parameters

vault_idintegerrequiredpath
field_idintegerrequiredpath

Numeric identifier of the field definition

Response

201Createdobject

The created pick list value

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Create a pick list value
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "value": "blue",
      "hidden": false
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "value": "blue",
        "hidden": false
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "value": "blue",
      "hidden": false
    }),
});

const data = await response.json();
Request Body
{
  "value": "blue",
  "hidden": false
}
{
  "created_at": "2024-01-15T09:30:00Z",
  "hidden": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "value": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a pick list value

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}

Retrieve a single pick list value.

Parameters

vault_idintegerrequiredpath
field_idintegerrequiredpath

Numeric identifier of the field definition

idintegerrequiredpath

Numeric identifier of the pick list value

Response

200OKobject

The pick list value

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Pick list value not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a pick list value
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "created_at": "2024-01-15T09:30:00Z",
  "hidden": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "value": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a pick list value

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}

Update a pick list value. Requires vault administrator access.

Body

application/json

Attributes for creating or updating a pick list value.

hiddenbooleanfalse

Whether the value is hidden from users.

valuestringrequired

Parameters

vault_idintegerrequiredpath
field_idintegerrequiredpath

Numeric identifier of the field definition

idintegerrequiredpath

Numeric identifier of the pick list value

Response

200OKobject

The updated pick list value

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Pick list value not found, or vault is unauthorized

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Update a pick list value
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "value": "blue",
      "hidden": false
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "value": "blue",
        "hidden": false
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "value": "blue",
      "hidden": false
    }),
});

const data = await response.json();
Request Body
{
  "value": "blue",
  "hidden": false
}
{
  "created_at": "2024-01-15T09:30:00Z",
  "hidden": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "value": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Delete a pick list value

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}

Delete a pick list value. Requires vault administrator access.

Parameters

vault_idintegerrequiredpath
field_idintegerrequiredpath

Numeric identifier of the field definition

idintegerrequiredpath

Numeric identifier of the pick list value

Response

200OKobject

The pick list value was deleted

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Pick list value not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Delete a pick list value
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "message": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Files

File attachments

Attach a file to an object

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files

Attach a file to a record in the vault. The request must be sent as multipart/form-data (the file itself is the file part; the resource_class and resource_id fields identify the record to attach it to).

Files can only be attached to the four resource classes listed under resource_class: run, molecule, protocol, and eln_entry. Readout rows are not directly attachable — there is no readout_row resource class. To associate a file with protocol readout data, attach it to the parent run (resource_class: run, resource_id: the run's id) or to the protocol.

Body

multipart/form-data
filestring<binary>

Path to the file to be uploaded

resource_classstringrunmoleculeprotocoleln_entry

Class of the resource to which the file is attached

resource_idstring

Unique identifier of the resource to which the file is attached

Parameters

vault_idintegerrequiredpath

Response

200OKobject

File successfully attached

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Attach a file to an object
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -F 'file=@/path/to/file' \
  -F 'resource_class=run' \
  -F 'resource_id=string'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    files={'file': open('/path/to/file', 'rb')},
    data={'resource_class': 'run', 'resource_id': 'string'},
)
data = response.json()
// `fileInput` is a file <input> element, e.g. document.querySelector('input[type=file]')
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('resource_class', 'run');
formData.append('resource_id', 'string');

const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
  body: formData,
});

const data = await response.json();
Request Body
{
  "file": "<binary>",
  "resource_class": "run",
  "resource_id": "string"
}
{
  "id": "string",
  "name": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Retrieve a file

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}

Return a single file with the content base64 encoded.

Parameters

vault_idintegerrequiredpath
file_idintegerrequiredpath

Response

200OK

Successful operation, output will depend on format selected when doing the query

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Couldn't find this file

Authorization

ApiKeyAuthapiKey in header
Retrieve a file
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "error": "Couldn't find file with 'id'={file_id}"
}

Delete file

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}

Delete a file

Parameters

vault_idintegerrequiredpath
file_idintegerrequiredpath

Response

200OKobject

The file

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Delete file
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/files/{file_id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "character_set": "US-ASCII",
  "class": "uploaded file",
  "contents": "VGhpcyBpcyBhIGZpbGUK",
  "id": 1069448031,
  "mime_type": {
    "hash": -1147906696977776400,
    "string": "text/plain",
    "symbol": "text",
    "synonyms": [
      "string"
    ]
  },
  "name": "tmp.txt"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Import Parsers

Import parsers for structured data files

Get import parsers

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers

List the import parsers (structured-file parsing templates) defined in the vault. The listing returns summary fields only; use the show endpoint to retrieve a parser's full template_json configuration.

Parameters

vault_idintegerrequiredpath

Response

200OKobject

List of import parsers

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get import parsers
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "count": 0,
  "objects": [
    {
      "created_at": "2024-01-15T09:30:00Z",
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "name": "string",
      "owner": "string",
      "template_json": {}
    }
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get an import parser

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers/{id}

Retrieve a single import parser, including its full template_json configuration.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the import parser

Response

200OKobject

The import parser

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Import parser not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get an import parser
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/import_parsers/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "owner": "string",
  "template_json": {}
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Inventory

Sample inventory locations

Retrieve a list of Sample Inventory Locations for a given Vault

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_locations

Returns a list of inventory locations within the specified vault.

Parameters

vault_idintegerrequiredpath
X-CDD-Tokenstringrequiredheader

Authentication token

Response

200OKArray<object>

A list of inventory locations

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Retrieve a list of Sample Inventory Locations for a given Vault
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_locations' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_locations',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_locations', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "class": "inventory location",
    "created_at": "2023-10-30T18:25:41.771Z",
    "filled_position_count": 0,
    "id": 42,
    "modified_at": "2023-10-30T18:25:41.771Z",
    "num_columns": 0,
    "num_rows": 0,
    "parent_id": 130,
    "position_limit": 0,
    "value": "Gotham"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Inventory Samples

Inventory samples and their events

Get inventory samples

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples

List inventory samples in the vault. Supports pagination (page_size, offset), asynchronous retrieval (async=true), and filtering by batch, project, and creation/modification dates. Requires inventory fields to be enabled for the vault.

Parameters

vault_idintegerrequiredpath
page_sizeintegerquery

Maximum number of records to return (default 50, maximum 1000).

offsetintegerquery

Number of records to skip (for pagination).

asyncbooleanquery

If true, run the listing as an asynchronous export.

batch_idsstringquery

Comma-separated batch ids to filter by.

inventory_sample_idsstringquery

Comma-separated inventory sample ids to filter by.

projectsstringquery

Comma-separated project ids to filter by.

created_afterstring<date-time>query

Only include samples created on or after this time.

created_beforestring<date-time>query

Only include samples created on or before this time.

modified_afterstring<date-time>query

Only include samples modified on or after this time.

modified_beforestring<date-time>query

Only include samples modified on or before this time.

Response

200OKobject

A page of inventory samples

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get inventory samples
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "count": 0,
  "objects": [
    {
      "batch": 0,
      "batch_name": "string",
      "class": "inventory sample",
      "created_at": "2024-01-15T09:30:00Z",
      "created_by_user_full_name": "string",
      "current_amount": 0,
      "depleted": true,
      "fields": {},
      "id": 0,
      "inventory_events": [
        {
          "class": "inventory event",
          "created_at": "2024-01-15T09:30:00Z",
          "fields": {},
          "id": 0,
          "modified_at": "2024-01-15T09:30:00Z",
          "updated_by_user_full_name": "string"
        }
      ],
      "location": "string",
      "modified_at": "2024-01-15T09:30:00Z",
      "name": "string",
      "units": "string",
      "updated_by_user_full_name": "string"
    }
  ],
  "offset": 0,
  "page_size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Create an inventory sample

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples

Create an inventory sample for a batch.

Body

application/json

Attributes for creating an inventory sample.

batch_idintegerrequired

Id of the batch this sample is an inventory of.

fieldsobject

Custom inventory sample field values, keyed by field name.

inventory_eventsArray<object>

Initial inventory event(s) for the sample. At most one event may be supplied per request.

Show child attributes
fieldsobject

Custom event field values, keyed by field name.

unitsstringgkgmgµgngmLLµLMmMµMnMmolmmolµmolnmolpmolcountrequired

Units the sample amount is expressed in. One of: g, kg, mg, µg, ng, mL, L, µL, M, mM, µM, nM, mol, mmol, µmol, nmol, pmol, count.

Parameters

vault_idintegerrequiredpath

Response

200OKobject

The created inventory sample

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Create an inventory sample
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "batch_id": 456,
      "units": "mg",
      "fields": {
        "Supplier": "Acme Chemicals"
      },
      "inventory_events": [
        {
          "fields": {
            "Credit": 100
          }
        }
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "batch_id": 456,
        "units": "mg",
        "fields": {
            "Supplier": "Acme Chemicals"
        },
        "inventory_events": [
            {
                "fields": {
                    "Credit": 100
                }
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "batch_id": 456,
      "units": "mg",
      "fields": {
        "Supplier": "Acme Chemicals"
      },
      "inventory_events": [
        {
          "fields": {
            "Credit": 100
          }
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "batch_id": 456,
  "units": "mg",
  "fields": {
    "Supplier": "Acme Chemicals"
  },
  "inventory_events": [
    {
      "fields": {
        "Credit": 100
      }
    }
  ]
}
{
  "batch": 0,
  "batch_name": "string",
  "class": "inventory sample",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by_user_full_name": "string",
  "current_amount": 0,
  "depleted": true,
  "fields": {},
  "id": 0,
  "inventory_events": [
    {
      "class": "inventory event",
      "created_at": "2024-01-15T09:30:00Z",
      "fields": {},
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "updated_by_user_full_name": "string"
    }
  ],
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "units": "string",
  "updated_by_user_full_name": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get an inventory sample

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}

Retrieve a single inventory sample.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the inventory sample

Response

200OKobject

The inventory sample

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Inventory sample not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get an inventory sample
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "batch": 0,
  "batch_name": "string",
  "class": "inventory sample",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by_user_full_name": "string",
  "current_amount": 0,
  "depleted": true,
  "fields": {},
  "id": 0,
  "inventory_events": [
    {
      "class": "inventory event",
      "created_at": "2024-01-15T09:30:00Z",
      "fields": {},
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "updated_by_user_full_name": "string"
    }
  ],
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "units": "string",
  "updated_by_user_full_name": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update an inventory sample

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}

Update an inventory sample. Only the supplied fields are changed. At most one inventory event may be added or updated per request.

Body

application/json

Attributes for updating an inventory sample. Only supplied fields are changed.

depletedboolean

Mark the sample as depleted (true) or clear the depleted flag (false).

fieldsobject

Custom inventory sample field values, keyed by field name.

inventory_eventsArray<object>

An inventory event to add or update. At most one event may be supplied per request. Include the event id to update an existing event; omit it to create a new one.

Show child attributes
fieldsobject

Custom event field values, keyed by field name.

idinteger

Id of the event to update. Omit to create a new event.

unitsstringgkgmgµgngmLLµLMmMµMnMmolmmolµmolnmolpmolcount

Units the sample amount is expressed in.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the inventory sample

Response

200OKobject

The updated inventory sample

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Update an inventory sample
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "depleted": false,
      "fields": {
        "Supplier": "New Supplier Inc"
      },
      "inventory_events": [
        {
          "id": 54321,
          "fields": {
            "Debit": 10
          }
        }
      ]
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "depleted": false,
        "fields": {
            "Supplier": "New Supplier Inc"
        },
        "inventory_events": [
            {
                "id": 54321,
                "fields": {
                    "Debit": 10
                }
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "depleted": false,
      "fields": {
        "Supplier": "New Supplier Inc"
      },
      "inventory_events": [
        {
          "id": 54321,
          "fields": {
            "Debit": 10
          }
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "depleted": false,
  "fields": {
    "Supplier": "New Supplier Inc"
  },
  "inventory_events": [
    {
      "id": 54321,
      "fields": {
        "Debit": 10
      }
    }
  ]
}
{
  "batch": 0,
  "batch_name": "string",
  "class": "inventory sample",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by_user_full_name": "string",
  "current_amount": 0,
  "depleted": true,
  "fields": {},
  "id": 0,
  "inventory_events": [
    {
      "class": "inventory event",
      "created_at": "2024-01-15T09:30:00Z",
      "fields": {},
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "updated_by_user_full_name": "string"
    }
  ],
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "units": "string",
  "updated_by_user_full_name": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Delete an inventory sample

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}

Delete an inventory sample. Samples that are associated with a protocol (readout rows) or a plate well cannot be deleted.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the inventory sample

Response

200OKobject

The inventory sample was deleted

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

The sample cannot be deleted (associated with a protocol or plate well)

Authorization

ApiKeyAuthapiKey in header
Delete an inventory sample
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/inventory_samples/{id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "message": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Mapping Templates

Import mapping templates

Retrieve all the mapping templates

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates

This will give you a summary of all the mapping templates.

If you need details, you need to use the GET /vaults/{vault_id}/mapping_templates/{mapping_template_id} endpoint.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of all fields

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Retrieve all the mapping templates
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "created_at": "2021-12-23T23:59:22.000Z",
    "id": 22704,
    "modified_at": "2021-12-23T23:59:22.000Z",
    "name": "Protac Registration",
    "owner": "Charlie Weatherall"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Retrieve a single mapping template

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates/{mapping_template_id}

This will give you the details about this mapping template

Parameters

vault_idintegerrequiredpath
mapping_template_idintegerrequiredpath

Response

200OKobject

List of all fields

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Retrieve a single mapping template
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates/{mapping_template_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates/{mapping_template_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/mapping_templates/{mapping_template_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "created_at": "2021-12-23T23:59:22.000Z",
  "file": {
    "file_name": "string",
    "value": 0
  },
  "header_mappings": [
    {
      "definition": {
        "data_type_name": "string",
        "id": 0,
        "name": "string",
        "pick_list_values": [
          "string"
        ],
        "protocol_name": "string",
        "type": "string"
      },
      "header": {
        "id": 0,
        "name": "string"
      },
      "run_grouping": 0
    }
  ],
  "id": 22704,
  "modified_at": "2021-12-23T23:59:22.000Z",
  "name": "Protac Registration",
  "owner": "Charlie Weatherall"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Molecules

Molecules handling

Create a molecule

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules

Create a molecule. This is only permitted in vaults that are NOT using a registration system; in registration vaults, register molecules by creating batches instead. To read or search molecules, use POST /molecules/query.

Body

application/json

Attributes for creating a molecule. Creating molecules directly is only allowed in vaults that are NOT using a registration system; in registration vaults, register molecules by creating batches instead.

collectionsArray<integer | string>

Collections to add the molecule to (ids or names).

Show child attributes
One of
integer
string
duplicate_resolutionstringnewprompt

How to handle a structure that duplicates an existing molecule. new registers a new molecule; prompt fails with the duplicate details so the caller can decide. Must match tautomer_resolution if both are given.

molecule_fieldsobject

Custom molecule field values, keyed by field name. The legacy alias udfs is also accepted.

namestringrequired

Name of the molecule.

projectsArray<integer | string>

Projects the molecule belongs to (ids or names).

Show child attributes
One of
integer
string
registration_forminteger | string

The registration form to use (id or name). Defaults to the vault default.

registration_typestring

The kind of entity being registered (e.g. CHEMICAL_STRUCTURE).

structurestring

The chemical structure, as SMILES or a molfile. For amino-acid, nucleotide, or mixture molecules use the corresponding structure representation accepted for that registration type.

synonymsArray<string>

Alternative names for the molecule.

tautomer_resolutionstringnewprompt

How to handle a structure that is a tautomer of an existing molecule.

Parameters

vault_idintegerrequiredpath

Response

200OKobject

The created molecule

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Validation error, or molecule creation is not allowed in this vault

Authorization

ApiKeyAuthapiKey in header
Create a molecule
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "My compound",
      "structure": "CC(=O)Oc1ccccc1C(=O)O",
      "synonyms": [
        "Aspirin"
      ],
      "projects": [
        12
      ],
      "molecule_fields": {
        "Solubility": "High"
      }
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "name": "My compound",
        "structure": "CC(=O)Oc1ccccc1C(=O)O",
        "synonyms": [
            "Aspirin"
        ],
        "projects": [
            12
        ],
        "molecule_fields": {
            "Solubility": "High"
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "My compound",
      "structure": "CC(=O)Oc1ccccc1C(=O)O",
      "synonyms": [
        "Aspirin"
      ],
      "projects": [
        12
      ],
      "molecule_fields": {
        "Solubility": "High"
      }
    }),
});

const data = await response.json();
Request Body
{
  "name": "My compound",
  "structure": "CC(=O)Oc1ccccc1C(=O)O",
  "synonyms": [
    "Aspirin"
  ],
  "projects": [
    12
  ],
  "molecule_fields": {
    "Solubility": "High"
  }
}
{
  "batches": [
    {
      "batch_fields": {},
      "class": "batch",
      "created_at": "2024-01-15T09:30:00Z",
      "formula_weight": 0,
      "id": 42,
      "modified_at": "2024-01-15T09:30:00Z",
      "molecule_batch_identifier": "DEMO-1000211-001",
      "name": "Batch 1",
      "owner": "Charlie Weatherall",
      "projects": [
        {
          "id": 1,
          "name": "Project 1"
        }
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }
  ],
  "class": "molecule",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 1000211,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule_fields": {},
  "name": "Aspirin",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "registration_type": "chemical_structure",
  "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
  "synonyms": [
    "string"
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get multiple molecules

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/query

Get the information from multiple molecules. We still support the now deprecated GET queries on the endpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.

Body

application/json
One of
asyncboolean

If true, do an asynchronous export. Use for large data sets.

batch_created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_field_after_datestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_field_after_namestring

Name of the batch date field to filter on (used with batch_field_after_date).

batch_field_before_datestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_field_before_namestring

Name of the batch date field to filter on (used with batch_field_before_date).

batch_fieldsArray<string>

Array of Batch field names to include in the resulting JSON. Defaults to all available fields.

collection_criteriaArray<object>

Array of collection criteria objects. Filters results based on collection membership with support for AND/OR/XOR junctions and exclusion (NOT IN) logic.

Show child attributes
collection_idintegerrequired

The ID of the collection to filter by.

junctionstringANDORXORAND

How to combine this criterion with the previous one. The first criterion's junction is ignored. Defaults to "AND".

not_inbooleanfalse

If true, excludes molecules that belong to this collection instead of including them. Defaults to false.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

data_setsArray<integer>

Array of public dataset ids. Defaults to all data sets.

fields_searchArray<object | object | object>

Array of Molecule field names & values. Used to filter Molecules returned based on query values

Show child attributes
One of
namestring

Name of the field to search

text_valuestring

Text value to search for

namestring

Name of the field to search

number_valuenumber

Number value to search for

date_valuestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

namestring

Name of the field to search

include_original_structuresbooleanfalse

If true, include the original structure in the response. This is independent of no_structures.

inchikeystring

Filter molecules by InChIKey.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_fieldsArray<string>

Array of Molecule field names to include in the resulting JSON. Defaults to all available fields.

namesArray<string>

Array of molecule names or synonyms to search for.

no_structuresbooleanfalse

If true, omit structure representations for a smaller and faster response.

offsetinteger
only_batch_idsbooleanfalse

If true, the full Molecule details are still returned but the Batch-level information is left out of the JSON results. (Only the IDs of the Batches are still included.)

only_idsbooleanfalse

If true, only return the ids of the molecules.

page_sizeinteger50

Requested page size (maximum value 1000).

projectsArray<integer>

Array of project ids. Defaults to all available projects.

protocol_criteriaArray<object>

Array of protocol-based filters restricting results to molecules with (or without) matching protocol readout data. Criteria are combined using each entry's junction.

Show child attributes
protocol_idinteger

Id of the protocol to filter on (provide this or data_set_id).

data_set_idinteger

Id of the data set to filter on (provide this or protocol_id).

run_criterionstringanyrecentrun_daterun_id

Which runs to consider.

run_idinteger

Run id to match (when run_criterion is run_id).

run_afterstring<date>

Include runs on/after this date (when run_criterion is run_date).

run_beforestring<date>

Include runs on/before this date (when run_criterion is run_date).

since_days_agointeger

Number of days back to include (when run_criterion is recent).

readout_definition_idinteger

Id of the readout definition to filter on.

operatorstring=!=<>≤≥containsdoes not containfrom

Comparison operator applied to readout_value.

readout_valuestring

Value to compare the readout against.

readout_value_maximumstring

Upper bound of a range (when operator is from).

calculation_error_typestring

Filter by calculation error type.

criterion_typestringdata set or protocolrun dateprotocol field

The kind of protocol criterion.

fieldstring

Protocol field name (when criterion_type is protocol field).

querystring

Protocol field search value (when criterion_type is protocol field).

protocol_condition_idsArray<integer>

Restrict to these protocol condition ids.

negatedbooleanfalse

If true, exclude rather than include matches.

junctionstringANDORAND

How to combine this criterion with the previous one (ignored for the first criterion).

structurestring

A SMILES or MOL string to search for.

structure_criterionobject

A structure-property filter object. Each property is filtered by an optional _minimum and/or _maximum bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same <property>_minimum / <property>_maximum convention.

Show child attributes
heavy_atom_count_minimuminteger
heavy_atom_count_maximuminteger
cd_molweight_minimumnumber
cd_molweight_maximumnumber
exact_mass_minimumnumber
exact_mass_maximumnumber
log_p_minimumnumber
log_p_maximumnumber
log_d_minimumnumber
log_d_maximumnumber
log_s_minimumnumber
log_s_maximumnumber
num_aromatic_rings_minimuminteger
num_aromatic_rings_maximuminteger
num_h_bond_acceptors_minimuminteger
num_h_bond_acceptors_maximuminteger
num_h_bond_donors_minimuminteger
num_h_bond_donors_maximuminteger
num_rotatable_bonds_minimuminteger
num_rotatable_bonds_maximuminteger
num_rule_of_5_violations_minimuminteger
num_rule_of_5_violations_maximuminteger
topological_polar_surface_area_minimumnumber
topological_polar_surface_area_maximumnumber
structure_search_typestringexactsubstructuresimilarityexact_with_stereo

The type of structure search to perform. Options are 'exact', 'substructure', 'similarity', or 'exact_with_stereo'.

structure_similarity_thresholdnumber[0, 1]

Similarity threshold for similarity searches (0 to 1). Only used when structure_search_type is 'similarity'.

moleculesArray<integer>

Comma separated list of molecule ids. Cannot be used with other parameters

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

Success

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get multiple molecules
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/query' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "async": true,
      "batch_created_after": "string",
      "batch_created_before": "string",
      "batch_field_after_date": "string",
      "batch_field_after_name": "string",
      "batch_field_before_date": "string",
      "batch_field_before_name": "string",
      "batch_fields": [
        "string"
      ],
      "collection_criteria": [
        {
          "collection_id": 0,
          "junction": "AND",
          "not_in": false
        }
      ],
      "created_after": "string",
      "created_before": "string",
      "data_sets": [
        0
      ],
      "fields_search": [
        {
          "name": "string",
          "text_value": "string"
        }
      ],
      "include_original_structures": false,
      "inchikey": "string",
      "modified_after": "string",
      "modified_before": "string",
      "molecule_fields": [
        "string"
      ],
      "names": [
        "string"
      ],
      "no_structures": false,
      "offset": 0,
      "only_batch_ids": false,
      "only_ids": false,
      "page_size": 50,
      "projects": [
        0
      ],
      "protocol_criteria": [
        {
          "protocol_id": 0,
          "data_set_id": 0,
          "run_criterion": "any",
          "run_id": 0,
          "run_after": "string",
          "run_before": "string",
          "since_days_ago": 0,
          "readout_definition_id": 0,
          "operator": "=",
          "readout_value": "string",
          "readout_value_maximum": "string",
          "calculation_error_type": "string",
          "criterion_type": "data set or protocol",
          "field": "string",
          "query": "string",
          "protocol_condition_ids": [
            0
          ],
          "negated": false,
          "junction": "AND"
        }
      ],
      "structure": "string",
      "structure_criterion": {
        "heavy_atom_count_minimum": 0,
        "heavy_atom_count_maximum": 0,
        "cd_molweight_minimum": 0,
        "cd_molweight_maximum": 0,
        "exact_mass_minimum": 0,
        "exact_mass_maximum": 0,
        "log_p_minimum": 0,
        "log_p_maximum": 0,
        "log_d_minimum": 0,
        "log_d_maximum": 0,
        "log_s_minimum": 0,
        "log_s_maximum": 0,
        "num_aromatic_rings_minimum": 0,
        "num_aromatic_rings_maximum": 0,
        "num_h_bond_acceptors_minimum": 0,
        "num_h_bond_acceptors_maximum": 0,
        "num_h_bond_donors_minimum": 0,
        "num_h_bond_donors_maximum": 0,
        "num_rotatable_bonds_minimum": 0,
        "num_rotatable_bonds_maximum": 0,
        "num_rule_of_5_violations_minimum": 0,
        "num_rule_of_5_violations_maximum": 0,
        "topological_polar_surface_area_minimum": 0,
        "topological_polar_surface_area_maximum": 0
      },
      "structure_search_type": "exact",
      "structure_similarity_threshold": 0
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/query',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "async": true,
        "batch_created_after": "string",
        "batch_created_before": "string",
        "batch_field_after_date": "string",
        "batch_field_after_name": "string",
        "batch_field_before_date": "string",
        "batch_field_before_name": "string",
        "batch_fields": [
            "string"
        ],
        "collection_criteria": [
            {
                "collection_id": 0,
                "junction": "AND",
                "not_in": false
            }
        ],
        "created_after": "string",
        "created_before": "string",
        "data_sets": [
            0
        ],
        "fields_search": [
            {
                "name": "string",
                "text_value": "string"
            }
        ],
        "include_original_structures": false,
        "inchikey": "string",
        "modified_after": "string",
        "modified_before": "string",
        "molecule_fields": [
            "string"
        ],
        "names": [
            "string"
        ],
        "no_structures": false,
        "offset": 0,
        "only_batch_ids": false,
        "only_ids": false,
        "page_size": 50,
        "projects": [
            0
        ],
        "protocol_criteria": [
            {
                "protocol_id": 0,
                "data_set_id": 0,
                "run_criterion": "any",
                "run_id": 0,
                "run_after": "string",
                "run_before": "string",
                "since_days_ago": 0,
                "readout_definition_id": 0,
                "operator": "=",
                "readout_value": "string",
                "readout_value_maximum": "string",
                "calculation_error_type": "string",
                "criterion_type": "data set or protocol",
                "field": "string",
                "query": "string",
                "protocol_condition_ids": [
                    0
                ],
                "negated": false,
                "junction": "AND"
            }
        ],
        "structure": "string",
        "structure_criterion": {
            "heavy_atom_count_minimum": 0,
            "heavy_atom_count_maximum": 0,
            "cd_molweight_minimum": 0,
            "cd_molweight_maximum": 0,
            "exact_mass_minimum": 0,
            "exact_mass_maximum": 0,
            "log_p_minimum": 0,
            "log_p_maximum": 0,
            "log_d_minimum": 0,
            "log_d_maximum": 0,
            "log_s_minimum": 0,
            "log_s_maximum": 0,
            "num_aromatic_rings_minimum": 0,
            "num_aromatic_rings_maximum": 0,
            "num_h_bond_acceptors_minimum": 0,
            "num_h_bond_acceptors_maximum": 0,
            "num_h_bond_donors_minimum": 0,
            "num_h_bond_donors_maximum": 0,
            "num_rotatable_bonds_minimum": 0,
            "num_rotatable_bonds_maximum": 0,
            "num_rule_of_5_violations_minimum": 0,
            "num_rule_of_5_violations_maximum": 0,
            "topological_polar_surface_area_minimum": 0,
            "topological_polar_surface_area_maximum": 0
        },
        "structure_search_type": "exact",
        "structure_similarity_threshold": 0
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/query', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "async": true,
      "batch_created_after": "string",
      "batch_created_before": "string",
      "batch_field_after_date": "string",
      "batch_field_after_name": "string",
      "batch_field_before_date": "string",
      "batch_field_before_name": "string",
      "batch_fields": [
        "string"
      ],
      "collection_criteria": [
        {
          "collection_id": 0,
          "junction": "AND",
          "not_in": false
        }
      ],
      "created_after": "string",
      "created_before": "string",
      "data_sets": [
        0
      ],
      "fields_search": [
        {
          "name": "string",
          "text_value": "string"
        }
      ],
      "include_original_structures": false,
      "inchikey": "string",
      "modified_after": "string",
      "modified_before": "string",
      "molecule_fields": [
        "string"
      ],
      "names": [
        "string"
      ],
      "no_structures": false,
      "offset": 0,
      "only_batch_ids": false,
      "only_ids": false,
      "page_size": 50,
      "projects": [
        0
      ],
      "protocol_criteria": [
        {
          "protocol_id": 0,
          "data_set_id": 0,
          "run_criterion": "any",
          "run_id": 0,
          "run_after": "string",
          "run_before": "string",
          "since_days_ago": 0,
          "readout_definition_id": 0,
          "operator": "=",
          "readout_value": "string",
          "readout_value_maximum": "string",
          "calculation_error_type": "string",
          "criterion_type": "data set or protocol",
          "field": "string",
          "query": "string",
          "protocol_condition_ids": [
            0
          ],
          "negated": false,
          "junction": "AND"
        }
      ],
      "structure": "string",
      "structure_criterion": {
        "heavy_atom_count_minimum": 0,
        "heavy_atom_count_maximum": 0,
        "cd_molweight_minimum": 0,
        "cd_molweight_maximum": 0,
        "exact_mass_minimum": 0,
        "exact_mass_maximum": 0,
        "log_p_minimum": 0,
        "log_p_maximum": 0,
        "log_d_minimum": 0,
        "log_d_maximum": 0,
        "log_s_minimum": 0,
        "log_s_maximum": 0,
        "num_aromatic_rings_minimum": 0,
        "num_aromatic_rings_maximum": 0,
        "num_h_bond_acceptors_minimum": 0,
        "num_h_bond_acceptors_maximum": 0,
        "num_h_bond_donors_minimum": 0,
        "num_h_bond_donors_maximum": 0,
        "num_rotatable_bonds_minimum": 0,
        "num_rotatable_bonds_maximum": 0,
        "num_rule_of_5_violations_minimum": 0,
        "num_rule_of_5_violations_maximum": 0,
        "topological_polar_surface_area_minimum": 0,
        "topological_polar_surface_area_maximum": 0
      },
      "structure_search_type": "exact",
      "structure_similarity_threshold": 0
    }),
});

const data = await response.json();
Request Body
{
  "async": true,
  "batch_created_after": "2024-01-15",
  "batch_created_before": "2024-01-15",
  "batch_field_after_date": "2024-01-15",
  "batch_field_after_name": "string",
  "batch_field_before_date": "2024-01-15",
  "batch_field_before_name": "string",
  "batch_fields": [
    "string"
  ],
  "collection_criteria": [
    {
      "collection_id": 0,
      "junction": "AND",
      "not_in": false
    }
  ],
  "created_after": "2024-01-15",
  "created_before": "2024-01-15",
  "data_sets": [
    0
  ],
  "fields_search": [
    {
      "name": "string",
      "text_value": "string"
    }
  ],
  "include_original_structures": false,
  "inchikey": "string",
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "molecule_fields": [
    "string"
  ],
  "names": [
    "string"
  ],
  "no_structures": false,
  "offset": 0,
  "only_batch_ids": false,
  "only_ids": false,
  "page_size": 50,
  "projects": [
    0
  ],
  "protocol_criteria": [
    {
      "protocol_id": 0,
      "data_set_id": 0,
      "run_criterion": "any",
      "run_id": 0,
      "run_after": "2024-01-15",
      "run_before": "2024-01-15",
      "since_days_ago": 0,
      "readout_definition_id": 0,
      "operator": "=",
      "readout_value": "string",
      "readout_value_maximum": "string",
      "calculation_error_type": "string",
      "criterion_type": "data set or protocol",
      "field": "string",
      "query": "string",
      "protocol_condition_ids": [
        0
      ],
      "negated": false,
      "junction": "AND"
    }
  ],
  "structure": "string",
  "structure_criterion": {
    "heavy_atom_count_minimum": 0,
    "heavy_atom_count_maximum": 0,
    "cd_molweight_minimum": 0,
    "cd_molweight_maximum": 0,
    "exact_mass_minimum": 0,
    "exact_mass_maximum": 0,
    "log_p_minimum": 0,
    "log_p_maximum": 0,
    "log_d_minimum": 0,
    "log_d_maximum": 0,
    "log_s_minimum": 0,
    "log_s_maximum": 0,
    "num_aromatic_rings_minimum": 0,
    "num_aromatic_rings_maximum": 0,
    "num_h_bond_acceptors_minimum": 0,
    "num_h_bond_acceptors_maximum": 0,
    "num_h_bond_donors_minimum": 0,
    "num_h_bond_donors_maximum": 0,
    "num_rotatable_bonds_minimum": 0,
    "num_rotatable_bonds_maximum": 0,
    "num_rule_of_5_violations_minimum": 0,
    "num_rule_of_5_violations_maximum": 0,
    "topological_polar_surface_area_minimum": 0,
    "topological_polar_surface_area_maximum": 0
  },
  "structure_search_type": "exact",
  "structure_similarity_threshold": 0
}
[
  {
    "batches": [
      {
        "batch_fields": {},
        "class": "batch",
        "created_at": "2024-01-15T09:30:00Z",
        "formula_weight": 0,
        "id": 42,
        "modified_at": "2024-01-15T09:30:00Z",
        "molecule_batch_identifier": "DEMO-1000211-001",
        "name": "Batch 1",
        "owner": "Charlie Weatherall",
        "projects": [
          {
            "id": 1,
            "name": "Project 1"
          }
        ],
        "salt_name": "string",
        "solvent_of_crystallization_name": "string",
        "stoichiometry": {
          "core_count": 0,
          "salt_count": 0,
          "solvent_of_crystallization_count": 0
        }
      }
    ],
    "class": "molecule",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 1000211,
    "modified_at": "2024-01-15T09:30:00Z",
    "molecule_fields": {},
    "name": "Aspirin",
    "owner": "Charlie Weatherall",
    "projects": [
      {
        "id": 1,
        "name": "Project 1"
      }
    ],
    "registration_type": "chemical_structure",
    "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
    "synonyms": [
      "string"
    ]
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get a molecule

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}

Retrieve a single molecule by id. For querying multiple molecules or searching by structure, use POST /molecules/query.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the molecule

no_structuresbooleanquery

Exclude structure representations (smiles, inchi, molfile, etc.).

only_batch_idsbooleanquery

Return only the molecule's batch ids instead of full batch objects.

Response

200OKobject

The molecule

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Molecule not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a molecule
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "batches": [
    {
      "batch_fields": {},
      "class": "batch",
      "created_at": "2024-01-15T09:30:00Z",
      "formula_weight": 0,
      "id": 42,
      "modified_at": "2024-01-15T09:30:00Z",
      "molecule_batch_identifier": "DEMO-1000211-001",
      "name": "Batch 1",
      "owner": "Charlie Weatherall",
      "projects": [
        {
          "id": 1,
          "name": "Project 1"
        }
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }
  ],
  "class": "molecule",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 1000211,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule_fields": {},
  "name": "Aspirin",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "registration_type": "chemical_structure",
  "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
  "synonyms": [
    "string"
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a molecule

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}

Update a molecule. Only the supplied fields are changed; array fields (synonyms, projects, collections) replace the existing values.

Body

application/json

Attributes for updating a molecule. Only the supplied fields are changed. Array fields (synonyms, projects, collections) replace the existing values.

collectionsArray<integer | string>

Collections the molecule belongs to (ids or names). Replaces existing.

Show child attributes
One of
integer
string
molecule_fieldsobject

Custom molecule field values, keyed by field name. The legacy alias udfs is also accepted.

namestring

Name of the molecule.

projectsArray<integer | string>

Projects the molecule belongs to (ids or names). Replaces existing.

Show child attributes
One of
integer
string
structurestring

Updated chemical structure, as SMILES or a molfile.

synonymsArray<string>

Alternative names for the molecule. Replaces existing.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the molecule

Response

200OKobject

The updated molecule

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Molecule not found, or vault is unauthorized

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Update a molecule
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Renamed compound",
      "synonyms": [
        "Aspirin",
        "2-Acetoxybenzoic acid"
      ],
      "molecule_fields": {
        "Solubility": "Medium"
      }
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "name": "Renamed compound",
        "synonyms": [
            "Aspirin",
            "2-Acetoxybenzoic acid"
        ],
        "molecule_fields": {
            "Solubility": "Medium"
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "Renamed compound",
      "synonyms": [
        "Aspirin",
        "2-Acetoxybenzoic acid"
      ],
      "molecule_fields": {
        "Solubility": "Medium"
      }
    }),
});

const data = await response.json();
Request Body
{
  "name": "Renamed compound",
  "synonyms": [
    "Aspirin",
    "2-Acetoxybenzoic acid"
  ],
  "molecule_fields": {
    "Solubility": "Medium"
  }
}
{
  "batches": [
    {
      "batch_fields": {},
      "class": "batch",
      "created_at": "2024-01-15T09:30:00Z",
      "formula_weight": 0,
      "id": 42,
      "modified_at": "2024-01-15T09:30:00Z",
      "molecule_batch_identifier": "DEMO-1000211-001",
      "name": "Batch 1",
      "owner": "Charlie Weatherall",
      "projects": [
        {
          "id": 1,
          "name": "Project 1"
        }
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }
  ],
  "class": "molecule",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 1000211,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule_fields": {},
  "name": "Aspirin",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "registration_type": "chemical_structure",
  "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
  "synonyms": [
    "string"
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a molecule image

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}/image

Request a rendered image of a molecule's structure. Image generation is asynchronous: this returns an export object whose progress you poll with GET /export_progress/{export_id}, then download the image with GET /exports/{export_id} once it is finished.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the molecule

widthintegerquery

Image width in pixels.

heightintegerquery

Image height in pixels.

formatstringsvgpngsvgquery

Image format.

Response

200OKobject

The export to poll for the generated image

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Molecule not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a molecule image
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}/image' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}/image',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/molecules/{id}/image', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "queued_job_position": 0,
  "status": "new"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Plates

Plates of wells

Get plates

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates

List plates in the vault. Supports pagination (page_size, offset), asynchronous retrieval (async=true), only_ids, and filtering by name, location, project, and creation/modification dates.

Parameters

vault_idintegerrequiredpath
page_sizeintegerquery

Maximum number of records to return (default 50, maximum 1000).

offsetintegerquery

Number of records to skip (for pagination).

asyncbooleanquery

If true, run the listing as an asynchronous export.

only_idsbooleanquery

If true, return only the ids of matching plates.

platesstringquery

Comma-separated plate ids to filter by.

namesstringquery

Comma-separated plate names to filter by.

projectsstringquery

Comma-separated project ids to filter by.

Response

200OKArray<object>

List of plates

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get plates
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "class": "plate",
    "concentration": 0,
    "concentration_unit_label": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 0,
    "inventory_location_id": 0,
    "location": "string",
    "modified_at": "2024-01-15T09:30:00Z",
    "name": "string",
    "projects": [
      {
        "id": 0,
        "name": "string"
      }
    ],
    "statistics": [
      {}
    ],
    "volume": 0,
    "volume_unit_label": "string",
    "wells": [
      {
        "batch": 0,
        "col": 0,
        "row": 0,
        "sample": 0
      }
    ]
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Create a plate

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates

Create a plate. Requires write permission in the vault.

Body

application/json

Attributes for creating or updating a plate. On create, name and projects are required. Supplying wells replaces the plate's wells.

concentrationnumber
concentration_unit_labelstring
inventory_locationinteger

Id of the inventory location for the plate.

locationstring
namestring
projectsArray<integer>

Project ids the plate belongs to.

volumenumber
volume_unit_labelstring
wellsArray<object>

Wells to populate. Each well identifies its position by row+col or pos.

Show child attributes
batchinteger

Batch id to place in the well.

colinteger
posstring

Well position in letter-number form (e.g. "A1"), as an alternative to row/col.

rowinteger

Parameters

vault_idintegerrequiredpath

Response

200OKobject

The created plate

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Create a plate
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Plate 001",
      "projects": [
        12
      ],
      "location": "Freezer A",
      "wells": [
        {
          "row": 0,
          "col": 0,
          "batch": 456
        }
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "name": "Plate 001",
        "projects": [
            12
        ],
        "location": "Freezer A",
        "wells": [
            {
                "row": 0,
                "col": 0,
                "batch": 456
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "Plate 001",
      "projects": [
        12
      ],
      "location": "Freezer A",
      "wells": [
        {
          "row": 0,
          "col": 0,
          "batch": 456
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "name": "Plate 001",
  "projects": [
    12
  ],
  "location": "Freezer A",
  "wells": [
    {
      "row": 0,
      "col": 0,
      "batch": 456
    }
  ]
}
{
  "class": "plate",
  "concentration": 0,
  "concentration_unit_label": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "inventory_location_id": 0,
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "projects": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "statistics": [
    {}
  ],
  "volume": 0,
  "volume_unit_label": "string",
  "wells": [
    {
      "batch": 0,
      "col": 0,
      "row": 0,
      "sample": 0
    }
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a plate

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}

Retrieve a single plate.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the plate

Response

200OKobject

The plate

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Plate not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a plate
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "class": "plate",
  "concentration": 0,
  "concentration_unit_label": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "inventory_location_id": 0,
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "projects": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "statistics": [
    {}
  ],
  "volume": 0,
  "volume_unit_label": "string",
  "wells": [
    {
      "batch": 0,
      "col": 0,
      "row": 0,
      "sample": 0
    }
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a plate

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}

Update a plate. Requires write permission.

Body

application/json

Attributes for creating or updating a plate. On create, name and projects are required. Supplying wells replaces the plate's wells.

concentrationnumber
concentration_unit_labelstring
inventory_locationinteger

Id of the inventory location for the plate.

locationstring
namestring
projectsArray<integer>

Project ids the plate belongs to.

volumenumber
volume_unit_labelstring
wellsArray<object>

Wells to populate. Each well identifies its position by row+col or pos.

Show child attributes
batchinteger

Batch id to place in the well.

colinteger
posstring

Well position in letter-number form (e.g. "A1"), as an alternative to row/col.

rowinteger

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the plate

Response

200OKobject

The updated plate

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Plate not found, or vault is unauthorized

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Update a plate
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Plate 001",
      "projects": [
        12
      ],
      "location": "Freezer A",
      "wells": [
        {
          "row": 0,
          "col": 0,
          "batch": 456
        }
      ]
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "name": "Plate 001",
        "projects": [
            12
        ],
        "location": "Freezer A",
        "wells": [
            {
                "row": 0,
                "col": 0,
                "batch": 456
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "Plate 001",
      "projects": [
        12
      ],
      "location": "Freezer A",
      "wells": [
        {
          "row": 0,
          "col": 0,
          "batch": 456
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "name": "Plate 001",
  "projects": [
    12
  ],
  "location": "Freezer A",
  "wells": [
    {
      "row": 0,
      "col": 0,
      "batch": 456
    }
  ]
}
{
  "class": "plate",
  "concentration": 0,
  "concentration_unit_label": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "inventory_location_id": 0,
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "projects": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "statistics": [
    {}
  ],
  "volume": 0,
  "volume_unit_label": "string",
  "wells": [
    {
      "batch": 0,
      "col": 0,
      "row": 0,
      "sample": 0
    }
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Delete a plate

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}

Delete a plate. Requires write permission. A plate that has associated run data cannot be deleted.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the plate

Response

200OK

The plate was deleted

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Plate not found, or vault is unauthorized

422Unprocessable Entityobject

The plate cannot be deleted (it has associated run data)

Authorization

ApiKeyAuthapiKey in header
Delete a plate
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/plates/{id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Projects

Projects within a vault

Get projects

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects

List the projects accessible to the API key in the vault. Each entry contains the project id and name.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of projects

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get projects
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "description": "string",
    "id": 0,
    "members": [
      {
        "can_edit_data": true,
        "can_manage_project": true,
        "id": 0
      }
    ],
    "name": "string"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Create a project

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects

Create a project. Requires permission to manage projects in the vault. The response contains the new project's id and name.

Body

application/json

Attributes for creating or updating a project.

descriptionstring

Project description.

membersArray<object>

Project members. On update this replaces the existing membership list. If omitted on create, the current user is added as a member.

Show child attributes
can_edit_databooleanfalse
can_manage_projectbooleanfalse
user_idintegerrequired

Id of an existing vault user.

namestringrequired

Project name (must be unique within the vault).

Parameters

vault_idintegerrequiredpath

Response

200OKobject

The created project

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Create a project
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "My project",
      "description": "Compounds from the 2026 screening campaign",
      "members": [
        {
          "user_id": 6021,
          "can_manage_project": true,
          "can_edit_data": true
        }
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "name": "My project",
        "description": "Compounds from the 2026 screening campaign",
        "members": [
            {
                "user_id": 6021,
                "can_manage_project": true,
                "can_edit_data": true
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "My project",
      "description": "Compounds from the 2026 screening campaign",
      "members": [
        {
          "user_id": 6021,
          "can_manage_project": true,
          "can_edit_data": true
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "name": "My project",
  "description": "Compounds from the 2026 screening campaign",
  "members": [
    {
      "user_id": 6021,
      "can_manage_project": true,
      "can_edit_data": true
    }
  ]
}
{
  "description": "string",
  "id": 0,
  "members": [
    {
      "can_edit_data": true,
      "can_manage_project": true,
      "id": 0
    }
  ],
  "name": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a project

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}

Retrieve a single project, including its description and members.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the project

Response

200OKobject

The project

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Project not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a project
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "description": "string",
  "id": 0,
  "members": [
    {
      "can_edit_data": true,
      "can_manage_project": true,
      "id": 0
    }
  ],
  "name": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a project

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}

Update a project. Requires permission to manage projects. Supplying members replaces the existing membership list.

Body

application/json

Attributes for creating or updating a project.

descriptionstring

Project description.

membersArray<object>

Project members. On update this replaces the existing membership list. If omitted on create, the current user is added as a member.

Show child attributes
can_edit_databooleanfalse
can_manage_projectbooleanfalse
user_idintegerrequired

Id of an existing vault user.

namestringrequired

Project name (must be unique within the vault).

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the project

Response

200OKobject

The updated project

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Project not found, or vault is unauthorized

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Update a project
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "My project",
      "description": "Compounds from the 2026 screening campaign",
      "members": [
        {
          "user_id": 6021,
          "can_manage_project": true,
          "can_edit_data": true
        }
      ]
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "name": "My project",
        "description": "Compounds from the 2026 screening campaign",
        "members": [
            {
                "user_id": 6021,
                "can_manage_project": true,
                "can_edit_data": true
            }
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "My project",
      "description": "Compounds from the 2026 screening campaign",
      "members": [
        {
          "user_id": 6021,
          "can_manage_project": true,
          "can_edit_data": true
        }
      ]
    }),
});

const data = await response.json();
Request Body
{
  "name": "My project",
  "description": "Compounds from the 2026 screening campaign",
  "members": [
    {
      "user_id": 6021,
      "can_manage_project": true,
      "can_edit_data": true
    }
  ]
}
{
  "description": "string",
  "id": 0,
  "members": [
    {
      "can_edit_data": true,
      "can_manage_project": true,
      "id": 0
    }
  ],
  "name": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Delete a project

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}

Delete a project. Requires permission to manage projects. A project that still has associated data (runs, models, etc.) may not be deletable.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the project

Response

200OK

The project was deleted

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Project not found, or vault is unauthorized

422Unprocessable Entityobject

The project cannot be deleted (it still has associated data)

Authorization

ApiKeyAuthapiKey in header
Delete a project
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/projects/{id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Protocols

Protocols and their readout data

Get protocols

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols

List protocols in the vault. Supports pagination (page_size, offset), asynchronous retrieval (async=true), only_ids, no_runs (omit run data), and filtering by name, project, molecule, plate, and dates.

Parameters

vault_idintegerrequiredpath
page_sizeintegerquery

Maximum number of records to return (default 50, maximum 1000).

offsetintegerquery

Number of records to skip (for pagination).

asyncbooleanquery

If true, run the listing as an asynchronous export.

only_idsbooleanquery

If true, return only the ids of matching protocols.

no_runsbooleanquery

If true, omit run data from each protocol.

namesstringquery

Comma-separated protocol names to filter by.

protocolsstringquery

Comma-separated protocol ids to filter by.

projectsstringquery

Comma-separated project ids to filter by.

Response

200OKobject

A page of protocols

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get protocols
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "count": 0,
  "objects": [
    {
      "calculations": [
        {}
      ],
      "category": "string",
      "class": "protocol",
      "created_at": "2024-01-15T09:30:00Z",
      "data_set": 0,
      "description": "string",
      "hit_definitions": [
        {}
      ],
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "name": "string",
      "ontology_annotations": [
        {}
      ],
      "owner": "string",
      "projects": [
        0
      ],
      "protocol_fields": {},
      "protocol_statistics": [
        {}
      ],
      "readout_definitions": [
        {}
      ],
      "runs": [
        {}
      ]
    }
  ],
  "offset": 0,
  "page_size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get a protocol

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}

Retrieve a single protocol. Pass no_runs=true to omit run data.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the protocol

no_runsbooleanquery

If true, omit run data from the response.

Response

200OKobject

The protocol

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Protocol not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a protocol
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "calculations": [
    {}
  ],
  "category": "string",
  "class": "protocol",
  "created_at": "2024-01-15T09:30:00Z",
  "data_set": 0,
  "description": "string",
  "hit_definitions": [
    {}
  ],
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "ontology_annotations": [
    {}
  ],
  "owner": "string",
  "projects": [
    0
  ],
  "protocol_fields": {},
  "protocol_statistics": [
    {}
  ],
  "readout_definitions": [
    {}
  ],
  "runs": [
    {}
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a protocol

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}

Update a protocol's definition (name, projects, and protocol field values). This does not modify readout definitions. Requires write permission.

Body

application/json

Attributes for updating a protocol's definition (not its readout definitions). Only the supplied fields are changed.

namestring
projectsArray<integer>

Project ids the protocol belongs to (replaces the existing set).

protocol_fieldsobject

Custom protocol field values, keyed by field name.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the protocol

Response

200OKobject

The updated protocol

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Protocol not found, or vault is unauthorized

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Update a protocol
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "My Inhibition Screen",
      "projects": [
        12
      ],
      "protocol_fields": {
        "Category": "Biochemical"
      }
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "name": "My Inhibition Screen",
        "projects": [
            12
        ],
        "protocol_fields": {
            "Category": "Biochemical"
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "My Inhibition Screen",
      "projects": [
        12
      ],
      "protocol_fields": {
        "Category": "Biochemical"
      }
    }),
});

const data = await response.json();
Request Body
{
  "name": "My Inhibition Screen",
  "projects": [
    12
  ],
  "protocol_fields": {
    "Category": "Biochemical"
  }
}
{
  "calculations": [
    {}
  ],
  "category": "string",
  "class": "protocol",
  "created_at": "2024-01-15T09:30:00Z",
  "data_set": 0,
  "description": "string",
  "hit_definitions": [
    {}
  ],
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "ontology_annotations": [
    {}
  ],
  "owner": "string",
  "projects": [
    0
  ],
  "protocol_fields": {},
  "protocol_statistics": [
    {}
  ],
  "readout_definitions": [
    {}
  ],
  "runs": [
    {}
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get protocol data

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/data

Retrieve the readout data (detail rows, with any matching aggregate-row readouts merged in) for a protocol. Supports pagination and filtering by molecule, plate, run, and project. Pass format=csv to produce a CSV export instead of JSON.

Parameters

vault_idintegerrequiredpath
protocol_idintegerrequiredpath

Numeric identifier of the protocol

page_sizeintegerquery

Maximum number of records to return (default 50, maximum 1000).

offsetintegerquery

Number of records to skip (for pagination).

asyncbooleanquery

If true, run the query as an asynchronous export.

formatstringquery

If "csv", produce a CSV export instead of a JSON page.

moleculesstringquery

Comma-separated molecule ids to filter by.

runsstringquery

Comma-separated run ids to filter by.

platesstringquery

Comma-separated plate ids to filter by.

projectsstringquery

Comma-separated project ids to filter by.

Response

200OKobject

A page of protocol readout data

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get protocol data
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/data' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/data',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/protocols/{protocol_id}/data', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "count": 0,
  "objects": [
    {
      "batch": 0,
      "id": 0,
      "molecule": 0,
      "readouts": {},
      "run": 0,
      "well": {}
    }
  ],
  "offset": 0,
  "page_size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get dose-response plot

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}/protocols/{id}/plot

Generate dose-response plot image(s) for a batch within a protocol. By default, returns a ZIP archive containing one PNG per dose-response calculation on the protocol. Pass dose_response_calculation_id to get a single PNG for one calculation instead.

Parameters

vault_idintegerrequiredpath
batch_idintegerrequiredpath

Numeric identifier of the batch

idintegerrequiredpath

Numeric identifier of the protocol

dose_response_calculation_idintegerquery

Restrict the plot to a single dose-response calculation. When provided, a single PNG is returned; when omitted, a ZIP of PNGs is returned.

sizestringsmallmediumlargequery

Image size multiplier.

runsstringquery

Comma-separated run ids to restrict the plotted data to.

Response

200OKstring<binary>

A single PNG (when dose_response_calculation_id is given) or a ZIP archive of PNGs (otherwise).

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

No data found for this batch/protocol, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get dose-response plot
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}/protocols/{id}/plot' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}/protocols/{id}/plot',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.content
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/batches/{batch_id}/protocols/{id}/plot', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.blob();
"<binary>"
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Readout Rows

Rows of protocol readout data

Get multiple readout rows

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/query

Get multiple readout rows (rows of protocol data). We still support the now deprecated GET queries on the endpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.

When async is true the request returns an export to poll instead of the readout rows; check it with the GET export progress call and retrieve the result with the GET export call.

Body

application/json
asyncboolean

If true, do an asynchronous export. Use for large data sets.

batchesArray<integer>

Array of batch ids. Defaults to all batches.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

data_setsArray<integer>

Array of public dataset ids. Defaults to all data sets.

include_control_statebooleanfalse

If true, include the control state of each readout.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

moleculesArray<integer>

Array of molecule ids. Defaults to all molecules.

offsetinteger
only_idsbooleanfalse

If true, only return the ids of the readout rows.

page_sizeinteger50

Requested page size (maximum value 1000).

platesArray<integer>

Array of plate ids. Defaults to all plates.

projectsArray<integer>

Array of project ids. Defaults to all available projects.

protocolsArray<integer>

Array of protocol ids. Defaults to all protocols.

runsArray<integer>

Array of run ids. Defaults to all runs.

runs_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

runs_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

typeArray<string>detail_rowbatch_run_aggregate_rowbatch_protocol_aggregate_rowmolecule_protocol_aggregate_row

Filter to specific readout row types. Defaults to all types.

Parameters

vault_idintegerrequiredpath

Response

200OKobject | object

The matching readout rows, or the export to poll when async is true

401Unauthorizedobject

Missing or invalid API key

422Unprocessable Entityobject

Invalid query parameters, such as an illegal type

Authorization

ApiKeyAuthapiKey in header
Get multiple readout rows
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/query' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "async": true,
      "batches": [
        0
      ],
      "created_after": "string",
      "created_before": "string",
      "data_sets": [
        0
      ],
      "include_control_state": false,
      "modified_after": "string",
      "modified_before": "string",
      "molecules": [
        0
      ],
      "offset": 0,
      "only_ids": false,
      "page_size": 50,
      "plates": [
        0
      ],
      "projects": [
        0
      ],
      "protocols": [
        0
      ],
      "runs": [
        0
      ],
      "runs_after": "string",
      "runs_before": "string",
      "type": [
        "detail_row"
      ]
    }'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/query',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "async": true,
        "batches": [
            0
        ],
        "created_after": "string",
        "created_before": "string",
        "data_sets": [
            0
        ],
        "include_control_state": false,
        "modified_after": "string",
        "modified_before": "string",
        "molecules": [
            0
        ],
        "offset": 0,
        "only_ids": false,
        "page_size": 50,
        "plates": [
            0
        ],
        "projects": [
            0
        ],
        "protocols": [
            0
        ],
        "runs": [
            0
        ],
        "runs_after": "string",
        "runs_before": "string",
        "type": [
            "detail_row"
        ]
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/query', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "async": true,
      "batches": [
        0
      ],
      "created_after": "string",
      "created_before": "string",
      "data_sets": [
        0
      ],
      "include_control_state": false,
      "modified_after": "string",
      "modified_before": "string",
      "molecules": [
        0
      ],
      "offset": 0,
      "only_ids": false,
      "page_size": 50,
      "plates": [
        0
      ],
      "projects": [
        0
      ],
      "protocols": [
        0
      ],
      "runs": [
        0
      ],
      "runs_after": "string",
      "runs_before": "string",
      "type": [
        "detail_row"
      ]
    }),
});

const data = await response.json();
Request Body
{
  "async": true,
  "batches": [
    0
  ],
  "created_after": "2024-01-15",
  "created_before": "2024-01-15",
  "data_sets": [
    0
  ],
  "include_control_state": false,
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "molecules": [
    0
  ],
  "offset": 0,
  "only_ids": false,
  "page_size": 50,
  "plates": [
    0
  ],
  "projects": [
    0
  ],
  "protocols": [
    0
  ],
  "runs": [
    0
  ],
  "runs_after": "2024-01-15",
  "runs_before": "2024-01-15",
  "type": [
    "detail_row"
  ]
}
{
  "count": 0,
  "objects": [
    {
      "batch": 1,
      "class": "readout row",
      "created_at": "2024-01-02T03:04:05.000Z",
      "id": 1,
      "modified_at": "2024-01-02T03:04:05.000Z",
      "molecule": 1,
      "protocol": 1,
      "readouts": {},
      "run": 1,
      "type": "detail_row",
      "well": "string"
    }
  ],
  "offset": 0,
  "page_size": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update existing row

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}

Updates an existing readout row (including the ability to flag an existing readout row as an outlier).

This PUT Readout_Rows API call allows users to update a specified row of Protocol data or flag a specified row of Protocol data as an outlier. Only detail rows can be updated; aggregate rows cannot be updated via the API.

Noteworthy tips:

  • The GET Protocol Data API call will be useful to ascertain the id of the readout row for the Protocol data you wish to edit. - The GET Protocols API call also provides the readout definition IDs.

Body

application/json
readoutsobject

New readout values and/or outlier flags, keyed by readout definition ID

Parameters

vault_idintegerrequiredpath
readout_row_idintegerrequiredpath

Response

200OKobject

The updated readout row

400Bad Requestobject

Invalid readout keys (only "value" and "outlier" are allowed), invalid outlier flag value, or the readout cannot be flagged as an outlier

401Unauthorizedobject

Missing or invalid API key

403Forbiddenobject

Aggregate rows can't be updated via the API. Only detail rows can be updated

404Not Foundobject

Couldn't find this readout row or one of its readouts

Authorization

ApiKeyAuthapiKey in header
Update existing row
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "readouts": {
        "283130": {
          "value": 99
        },
        "283131": {
          "outlier": true
        }
      }
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "readouts": {
            "283130": {
                "value": 99
            },
            "283131": {
                "outlier": true
            }
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "readouts": {
        "283130": {
          "value": 99
        },
        "283131": {
          "outlier": true
        }
      }
    }),
});

const data = await response.json();
Request Body
{
  "readouts": {
    "283130": {
      "value": 99
    },
    "283131": {
      "outlier": true
    }
  }
}
{
  "id": 1,
  "readouts": {}
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Delete a readout row

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}

Delete a single readout row (row of protocol data). Only detail rows can be deleted; aggregate rows cannot be deleted via the API.

Parameters

vault_idintegerrequiredpath
readout_row_idintegerrequiredpath

Response

200OKobject

The readout row was deleted

401Unauthorizedobject

Missing or invalid API key

403Forbiddenobject

Aggregate rows can't be destroyed via the API. Only detail rows can be destroyed

404Not Foundobject

Couldn't find this readout row

Authorization

ApiKeyAuthapiKey in header
Delete a readout row
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/readout_rows/{readout_row_id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "message": "Readout row with ID 1 has been destroyed"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Registration Forms

Registration forms

Get registration forms

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms

List the registration forms configured in the vault.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of registration forms

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get registration forms
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "allow_new_molecules": true,
    "class": "registration form",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 0,
    "modified_at": "2024-01-15T09:30:00Z",
    "name": "string",
    "registration_system": {
      "class": "registration system",
      "id": 0
    },
    "registration_type": "string"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get a registration form

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms/{id}

Retrieve a single registration form.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the registration form

Response

200OKobject

The registration form

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Registration form not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a registration form
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_forms/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "allow_new_molecules": true,
  "class": "registration form",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "registration_system": {
    "class": "registration system",
    "id": 0
  },
  "registration_type": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Registration Systems

Registration systems

Get registration systems

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems

List the registration systems defined in the vault.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of registration systems

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get registration systems
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "id": 0,
    "prefix": "CDD"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get a registration system

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems/{id}

Retrieve a single registration system.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the registration system

Response

200OKobject

The registration system

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Registration system not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a registration system
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/registration_systems/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "id": 0,
  "prefix": "CDD"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Runs

Runs of protocol data

Get runs

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs

List runs in the vault. Supports pagination (page_size, offset), asynchronous retrieval (async=true), only_ids, and filtering by protocol, project, slurp, run date, and creation/modification dates.

Parameters

vault_idintegerrequiredpath
page_sizeintegerquery

Maximum number of records to return (default 50, maximum 1000).

offsetintegerquery

Number of records to skip (for pagination).

asyncbooleanquery

If true, run the listing as an asynchronous export.

only_idsbooleanquery

If true, return only the ids of matching runs.

protocolsstringquery

Comma-separated protocol ids to filter by.

projectsstringquery

Comma-separated project ids to filter by.

slurpintegerquery

Only include runs imported by this slurp id.

run_date_afterstring<date>query

Include runs with a run date on/after this date.

run_date_beforestring<date>query

Include runs with a run date on/before this date.

Response

200OKArray<object>

List of runs

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get runs
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "attached_files": [
      {}
    ],
    "class": "run",
    "conditions": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "eln_entries": [
      {}
    ],
    "id": 0,
    "modified_at": "2024-01-15T09:30:00Z",
    "ontology_annotations": [
      {}
    ],
    "person": "string",
    "place": "string",
    "plate_statistics": [
      {}
    ],
    "project": {
      "id": 0,
      "name": "string"
    },
    "protocol": 0,
    "run_date": "2024-01-15",
    "run_fields": {},
    "source_files": [
      {}
    ]
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Delete runs by slurp

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs

Delete all runs that were imported by a given slurp. Pass the slurp id as the slurp query parameter. Requires write permission for all affected runs. (To delete a single run, use DELETE /runs/{id}.)

Parameters

vault_idintegerrequiredpath
slurpintegerrequiredquery

Id of the slurp whose runs should be deleted.

Response

200OKobject

The slurp's runs were deleted

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Delete runs by slurp
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "message": "string",
  "status": 0
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Get a run

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}

Retrieve a single run, including its plate statistics.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the run

Response

200OKobject

The run

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Run not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a run
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "attached_files": [
    {}
  ],
  "class": "run",
  "conditions": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "eln_entries": [
    {}
  ],
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "ontology_annotations": [
    {}
  ],
  "person": "string",
  "place": "string",
  "plate_statistics": [
    {}
  ],
  "project": {
    "id": 0,
    "name": "string"
  },
  "protocol": 0,
  "run_date": "2024-01-15",
  "run_fields": {},
  "source_files": [
    {}
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Update a run

PUT
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}

Update a run. Only the supplied fields are changed. Use project_id to move the run to a different project. Requires write permission.

Body

application/json

Attributes for updating a run. Only the supplied fields are changed.

conditionsstring

Value for the Conditions run field (alternative to run_fields).

personstring

Value for the Person run field (alternative to run_fields).

placestring

Value for the Lab run field (alternative to run_fields).

project_idinteger

Move the run to this project (requires write access to the target project).

run_datestring<date>
run_fieldsobject

Custom run field values, keyed by field name.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the run

Response

200OKobject

The updated run

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Run not found, or vault is unauthorized

422Unprocessable Entityobject

Validation error

Authorization

ApiKeyAuthapiKey in header
Update a run
curl -X PUT 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "run_date": "2026-01-15",
      "run_fields": {
        "Person": "Jane Smith"
      }
    }'
import requests

response = requests.put(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    json={
        "run_date": "2026-01-15",
        "run_fields": {
            "Person": "Jane Smith"
        }
    },
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}', {
  method: 'PUT',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "run_date": "2026-01-15",
      "run_fields": {
        "Person": "Jane Smith"
      }
    }),
});

const data = await response.json();
Request Body
{
  "run_date": "2026-01-15T00:00:00.000Z",
  "run_fields": {
    "Person": "Jane Smith"
  }
}
{
  "attached_files": [
    {}
  ],
  "class": "run",
  "conditions": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "eln_entries": [
    {}
  ],
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "ontology_annotations": [
    {}
  ],
  "person": "string",
  "place": "string",
  "plate_statistics": [
    {}
  ],
  "project": {
    "id": 0,
    "name": "string"
  },
  "protocol": 0,
  "run_date": "2024-01-15",
  "run_fields": {},
  "source_files": [
    {}
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}
{
  "code": 404,
  "error": "Resource not found"
}

Delete a run

DELETE
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}

Delete a single run. Requires write permission.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the run

Response

200OK

The run was deleted

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Run not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Delete a run
curl -X DELETE 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.delete(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/runs/{id}', {
  method: 'DELETE',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Searches

Saved searches

List of all saved searches

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches

Return a list of accessible saved searches for the given vault.

Parameters

vault_idintegerrequiredpath

Response

200OKArray<object>

List of saved searches, each including its full search_criteria (structure, keyword, and molecule/collection/protocol criteria) and display_criteria.

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
List of all saved searches
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "display_criteria": {
      "custom_displayed_header_ids": [],
      "displayed_header_ids": [],
      "header_group_order": [],
      "image_size": "string",
      "max_column_width": 0,
      "plot_scale_type": "string",
      "row_detail_level": "string",
      "show_all_protocol_data": true,
      "show_dose_response_legend": true,
      "show_non_matching_readouts": true
    },
    "executed_by": [
      "string"
    ],
    "id": 0,
    "last_api_run_at": "2024-01-15T09:30:00Z",
    "last_ui_run_at": "2024-01-15T09:30:00Z",
    "name": "string",
    "owner": "string",
    "projects": [
      {}
    ],
    "saved_search_session_id": 0,
    "search_criteria": {
      "collection_criteria": [
        {
          "collection_id": 0,
          "junction": "AND",
          "not_in": true
        }
      ],
      "keyword_field": "string",
      "keywords": "string",
      "molecule_criteria": [
        {}
      ],
      "protocol_criteria": [
        {
          "protocol_id": 0,
          "data_set_id": 0,
          "run_criterion": "any",
          "run_id": 0,
          "run_after": "2024-01-15",
          "run_before": "2024-01-15",
          "since_days_ago": 0,
          "readout_definition_id": 0,
          "operator": "=",
          "readout_value": "string",
          "readout_value_maximum": "string",
          "calculation_error_type": "string",
          "criterion_type": "data set or protocol",
          "field": "string",
          "query": "string",
          "protocol_condition_ids": [
            0
          ],
          "negated": false,
          "junction": "AND"
        }
      ],
      "sort_direction": "ASC",
      "structure": "string",
      "structure_criterion": {
        "heavy_atom_count_minimum": 0,
        "heavy_atom_count_maximum": 0,
        "cd_molweight_minimum": 0,
        "cd_molweight_maximum": 0,
        "exact_mass_minimum": 0,
        "exact_mass_maximum": 0,
        "log_p_minimum": 0,
        "log_p_maximum": 0,
        "log_d_minimum": 0,
        "log_d_maximum": 0,
        "log_s_minimum": 0,
        "log_s_maximum": 0,
        "num_aromatic_rings_minimum": 0,
        "num_aromatic_rings_maximum": 0,
        "num_h_bond_acceptors_minimum": 0,
        "num_h_bond_acceptors_maximum": 0,
        "num_h_bond_donors_minimum": 0,
        "num_h_bond_donors_maximum": 0,
        "num_rotatable_bonds_minimum": 0,
        "num_rotatable_bonds_maximum": 0,
        "num_rule_of_5_violations_minimum": 0,
        "num_rule_of_5_violations_maximum": 0,
        "topological_polar_surface_area_minimum": 0,
        "topological_polar_surface_area_maximum": 0
      },
      "structure_registration_type": "structure",
      "structure_search_type": "string",
      "structure_similarity_threshold": 0
    },
    "visualization_session_id": 0
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Execute a given search

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches/{search_id}

Unlike other calls, saved searches can only be performed asynchronously.

Returns an export id and status.

See Async Exports for how to check on the status of your call and retrieving the data once it has finished.

Parameters

vault_idintegerrequiredpath
search_idintegerrequiredpath
projectsArray<integer>query

Comma separated list of the ids of the projects to search

data_setsArray<integer>query

Comma separated list of the ids of the data sets to search

zipbooleanfalsequery

Should it be zipped

formatstringcsvsdfxlsxlsxcsvquery

Format of the exported file

Response

200OKobject

Export information

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Execute a given search
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches/{search_id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches/{search_id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/searches/{search_id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "queued_job_position": 0,
  "status": "new"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Slurps

Data import jobs (slurps)

Get slurps

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps

List the active slurps (data import jobs) in the vault. Pass show_events=true to include the ambiguous/suspicious events and import errors raised during import.

Parameters

vault_idintegerrequiredpath
show_eventsbooleanquery

Include event and error details for each slurp.

Response

200OKArray<object>

List of active slurps

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get slurps
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "ambiguous_events": [
      {}
    ],
    "ambiguous_events_count": 0,
    "api_url": "string",
    "class": "slurp",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 0,
    "import_errors": 0,
    "import_errors_count": 0,
    "import_warnings": 0,
    "message": "string",
    "modified_at": "2024-01-15T09:30:00Z",
    "queued_job_position": 0,
    "queued_slurp_position": 0,
    "records_committed": 0,
    "records_processed": 0,
    "state": "mapping",
    "suspicious_events": [
      {}
    ],
    "suspicious_events_count": 0,
    "total_records": 0,
    "web_url": "string"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Create a slurp

POST
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps

Start a new slurp (data import) by uploading a file. The request must be sent as multipart/form-data: the data file is the file part, and any import metadata is supplied as a JSON string in the json part. The new slurp is created in the mapping state; poll the slurp to follow its progress.

Body

multipart/form-data
filestring<binary>required

The data file to import (CSV, XLSX, SDF, etc.).

jsonstring

Import metadata (such as mapping options) encoded as a JSON string.

Parameters

vault_idintegerrequiredpath

Response

200OKobject

The created slurp

401Unauthorizedobject

Missing or invalid API key

429Too Many Requestsobject

Too many concurrent slurps for this user

Authorization

ApiKeyAuthapiKey in header
Create a slurp
curl -X POST 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps' \
  -H 'X-CDD-Token: YOUR_API_KEY' \
  -F 'file=@/path/to/file' \
  -F 'json=string'
import requests

response = requests.post(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
    files={'file': open('/path/to/file', 'rb')},
    data={'json': 'string'},
)
data = response.json()
// `fileInput` is a file <input> element, e.g. document.querySelector('input[type=file]')
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('json', 'string');

const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps', {
  method: 'POST',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
  body: formData,
});

const data = await response.json();
Request Body
{
  "file": "<binary>",
  "json": "string"
}
{
  "ambiguous_events": [
    {}
  ],
  "ambiguous_events_count": 0,
  "api_url": "string",
  "class": "slurp",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "import_errors": 0,
  "import_errors_count": 0,
  "import_warnings": 0,
  "message": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "queued_job_position": 0,
  "queued_slurp_position": 0,
  "records_committed": 0,
  "records_processed": 0,
  "state": "mapping",
  "suspicious_events": [
    {}
  ],
  "suspicious_events_count": 0,
  "total_records": 0,
  "web_url": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Get a slurp

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps/{id}

Retrieve a single slurp. Pass show_events=true to include the ambiguous/suspicious events and import errors raised during import.

Parameters

vault_idintegerrequiredpath
idintegerrequiredpath

Numeric identifier of the slurp

show_eventsbooleanquery

Include event and error details.

Response

200OKobject

The slurp

401Unauthorizedobject

Missing or invalid API key

404Not Foundobject

Slurp not found, or vault is unauthorized

Authorization

ApiKeyAuthapiKey in header
Get a slurp
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps/{id}' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps/{id}',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/slurps/{id}', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "ambiguous_events": [
    {}
  ],
  "ambiguous_events_count": 0,
  "api_url": "string",
  "class": "slurp",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "import_errors": 0,
  "import_errors_count": 0,
  "import_warnings": 0,
  "message": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "queued_job_position": 0,
  "queued_slurp_position": 0,
  "records_committed": 0,
  "records_processed": 0,
  "state": "mapping",
  "suspicious_events": [
    {}
  ],
  "suspicious_events_count": 0,
  "total_records": 0,
  "web_url": "string"
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}
{
  "code": 404,
  "error": "Resource not found"
}

Status

Vault operational status

Get vault status

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/status

Retrieve the operational status of the vault: currently running imports (slurps), recalculating protocols, and overall availability of the background processing services. Requires vault administrator access.

Parameters

vault_idintegerrequiredpath

Response

200OKobject

The current vault status

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
Get vault status
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/status' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/status',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/status', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
{
  "any_executing_batch_move_job": true,
  "any_locking_chemistry_slurps": true,
  "application_status": {
    "calculators_available": true,
    "downtime_expected": {
      "end": "2024-01-15T09:30:00Z",
      "reason": "string",
      "start": "2024-01-15T09:30:00Z"
    },
    "processors_available": true
  },
  "max_executing_account_slurps": 0,
  "num_executing_account_slurps": 0,
  "recalculating_protocols": [
    {
      "id": 0,
      "name": "string",
      "projects": [
        {
          "id": 0,
          "name": "string"
        }
      ]
    }
  ],
  "slurps": [
    {
      "chemistry_locking": true,
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "owner": {
        "email": "string",
        "first_name": "string",
        "id": 0,
        "last_name": "string"
      },
      "project": {
        "id": 0,
        "name": "string"
      },
      "state": "queued_for_processing"
    }
  ]
}
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Users

Users management

List of users of a vault

GET
https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/users

Returns a list of CDD Vault members.

Noteworthy Tips:

  • Only Vault Administrators can use this GET Users API call.
  • This API call is useful to identify the Members' IDs of users for use in the GET ELN Entries API call.

Parameters

vault_idintegerrequiredpath
include_projectsbooleanquery

If true, each user’s Vault role and an array of project memberships are returned

Response

200OKArray<object> | Array<object>

Users of the vault

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
List of users of a vault
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/users' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/users',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults/{vault_id}/users', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "first_name": "string",
    "id": 0,
    "last_name": "string"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Vaults

Vaults management

List of vaults

GET
https://app.collaborativedrug.com/api/v1/vaults

Return a list of accessible vaults

Response

200OKArray<object>

List of vaults

401Unauthorizedobject

Missing or invalid API key

Authorization

ApiKeyAuthapiKey in header
List of vaults
curl -X GET 'https://app.collaborativedrug.com/api/v1/vaults' \
  -H 'X-CDD-Token: YOUR_API_KEY'
import requests

response = requests.get(
    'https://app.collaborativedrug.com/api/v1/vaults',
    headers={'X-CDD-Token': 'YOUR_API_KEY'},
)
data = response.json()
const response = await fetch('https://app.collaborativedrug.com/api/v1/vaults', {
  method: 'GET',
  headers: {
    'X-CDD-Token': 'YOUR_API_KEY',
  },
});

const data = await response.json();
[
  {
    "id": 489978881,
    "name": "McKerrow Vault"
  }
]
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

Models

error_apikey

object

Whenever the given API key doesn't allow access to the given vault or the vault doesn't exist

codeinteger401
errorstringkey not authorized for access to this vault
Example
{
  "code": 401,
  "error": "key not authorized for access to this vault"
}

vault_id

integer

Numeric identifier of the vault

integer
Example
0

field

object
data_type_namestring
idinteger
namestring
overwritableboolean
required_group_numberinteger
typestring
unique_valueboolean
Example
{
  "data_type_name": "string",
  "id": 0,
  "name": "string",
  "overwritable": true,
  "required_group_number": 0,
  "type": "string",
  "unique_value": true
}

fields

object
batchArray<object>
Show child attributes
data_type_namestring
idinteger
namestring
overwritableboolean
required_group_numberinteger
typestring
unique_valueboolean
internalArray<object>
Show child attributes
data_type_namestring
idinteger
namestring
overwritableboolean
required_group_numberinteger
typestring
unique_valueboolean
moleculeArray<object>
Show child attributes
data_type_namestring
idinteger
namestring
overwritableboolean
required_group_numberinteger
typestring
unique_valueboolean
protocolArray<object>
Show child attributes
data_type_namestring
idinteger
namestring
overwritableboolean
required_group_numberinteger
typestring
unique_valueboolean
Example
{
  "batch": [
    {
      "data_type_name": "string",
      "id": 0,
      "name": "string",
      "overwritable": true,
      "required_group_number": 0,
      "type": "string",
      "unique_value": true
    }
  ],
  "internal": [
    {
      "data_type_name": "string",
      "id": 0,
      "name": "string",
      "overwritable": true,
      "required_group_number": 0,
      "type": "string",
      "unique_value": true
    }
  ],
  "molecule": [
    {
      "data_type_name": "string",
      "id": 0,
      "name": "string",
      "overwritable": true,
      "required_group_number": 0,
      "type": "string",
      "unique_value": true
    }
  ],
  "protocol": [
    {
      "data_type_name": "string",
      "id": 0,
      "name": "string",
      "overwritable": true,
      "required_group_number": 0,
      "type": "string",
      "unique_value": true
    }
  ]
}

pick_list_value_object

object

A pick list value belonging to a vault field definition.

created_atstring<date-time>required
hiddenbooleanrequired

Whether the value is hidden from users.

idintegerrequired
modified_atstring<date-time>required
valuestringrequired
Example
{
  "created_at": "2024-01-15T09:30:00Z",
  "hidden": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "value": "string"
}

pick_list_value_write

object

Attributes for creating or updating a pick list value.

hiddenbooleanfalse

Whether the value is hidden from users.

valuestringrequired
Example
{
  "value": "blue",
  "hidden": false
}

error

object

A general error response containing an error message and HTTP status code

codeinteger

HTTP status code

errorstring

Human-readable error message

Example
{
  "code": 404,
  "error": "Resource not found"
}

batch_move_job

object
batchintegerrequired

The ID of the batch to move

classstringrequired

The class of the job

created_atstring<date-time>required

The creation time of the batch move job

fail_on_molecule_deletionbooleanrequired

Whether to fail if moving the batch would trigger the removal of the originating molecule

idintegerrequired

The ID of the batch move job

modified_atstring<date-time>required

The modification time of the batch move job

moleculeintegerrequired

The ID of the molecule to move the batch to

namestring

The new name given to the batch. Only present when a name was supplied at creation (allowed only for vaults without a registration system).

queued_job_positioninteger

Position of the job in the processing queue. Only present while the job is queued.

requested_byintegerrequired

The ID of the user who requested the batch move job

statusstringrequestedqueuedprocessingsuccessfailurecanceledrequired

The status of the batch move job. A job starts as requested and transitions through the queue until it reaches a terminal state (success, failure, or canceled).

status_messagestring

Human-readable description of the job's current status.

Example
{
  "batch": 0,
  "class": "batch move job",
  "created_at": "2024-01-15T09:30:00Z",
  "fail_on_molecule_deletion": true,
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule": 0,
  "name": "string",
  "queued_job_position": 0,
  "requested_by": 0,
  "status": "requested",
  "status_message": "string"
}

batch_move_job_create

object

Parameters for creating a batch move job, which moves a batch to a different molecule in the same vault.

batchintegerrequired

The ID of the batch to move.

fail_on_molecule_deletionbooleantrue

Fail the job if moving the batch would trigger removal of the originating molecule. Defaults to true.

moleculeintegerrequired

The ID of the molecule to move the batch to.

namestring

A new name for the batch. Optional, and only allowed for vaults without a registration system.

Example
{
  "batch": 618771089,
  "molecule": 1,
  "fail_on_molecule_deletion": true
}

batch_create

object
batch_fieldsobject

Only in registration vaults

Each vault has its own settings on the minimum information required to create a new Batch (for a Vault Administrator, see Settings > Vault > Batch Fields, to change which Batch fields are required).

{: , ... }

moleculeobject | object | object
namestring
projectsArray<integer | string>

An array of project ids or names

Show child attributes
One of
integer
string
salt_namestring

A two-letter code or Salt vendor string as listed in the All Available Salts table (https://app.collaborativedrug.com/support/salts). The salt is determined automatically when the salt is included in the molecular structure.

solvent_of_crystallization_namestring

Name of the solvent of crystallization. List available at https://support.collaborativedrug.com/hc/en-us/articles/214359563-Salts-and-solvent-of-crystallization#solvents_of_crystallization

stoichiometryobject

Only in registration vaults

Show child attributes
core_countinteger
salt_countinteger
solvent_of_crystallization_countinteger
Example
{
  "batch_fields": {},
  "molecule": {
    "cxsmiles": "string",
    "duplicate_resolution": "first",
    "id": 0,
    "name": "string",
    "registration_type": "CHEMICAL_STRUCTURE",
    "smiles": "string",
    "structure": "string"
  },
  "name": "Batch 1",
  "projects": [
    0
  ],
  "salt_name": "string",
  "solvent_of_crystallization_name": "string",
  "stoichiometry": {
    "core_count": 0,
    "salt_count": 0,
    "solvent_of_crystallization_count": 0
  }
}

project_id_name

object
idinteger
namestring
Example
{
  "id": 1,
  "name": "Project 1"
}

batch

object
batch_fieldsobject
classstring
created_atstring<date>
formula_weightnumber
idinteger
modified_atstring<date>
moleculeobject
Show child attributes
classstring
created_atstring<date-time>
idinteger
modified_atstring<date-time>
namestring
ownerstring
projectsArray<object>
Show child attributes
idinteger
namestring
registration_typestring
synonymsArray<string>
molecule_batch_identifierstring
namestring
ownerstring
projectsArray<object>
Show child attributes
idinteger
namestring
salt_namestring
solvent_of_crystallization_namestring
stoichiometryobject
Show child attributes
core_countinteger
salt_countinteger
solvent_of_crystallization_countinteger
Example
{
  "batch_fields": {},
  "class": "batch",
  "created_at": "2024-01-15",
  "formula_weight": 0,
  "id": 42,
  "modified_at": "2024-01-15",
  "molecule": {
    "class": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "id": 0,
    "modified_at": "2024-01-15T09:30:00Z",
    "name": "string",
    "owner": "string",
    "projects": [
      {
        "id": 1,
        "name": "Project 1"
      }
    ],
    "registration_type": "string",
    "synonyms": [
      "string"
    ]
  },
  "molecule_batch_identifier": "DEMO-1000211-001",
  "name": "Batch 1",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "salt_name": "string",
  "solvent_of_crystallization_name": "string",
  "stoichiometry": {
    "core_count": 0,
    "salt_count": 0,
    "solvent_of_crystallization_count": 0
  }
}

date

string

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

string<date>
Example
"2024-01-15"

protocol_criterion

object

A single protocol-based filter, used in the protocol_criteria array to restrict results to molecules/batches that have (or lack) particular protocol readout data. Combine multiple criteria with the junction field.

protocol_idinteger

Id of the protocol to filter on (provide this or data_set_id).

data_set_idinteger

Id of the data set to filter on (provide this or protocol_id).

run_criterionstringanyrecentrun_daterun_id

Which runs to consider.

run_idinteger

Run id to match (when run_criterion is run_id).

run_afterstring<date>

Include runs on/after this date (when run_criterion is run_date).

run_beforestring<date>

Include runs on/before this date (when run_criterion is run_date).

since_days_agointeger

Number of days back to include (when run_criterion is recent).

readout_definition_idinteger

Id of the readout definition to filter on.

operatorstring=!=<>≤≥containsdoes not containfrom

Comparison operator applied to readout_value.

readout_valuestring

Value to compare the readout against.

readout_value_maximumstring

Upper bound of a range (when operator is from).

calculation_error_typestring

Filter by calculation error type.

criterion_typestringdata set or protocolrun dateprotocol field

The kind of protocol criterion.

fieldstring

Protocol field name (when criterion_type is protocol field).

querystring

Protocol field search value (when criterion_type is protocol field).

protocol_condition_idsArray<integer>

Restrict to these protocol condition ids.

negatedbooleanfalse

If true, exclude rather than include matches.

junctionstringANDORAND

How to combine this criterion with the previous one (ignored for the first criterion).

Example
{
  "protocol_id": 0,
  "data_set_id": 0,
  "run_criterion": "any",
  "run_id": 0,
  "run_after": "2024-01-15",
  "run_before": "2024-01-15",
  "since_days_ago": 0,
  "readout_definition_id": 0,
  "operator": "=",
  "readout_value": "string",
  "readout_value_maximum": "string",
  "calculation_error_type": "string",
  "criterion_type": "data set or protocol",
  "field": "string",
  "query": "string",
  "protocol_condition_ids": [
    0
  ],
  "negated": false,
  "junction": "AND"
}

structure_criterion

object

A structure-property filter object. Each property is filtered by an optional _minimum and/or _maximum bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same <property>_minimum / <property>_maximum convention.

heavy_atom_count_minimuminteger
heavy_atom_count_maximuminteger
cd_molweight_minimumnumber
cd_molweight_maximumnumber
exact_mass_minimumnumber
exact_mass_maximumnumber
log_p_minimumnumber
log_p_maximumnumber
log_d_minimumnumber
log_d_maximumnumber
log_s_minimumnumber
log_s_maximumnumber
num_aromatic_rings_minimuminteger
num_aromatic_rings_maximuminteger
num_h_bond_acceptors_minimuminteger
num_h_bond_acceptors_maximuminteger
num_h_bond_donors_minimuminteger
num_h_bond_donors_maximuminteger
num_rotatable_bonds_minimuminteger
num_rotatable_bonds_maximuminteger
num_rule_of_5_violations_minimuminteger
num_rule_of_5_violations_maximuminteger
topological_polar_surface_area_minimumnumber
topological_polar_surface_area_maximumnumber
Example
{
  "heavy_atom_count_minimum": 0,
  "heavy_atom_count_maximum": 0,
  "cd_molweight_minimum": 0,
  "cd_molweight_maximum": 0,
  "exact_mass_minimum": 0,
  "exact_mass_maximum": 0,
  "log_p_minimum": 0,
  "log_p_maximum": 0,
  "log_d_minimum": 0,
  "log_d_maximum": 0,
  "log_s_minimum": 0,
  "log_s_maximum": 0,
  "num_aromatic_rings_minimum": 0,
  "num_aromatic_rings_maximum": 0,
  "num_h_bond_acceptors_minimum": 0,
  "num_h_bond_acceptors_maximum": 0,
  "num_h_bond_donors_minimum": 0,
  "num_h_bond_donors_maximum": 0,
  "num_rotatable_bonds_minimum": 0,
  "num_rotatable_bonds_maximum": 0,
  "num_rule_of_5_violations_minimum": 0,
  "num_rule_of_5_violations_maximum": 0,
  "topological_polar_surface_area_minimum": 0,
  "topological_polar_surface_area_maximum": 0
}

batch_query

object
asyncboolean

If true, do an asynchronous export. Use for large data sets.

batch_fieldsArray<string>

Array of Batch field names to include in the resulting JSON. Defaults to all available fields.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

collection_criteriaArray<object>

Array of collection criteria objects. Filters results to only include batches whose molecules match the collection criteria, with support for AND/OR/XOR junctions and exclusion (NOT IN) logic.

Show child attributes
collection_idintegerrequired

The ID of the collection to filter by.

junctionstringANDORXORAND

How to combine this criterion with the previous one. The first criterion's junction is ignored. Defaults to "AND".

not_inbooleanfalse

If true, excludes batches whose molecules belong to this collection instead of including them. Defaults to false.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

data_setsArray<integer>

Array of public dataset ids. Defaults to all data sets.

fields_searchArray<object | object | object>

Array of Batch field names & values. Used to filter Batches returned based on query values

Show child attributes
One of
namestring

Name of the field to search

text_valuestring

Text value to search for

namestring

Name of the field to search

number_valuenumber

Number value to search for

date_valuestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

namestring

Name of the field to search

include_original_structuresbooleanfalse

If true, include the original structure in the response. This is independent of no_structures.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_batch_identifierstring

A Molecule-Batch ID used to query the Vault. Use this parameter to limit the number of Molecule UDF Fields to return

molecule_created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_fieldsArray<string>

Array of Molecule field names to include in the resulting JSON. Defaults to all available fields.

no_structuresbooleanfalse

If true, omit structure representations for a smaller and faster response.

offsetinteger
only_idsbooleanfalse

If true, only return the ids of the molecules in the batch.

only_molecule_idsbooleanfalse

If true, the full Batch details are still returned but the Molecule-level information is left out of the JSON results. (Only the IDs of the Molecules are still included.)

page_sizeinteger50

Requested page size (maximum value 1000).

projectsArray<integer>

Array of project ids. Defaults to all available projects.

protocol_criteriaArray<object>

Array of protocol-based filters restricting results to batches with (or without) matching protocol readout data. Criteria are combined using each entry's junction.

Show child attributes
protocol_idinteger

Id of the protocol to filter on (provide this or data_set_id).

data_set_idinteger

Id of the data set to filter on (provide this or protocol_id).

run_criterionstringanyrecentrun_daterun_id

Which runs to consider.

run_idinteger

Run id to match (when run_criterion is run_id).

run_afterstring<date>

Include runs on/after this date (when run_criterion is run_date).

run_beforestring<date>

Include runs on/before this date (when run_criterion is run_date).

since_days_agointeger

Number of days back to include (when run_criterion is recent).

readout_definition_idinteger

Id of the readout definition to filter on.

operatorstring=!=<>≤≥containsdoes not containfrom

Comparison operator applied to readout_value.

readout_valuestring

Value to compare the readout against.

readout_value_maximumstring

Upper bound of a range (when operator is from).

calculation_error_typestring

Filter by calculation error type.

criterion_typestringdata set or protocolrun dateprotocol field

The kind of protocol criterion.

fieldstring

Protocol field name (when criterion_type is protocol field).

querystring

Protocol field search value (when criterion_type is protocol field).

protocol_condition_idsArray<integer>

Restrict to these protocol condition ids.

negatedbooleanfalse

If true, exclude rather than include matches.

junctionstringANDORAND

How to combine this criterion with the previous one (ignored for the first criterion).

structure_criterionobject

A structure-property filter object. Each property is filtered by an optional _minimum and/or _maximum bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same <property>_minimum / <property>_maximum convention.

Show child attributes
heavy_atom_count_minimuminteger
heavy_atom_count_maximuminteger
cd_molweight_minimumnumber
cd_molweight_maximumnumber
exact_mass_minimumnumber
exact_mass_maximumnumber
log_p_minimumnumber
log_p_maximumnumber
log_d_minimumnumber
log_d_maximumnumber
log_s_minimumnumber
log_s_maximumnumber
num_aromatic_rings_minimuminteger
num_aromatic_rings_maximuminteger
num_h_bond_acceptors_minimuminteger
num_h_bond_acceptors_maximuminteger
num_h_bond_donors_minimuminteger
num_h_bond_donors_maximuminteger
num_rotatable_bonds_minimuminteger
num_rotatable_bonds_maximuminteger
num_rule_of_5_violations_minimuminteger
num_rule_of_5_violations_maximuminteger
topological_polar_surface_area_minimumnumber
topological_polar_surface_area_maximumnumber
Example
{
  "async": true,
  "batch_fields": [
    "string"
  ],
  "created_after": "2024-01-15",
  "collection_criteria": [
    {
      "collection_id": 0,
      "junction": "AND",
      "not_in": false
    }
  ],
  "created_before": "2024-01-15",
  "data_sets": [
    0
  ],
  "fields_search": [
    {
      "name": "string",
      "text_value": "string"
    }
  ],
  "include_original_structures": false,
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "molecule_batch_identifier": "string",
  "molecule_created_after": "2024-01-15",
  "molecule_created_before": "2024-01-15",
  "molecule_fields": [
    "string"
  ],
  "no_structures": false,
  "offset": 0,
  "only_ids": false,
  "only_molecule_ids": false,
  "page_size": 50,
  "projects": [
    0
  ],
  "protocol_criteria": [
    {
      "protocol_id": 0,
      "data_set_id": 0,
      "run_criterion": "any",
      "run_id": 0,
      "run_after": "2024-01-15",
      "run_before": "2024-01-15",
      "since_days_ago": 0,
      "readout_definition_id": 0,
      "operator": "=",
      "readout_value": "string",
      "readout_value_maximum": "string",
      "calculation_error_type": "string",
      "criterion_type": "data set or protocol",
      "field": "string",
      "query": "string",
      "protocol_condition_ids": [
        0
      ],
      "negated": false,
      "junction": "AND"
    }
  ],
  "structure_criterion": {
    "heavy_atom_count_minimum": 0,
    "heavy_atom_count_maximum": 0,
    "cd_molweight_minimum": 0,
    "cd_molweight_maximum": 0,
    "exact_mass_minimum": 0,
    "exact_mass_maximum": 0,
    "log_p_minimum": 0,
    "log_p_maximum": 0,
    "log_d_minimum": 0,
    "log_d_maximum": 0,
    "log_s_minimum": 0,
    "log_s_maximum": 0,
    "num_aromatic_rings_minimum": 0,
    "num_aromatic_rings_maximum": 0,
    "num_h_bond_acceptors_minimum": 0,
    "num_h_bond_acceptors_maximum": 0,
    "num_h_bond_donors_minimum": 0,
    "num_h_bond_donors_maximum": 0,
    "num_rotatable_bonds_minimum": 0,
    "num_rotatable_bonds_maximum": 0,
    "num_rule_of_5_violations_minimum": 0,
    "num_rule_of_5_violations_maximum": 0,
    "topological_polar_surface_area_minimum": 0,
    "topological_polar_surface_area_maximum": 0
  }
}

batch_query_only_id

object
batchesArray<integer>

Comma separated list of batch ids. Cannot be used with other parameters

Example
{
  "batches": [
    0
  ]
}

collection_create

object
classstringuser collection
created_atstring<date>
modified_atstring<date>
moleculesArray<integer>

The list of molecules in the collection.

namestring
ownerstring
Example
{
  "class": "user collection",
  "created_at": "2024-01-15",
  "modified_at": "2024-01-15",
  "molecules": [
    0
  ],
  "name": "Rare compounds",
  "owner": "Jacob Bloom"
}

collection

object
idinteger

Id is also valid during creation/update but must match the id in the URL

classstringuser collection
created_atstring<date>
modified_atstring<date>
moleculesArray<integer>

The list of molecules in the collection.

namestring
ownerstring
Example
{
  "id": 42,
  "class": "user collection",
  "created_at": "2024-01-15",
  "modified_at": "2024-01-15",
  "molecules": [
    0
  ],
  "name": "Rare compounds",
  "owner": "Jacob Bloom"
}

collections_query_common

object
asyncboolean

If true, do an asynchronous export. Use for large data sets. You will get an export id that you can use with the async export function.

include_molecule_idsboolean

If true, include the ids of the molecules in the collection.

offsetinteger

The offset of the first collection in the result set. The offset is 0-based. That is, the first collection in the result set has offset 0.

only_idsboolean

If true, only return the ids of the matching collections.

page_sizeinteger50

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 call that also uses the async=true parameter will be ignored. The async call will return all valid data once executed.

projectsArray<integer>

Array of project ids. Defaults to all available projects.

Example
{
  "async": true,
  "include_molecule_ids": true,
  "offset": 0,
  "only_ids": true,
  "page_size": 50,
  "projects": [
    0
  ]
}

collections_query

object
One of
collectionsArray<integer>

The list of collections id to return

asyncboolean

If true, do an asynchronous export. Use for large data sets. You will get an export id that you can use with the async export function.

include_molecule_idsboolean

If true, include the ids of the molecules in the collection.

offsetinteger

The offset of the first collection in the result set. The offset is 0-based. That is, the first collection in the result set has offset 0.

only_idsboolean

If true, only return the ids of the matching collections.

page_sizeinteger50

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 call that also uses the async=true parameter will be ignored. The async call will return all valid data once executed.

projectsArray<integer>

Array of project ids. Defaults to all available projects.

asyncboolean

If true, do an asynchronous export. Use for large data sets. You will get an export id that you can use with the async export function.

include_molecule_idsboolean

If true, include the ids of the molecules in the collection.

offsetinteger

The offset of the first collection in the result set. The offset is 0-based. That is, the first collection in the result set has offset 0.

only_idsboolean

If true, only return the ids of the matching collections.

page_sizeinteger50

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 call that also uses the async=true parameter will be ignored. The async call will return all valid data once executed.

projectsArray<integer>

Array of project ids. Defaults to all available projects.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

typestringuser_collectionvault_collection

The type of collection user collections are private, vault collections are shared with project members.

Example
{
  "collections": [
    0
  ],
  "async": true,
  "include_molecule_ids": true,
  "offset": 0,
  "only_ids": true,
  "page_size": 50,
  "projects": [
    0
  ]
}

collection_update

object
moleculesArray<integer>

The list of molecules to add to the collection. Note that you cannot remove molecules from a collection. You have to recreate the collection without the molecule.

Example
{
  "molecules": [
    0
  ]
}

control_layout

object

A control layout describes which wells of a protocol or run are controls (positive, negative, or a reference molecule).

classstringrequired
control_wellsArray<object>required

The control wells defined by this layout.

Show child attributes
colinteger

Zero-based column index of the well.

control_statestring+-#

The control type of the well: + (positive control), - (negative control), # (reference molecule), or an empty string (not a control).

rowinteger

Zero-based row index of the well.

created_atstring<date-time>
idintegerrequired
modified_atstring<date-time>
plate_idinteger

Id of the plate this layout applies to, when plate-specific.

protocolinteger

Id of the protocol the layout belongs to (always present for run-scoped layouts as the run's protocol).

runinteger

Id of the run the layout belongs to, when run-scoped.

sizeintegerrequired

Number of wells in the layout (plate size).

Example
{
  "class": "control layout",
  "control_wells": [
    {
      "col": 0,
      "control_state": "+",
      "row": 0
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "plate_id": 0,
  "protocol": 0,
  "run": 0,
  "size": 0
}

control_layout_create

object

Attributes for creating a control layout. Specify the target with exactly one of protocol or run, and the layout dimensions with exactly one of size or plate.

One of
any
any
One of
any
any
Example
{
  "protocol": 321,
  "size": 96,
  "control_wells": [
    {
      "row": 0,
      "col": 0,
      "control_state": "+"
    },
    {
      "pos": "H12",
      "control_state": "-"
    }
  ]
}

data_set

object
idinteger

The id of the data_set

namestring

The name of the data_set

Example
{
  "id": 0,
  "name": "string"
}

eln_create

object

Attributes used to create or update an ELN entry. The same body is accepted by POST /eln/entries (create) and PUT /eln/entries/{id} (update); on update, only the supplied fields are changed.

append_to_bodyArray<object | object | object>

Ordered list of content nodes appended to the body of the entry. Each node has a type; the supported types are:

  • text — a paragraph of text. Provide text (defaults to an empty string).
  • link — a hyperlink. Provide url (required; must be a valid http/https/ftp/mailto URL) and an optional label for the display text. Use this to link to a batch, molecule, protocol, or any external resource.
  • file — an attachment that was already uploaded. Provide file, the id of an accessible uploaded file. (Files can also be attached to an existing entry with the POST /files API.)
Show child attributes
One of
textstring

Text content (defaults to an empty string).

typestringrequired
labelstring

Display text for the link (optional).

typestringrequired
urlstringrequired

Target URL (must be a valid http/https/ftp/mailto URL).

fileintegerrequired

Id of an already-uploaded, accessible file.

typestringrequired
eln_fieldsobject

The ELN fields of the entry

projectinteger | string
titlestring

The title of the entry

Example
{
  "title": "Synthesis of compound 42",
  "project": 7,
  "eln_fields": {
    "Reaction type": "Suzuki coupling"
  },
  "append_to_body": [
    {
      "type": "text",
      "text": "Procedure followed the standard protocol."
    },
    {
      "type": "link",
      "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345",
      "label": "Starting material CDD-12345"
    },
    {
      "type": "file",
      "file": 98765
    }
  ]
}

eln_entry_status

object
created_atstring

Timestamp in ISO-8601 UTC

idinteger

The id of the entry

statusstringnewopensubmittedfinalized
updated_atstring

Timestamp in ISO-8601 UTC

Example
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 42,
  "status": "new",
  "updated_at": "2024-01-02T03:04:05.000Z"
}

eln_entries_query

object
asyncbooleanfalse

Perform an asynchronous export If true, do an asynchronous export (see Async Export) Use if you wish to retrieve a zip file containing exports of the actual ELN entries along with any files attached within the ELN entries. Note: any page_size parameter used in the call call that also uses the async=true parameter will be ignored. The call will return all matching entries as a zip file with their content.

authorArray<string>

List of ELN author IDs. We do not match by names, you need to use the users call.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

eln_entriesArray<string>

List of ELN entry IDs

finalized_date_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

finalized_date_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

offsetinteger0

Index of the first object actually returned

only_idsbooleanfalse

Return only ELN Entry IDs

only_summarybooleanfalse

Return only a csv summary file, async is still recommended

page_sizeinteger50

Maximum number of objects to return in this call This parameter is ignored is async is true.

projectsArray<string>

List of project IDs

statusstringopensubmittedfinalized

Status of ELN entries (open, submitted, finalized)

submitted_date_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

submitted_date_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

Example
{
  "async": false,
  "author": [
    "string"
  ],
  "created_after": "2024-01-15",
  "created_before": "2024-01-15",
  "eln_entries": [
    "string"
  ],
  "finalized_date_after": "2024-01-15",
  "finalized_date_before": "2024-01-15",
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "offset": 0,
  "only_ids": false,
  "only_summary": false,
  "page_size": 50,
  "projects": [
    "string"
  ],
  "status": "open",
  "submitted_date_after": "2024-01-15",
  "submitted_date_before": "2024-01-15"
}

eln_status_action

object

A witnessing/status action to perform on an ELN entry. The set of valid status_action values depends on whether ELN witnessing is enabled for the vault:

  • Witnessing enabled: submit (requires witness), approve, reject (requires reason), cancel, reopen (requires reason), discard.
  • Witnessing disabled: finalize, reopen (requires reason), discard.
reasonstring

Reason for the action (required for reject and reopen).

status_actionstringsubmitapproverejectcancelreopenfinalizediscardrequired

The action to perform.

witnessinteger

Id of the witnessing user (required for submit).

Example
{
  "status_action": "submit",
  "witness": 6021
}

export

object
created_atstring

Timestamp in ISO-8601 UTC

idinteger
modified_atstring

Timestamp in ISO-8601 UTC

queued_job_positioninteger

Position of the export's job in the processing queue. Only present while the export is in the new state.

statusstringnewstartedfinisheddownloadedfailedcanceled

The export's state. While polling progress it moves new -> started -> finished; any value other than these three during polling means something went wrong. canceled is returned after a successful cancel.

Example
{
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "queued_job_position": 0,
  "status": "new"
}

exports

array
Array<object>
Show child attributes
created_atstring

Timestamp in ISO-8601 UTC

idinteger
modified_atstring

Timestamp in ISO-8601 UTC

queued_job_positioninteger

Position of the export's job in the processing queue. Only present while the export is in the new state.

statusstringnewstartedfinisheddownloadedfailedcanceled

The export's state. While polling progress it moves new -> started -> finished; any value other than these three during polling means something went wrong. canceled is returned after a successful cancel.

Example
[
  {
    "created_at": "2024-01-02T03:04:05.000Z",
    "id": 1,
    "modified_at": "2024-01-02T03:04:05.000Z",
    "queued_job_position": 0,
    "status": "new"
  }
]

file

object
character_setstring
classstring
contentsstring

Base64 encoded contents of the file

idinteger
mime_typeobject
Show child attributes
hashinteger
stringstring
symbolstring
synonymsArray<string>
namestring
Example
{
  "character_set": "US-ASCII",
  "class": "uploaded file",
  "contents": "VGhpcyBpcyBhIGZpbGUK",
  "id": 1069448031,
  "mime_type": {
    "hash": -1147906696977776400,
    "string": "text/plain",
    "symbol": "text",
    "synonyms": [
      "string"
    ]
  },
  "name": "tmp.txt"
}

import_parser

object

An import parser (plate block template) describing how a structured data file should be parsed during import.

created_atstring<date-time>required
idintegerrequired
modified_atstring<date-time>required
namestringrequired

Name of the import parser.

ownerstringrequired

Full name of the user who owns the import parser.

template_jsonobject

The parser configuration (arbitrary JSON object). Only returned by the show endpoint, not in the index listing.

Example
{
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "owner": "string",
  "template_json": {}
}

inventory_location

object
classstringinventory location
created_atstring<date-time>
filled_position_countinteger
idinteger
modified_atstring<date-time>
num_columnsinteger
num_rowsinteger
parent_idinteger | null
position_limitinteger
valuestring
Example
{
  "class": "inventory location",
  "created_at": "2023-10-30T18:25:41.771Z",
  "filled_position_count": 0,
  "id": 42,
  "modified_at": "2023-10-30T18:25:41.771Z",
  "num_columns": 0,
  "num_rows": 0,
  "parent_id": 130,
  "position_limit": 0,
  "value": "Gotham"
}

inventory_sample_object

object

An inventory sample: a tracked physical amount of a batch, with its current amount, location, custom fields, and event history.

batchintegerrequired

Id of the batch this sample is an inventory of.

batch_namestringrequired

Name of the associated batch.

classstringrequired
created_atstring<date-time>required
created_by_user_full_namestring

Full name of the user who created the sample.

current_amountnumberrequired

Current amount remaining for the sample.

depletedbooleanrequired

Whether the sample has been depleted.

fieldsobject

Custom inventory sample field values, keyed by field name.

idintegerrequired
inventory_eventsArray<object>

The event history (additions, withdrawals, etc.) for the sample.

Show child attributes
classstring
created_atstring<date-time>
fieldsobject

Custom event field values, keyed by field name.

idinteger
modified_atstring<date-time>
updated_by_user_full_namestring
locationstring

Human-readable display path of the sample's location.

modified_atstring<date-time>required
namestring

Name (identifier) of the sample.

unitsstringrequired

Units the sample amount is expressed in.

updated_by_user_full_namestring

Full name of the user who last modified the sample.

Example
{
  "batch": 0,
  "batch_name": "string",
  "class": "inventory sample",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by_user_full_name": "string",
  "current_amount": 0,
  "depleted": true,
  "fields": {},
  "id": 0,
  "inventory_events": [
    {
      "class": "inventory event",
      "created_at": "2024-01-15T09:30:00Z",
      "fields": {},
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "updated_by_user_full_name": "string"
    }
  ],
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "units": "string",
  "updated_by_user_full_name": "string"
}

inventory_sample_create

object

Attributes for creating an inventory sample.

batch_idintegerrequired

Id of the batch this sample is an inventory of.

fieldsobject

Custom inventory sample field values, keyed by field name.

inventory_eventsArray<object>

Initial inventory event(s) for the sample. At most one event may be supplied per request.

Show child attributes
fieldsobject

Custom event field values, keyed by field name.

unitsstringgkgmgµgngmLLµLMmMµMnMmolmmolµmolnmolpmolcountrequired

Units the sample amount is expressed in. One of: g, kg, mg, µg, ng, mL, L, µL, M, mM, µM, nM, mol, mmol, µmol, nmol, pmol, count.

Example
{
  "batch_id": 456,
  "units": "mg",
  "fields": {
    "Supplier": "Acme Chemicals"
  },
  "inventory_events": [
    {
      "fields": {
        "Credit": 100
      }
    }
  ]
}

inventory_sample_update

object

Attributes for updating an inventory sample. Only supplied fields are changed.

depletedboolean

Mark the sample as depleted (true) or clear the depleted flag (false).

fieldsobject

Custom inventory sample field values, keyed by field name.

inventory_eventsArray<object>

An inventory event to add or update. At most one event may be supplied per request. Include the event id to update an existing event; omit it to create a new one.

Show child attributes
fieldsobject

Custom event field values, keyed by field name.

idinteger

Id of the event to update. Omit to create a new event.

unitsstringgkgmgµgngmLLµLMmMµMnMmolmmolµmolnmolpmolcount

Units the sample amount is expressed in.

Example
{
  "depleted": false,
  "fields": {
    "Supplier": "New Supplier Inc"
  },
  "inventory_events": [
    {
      "id": 54321,
      "fields": {
        "Debit": 10
      }
    }
  ]
}

mapping_template_simple

object
created_atstring<date-time>
idinteger
modified_atstring<date-time>
namestring
ownerstring
Example
{
  "created_at": "2021-12-23T23:59:22.000Z",
  "id": 22704,
  "modified_at": "2021-12-23T23:59:22.000Z",
  "name": "Protac Registration",
  "owner": "Charlie Weatherall"
}

mapping_template_details

object
created_atstring<date-time>
fileobject
Show child attributes
file_namestring
valueinteger
header_mappingsArray<object>
Show child attributes
definitionobject
Show child attributes
data_type_namestring
idinteger
namestring
pick_list_valuesArray<string>
protocol_namestring
typestring
headerobject
Show child attributes
idinteger
namestring
run_groupinginteger
idinteger
modified_atstring<date-time>
namestring
ownerstring
Example
{
  "created_at": "2021-12-23T23:59:22.000Z",
  "file": {
    "file_name": "string",
    "value": 0
  },
  "header_mappings": [
    {
      "definition": {
        "data_type_name": "string",
        "id": 0,
        "name": "string",
        "pick_list_values": [
          "string"
        ],
        "protocol_name": "string",
        "type": "string"
      },
      "header": {
        "id": 0,
        "name": "string"
      },
      "run_grouping": 0
    }
  ],
  "id": 22704,
  "modified_at": "2021-12-23T23:59:22.000Z",
  "name": "Protac Registration",
  "owner": "Charlie Weatherall"
}

molecule_create

object

Attributes for creating a molecule. Creating molecules directly is only allowed in vaults that are NOT using a registration system; in registration vaults, register molecules by creating batches instead.

collectionsArray<integer | string>

Collections to add the molecule to (ids or names).

Show child attributes
One of
integer
string
duplicate_resolutionstringnewprompt

How to handle a structure that duplicates an existing molecule. new registers a new molecule; prompt fails with the duplicate details so the caller can decide. Must match tautomer_resolution if both are given.

molecule_fieldsobject

Custom molecule field values, keyed by field name. The legacy alias udfs is also accepted.

namestringrequired

Name of the molecule.

projectsArray<integer | string>

Projects the molecule belongs to (ids or names).

Show child attributes
One of
integer
string
registration_forminteger | string

The registration form to use (id or name). Defaults to the vault default.

registration_typestring

The kind of entity being registered (e.g. CHEMICAL_STRUCTURE).

structurestring

The chemical structure, as SMILES or a molfile. For amino-acid, nucleotide, or mixture molecules use the corresponding structure representation accepted for that registration type.

synonymsArray<string>

Alternative names for the molecule.

tautomer_resolutionstringnewprompt

How to handle a structure that is a tautomer of an existing molecule.

Example
{
  "name": "My compound",
  "structure": "CC(=O)Oc1ccccc1C(=O)O",
  "synonyms": [
    "Aspirin"
  ],
  "projects": [
    12
  ],
  "molecule_fields": {
    "Solubility": "High"
  }
}

molecule

object
batchesArray<object>

Array of batches belonging to this molecule

Show child attributes
batch_fieldsobject
classstring
created_atstring<date-time>
formula_weightnumber
idinteger
modified_atstring<date-time>
molecule_batch_identifierstring
namestring
ownerstring
projectsArray<object>
Show child attributes
idinteger
namestring
salt_namestring
solvent_of_crystallization_namestring
stoichiometryobject
Show child attributes
core_countinteger
salt_countinteger
solvent_of_crystallization_countinteger
classstring
created_atstring<date-time>
idinteger
modified_atstring<date-time>
molecule_fieldsobject
namestring
ownerstring
projectsArray<object>
Show child attributes
idinteger
namestring
registration_typestringchemical_structureamino_acidnucleotidemixtureother

The registration type of the molecule

smilesstring

SMILES representation of the molecule structure

synonymsArray<string>
Example
{
  "batches": [
    {
      "batch_fields": {},
      "class": "batch",
      "created_at": "2024-01-15T09:30:00Z",
      "formula_weight": 0,
      "id": 42,
      "modified_at": "2024-01-15T09:30:00Z",
      "molecule_batch_identifier": "DEMO-1000211-001",
      "name": "Batch 1",
      "owner": "Charlie Weatherall",
      "projects": [
        {
          "id": 1,
          "name": "Project 1"
        }
      ],
      "salt_name": "string",
      "solvent_of_crystallization_name": "string",
      "stoichiometry": {
        "core_count": 0,
        "salt_count": 0,
        "solvent_of_crystallization_count": 0
      }
    }
  ],
  "class": "molecule",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 1000211,
  "modified_at": "2024-01-15T09:30:00Z",
  "molecule_fields": {},
  "name": "Aspirin",
  "owner": "Charlie Weatherall",
  "projects": [
    {
      "id": 1,
      "name": "Project 1"
    }
  ],
  "registration_type": "chemical_structure",
  "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
  "synonyms": [
    "string"
  ]
}

molecule_query

object
asyncboolean

If true, do an asynchronous export. Use for large data sets.

batch_created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_field_after_datestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_field_after_namestring

Name of the batch date field to filter on (used with batch_field_after_date).

batch_field_before_datestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

batch_field_before_namestring

Name of the batch date field to filter on (used with batch_field_before_date).

batch_fieldsArray<string>

Array of Batch field names to include in the resulting JSON. Defaults to all available fields.

collection_criteriaArray<object>

Array of collection criteria objects. Filters results based on collection membership with support for AND/OR/XOR junctions and exclusion (NOT IN) logic.

Show child attributes
collection_idintegerrequired

The ID of the collection to filter by.

junctionstringANDORXORAND

How to combine this criterion with the previous one. The first criterion's junction is ignored. Defaults to "AND".

not_inbooleanfalse

If true, excludes molecules that belong to this collection instead of including them. Defaults to false.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

data_setsArray<integer>

Array of public dataset ids. Defaults to all data sets.

fields_searchArray<object | object | object>

Array of Molecule field names & values. Used to filter Molecules returned based on query values

Show child attributes
One of
namestring

Name of the field to search

text_valuestring

Text value to search for

namestring

Name of the field to search

number_valuenumber

Number value to search for

date_valuestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

namestring

Name of the field to search

include_original_structuresbooleanfalse

If true, include the original structure in the response. This is independent of no_structures.

inchikeystring

Filter molecules by InChIKey.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

molecule_fieldsArray<string>

Array of Molecule field names to include in the resulting JSON. Defaults to all available fields.

namesArray<string>

Array of molecule names or synonyms to search for.

no_structuresbooleanfalse

If true, omit structure representations for a smaller and faster response.

offsetinteger
only_batch_idsbooleanfalse

If true, the full Molecule details are still returned but the Batch-level information is left out of the JSON results. (Only the IDs of the Batches are still included.)

only_idsbooleanfalse

If true, only return the ids of the molecules.

page_sizeinteger50

Requested page size (maximum value 1000).

projectsArray<integer>

Array of project ids. Defaults to all available projects.

protocol_criteriaArray<object>

Array of protocol-based filters restricting results to molecules with (or without) matching protocol readout data. Criteria are combined using each entry's junction.

Show child attributes
protocol_idinteger

Id of the protocol to filter on (provide this or data_set_id).

data_set_idinteger

Id of the data set to filter on (provide this or protocol_id).

run_criterionstringanyrecentrun_daterun_id

Which runs to consider.

run_idinteger

Run id to match (when run_criterion is run_id).

run_afterstring<date>

Include runs on/after this date (when run_criterion is run_date).

run_beforestring<date>

Include runs on/before this date (when run_criterion is run_date).

since_days_agointeger

Number of days back to include (when run_criterion is recent).

readout_definition_idinteger

Id of the readout definition to filter on.

operatorstring=!=<>≤≥containsdoes not containfrom

Comparison operator applied to readout_value.

readout_valuestring

Value to compare the readout against.

readout_value_maximumstring

Upper bound of a range (when operator is from).

calculation_error_typestring

Filter by calculation error type.

criterion_typestringdata set or protocolrun dateprotocol field

The kind of protocol criterion.

fieldstring

Protocol field name (when criterion_type is protocol field).

querystring

Protocol field search value (when criterion_type is protocol field).

protocol_condition_idsArray<integer>

Restrict to these protocol condition ids.

negatedbooleanfalse

If true, exclude rather than include matches.

junctionstringANDORAND

How to combine this criterion with the previous one (ignored for the first criterion).

structurestring

A SMILES or MOL string to search for.

structure_criterionobject

A structure-property filter object. Each property is filtered by an optional _minimum and/or _maximum bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same <property>_minimum / <property>_maximum convention.

Show child attributes
heavy_atom_count_minimuminteger
heavy_atom_count_maximuminteger
cd_molweight_minimumnumber
cd_molweight_maximumnumber
exact_mass_minimumnumber
exact_mass_maximumnumber
log_p_minimumnumber
log_p_maximumnumber
log_d_minimumnumber
log_d_maximumnumber
log_s_minimumnumber
log_s_maximumnumber
num_aromatic_rings_minimuminteger
num_aromatic_rings_maximuminteger
num_h_bond_acceptors_minimuminteger
num_h_bond_acceptors_maximuminteger
num_h_bond_donors_minimuminteger
num_h_bond_donors_maximuminteger
num_rotatable_bonds_minimuminteger
num_rotatable_bonds_maximuminteger
num_rule_of_5_violations_minimuminteger
num_rule_of_5_violations_maximuminteger
topological_polar_surface_area_minimumnumber
topological_polar_surface_area_maximumnumber
structure_search_typestringexactsubstructuresimilarityexact_with_stereo

The type of structure search to perform. Options are 'exact', 'substructure', 'similarity', or 'exact_with_stereo'.

structure_similarity_thresholdnumber[0, 1]

Similarity threshold for similarity searches (0 to 1). Only used when structure_search_type is 'similarity'.

Example
{
  "async": true,
  "batch_created_after": "2024-01-15",
  "batch_created_before": "2024-01-15",
  "batch_field_after_date": "2024-01-15",
  "batch_field_after_name": "string",
  "batch_field_before_date": "2024-01-15",
  "batch_field_before_name": "string",
  "batch_fields": [
    "string"
  ],
  "collection_criteria": [
    {
      "collection_id": 0,
      "junction": "AND",
      "not_in": false
    }
  ],
  "created_after": "2024-01-15",
  "created_before": "2024-01-15",
  "data_sets": [
    0
  ],
  "fields_search": [
    {
      "name": "string",
      "text_value": "string"
    }
  ],
  "include_original_structures": false,
  "inchikey": "string",
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "molecule_fields": [
    "string"
  ],
  "names": [
    "string"
  ],
  "no_structures": false,
  "offset": 0,
  "only_batch_ids": false,
  "only_ids": false,
  "page_size": 50,
  "projects": [
    0
  ],
  "protocol_criteria": [
    {
      "protocol_id": 0,
      "data_set_id": 0,
      "run_criterion": "any",
      "run_id": 0,
      "run_after": "2024-01-15",
      "run_before": "2024-01-15",
      "since_days_ago": 0,
      "readout_definition_id": 0,
      "operator": "=",
      "readout_value": "string",
      "readout_value_maximum": "string",
      "calculation_error_type": "string",
      "criterion_type": "data set or protocol",
      "field": "string",
      "query": "string",
      "protocol_condition_ids": [
        0
      ],
      "negated": false,
      "junction": "AND"
    }
  ],
  "structure": "string",
  "structure_criterion": {
    "heavy_atom_count_minimum": 0,
    "heavy_atom_count_maximum": 0,
    "cd_molweight_minimum": 0,
    "cd_molweight_maximum": 0,
    "exact_mass_minimum": 0,
    "exact_mass_maximum": 0,
    "log_p_minimum": 0,
    "log_p_maximum": 0,
    "log_d_minimum": 0,
    "log_d_maximum": 0,
    "log_s_minimum": 0,
    "log_s_maximum": 0,
    "num_aromatic_rings_minimum": 0,
    "num_aromatic_rings_maximum": 0,
    "num_h_bond_acceptors_minimum": 0,
    "num_h_bond_acceptors_maximum": 0,
    "num_h_bond_donors_minimum": 0,
    "num_h_bond_donors_maximum": 0,
    "num_rotatable_bonds_minimum": 0,
    "num_rotatable_bonds_maximum": 0,
    "num_rule_of_5_violations_minimum": 0,
    "num_rule_of_5_violations_maximum": 0,
    "topological_polar_surface_area_minimum": 0,
    "topological_polar_surface_area_maximum": 0
  },
  "structure_search_type": "exact",
  "structure_similarity_threshold": 0
}

molecule_query_only_id

object
moleculesArray<integer>

Comma separated list of molecule ids. Cannot be used with other parameters

Example
{
  "molecules": [
    0
  ]
}

molecule_update

object

Attributes for updating a molecule. Only the supplied fields are changed. Array fields (synonyms, projects, collections) replace the existing values.

collectionsArray<integer | string>

Collections the molecule belongs to (ids or names). Replaces existing.

Show child attributes
One of
integer
string
molecule_fieldsobject

Custom molecule field values, keyed by field name. The legacy alias udfs is also accepted.

namestring

Name of the molecule.

projectsArray<integer | string>

Projects the molecule belongs to (ids or names). Replaces existing.

Show child attributes
One of
integer
string
structurestring

Updated chemical structure, as SMILES or a molfile.

synonymsArray<string>

Alternative names for the molecule. Replaces existing.

Example
{
  "name": "Renamed compound",
  "synonyms": [
    "Aspirin",
    "2-Acetoxybenzoic acid"
  ],
  "molecule_fields": {
    "Solubility": "Medium"
  }
}

plate_object

object

A plate of wells, optionally associated with batches/samples and run statistics.

classstringrequired
concentrationnumber
concentration_unit_labelstring

Units for concentration (e.g. "M").

created_atstring<date-time>
idintegerrequired
inventory_location_idinteger
locationstring

Free-text location of the plate.

modified_atstring<date-time>
namestringrequired
projectsArray<object>

Projects the plate belongs to.

Show child attributes
idinteger
namestring
statisticsArray<object>

Per-run plate statistics (Z'-factor, control means, etc.).

volumenumber
volume_unit_labelstring

Units for volume (e.g. "µL").

wellsArray<object>

The wells of the plate and their batch/sample assignments.

Show child attributes
batchinteger

Batch id in the well (if any).

colinteger

Zero-based column index.

rowinteger

Zero-based row index.

sampleinteger

Inventory sample id in the well (if any).

Example
{
  "class": "plate",
  "concentration": 0,
  "concentration_unit_label": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "inventory_location_id": 0,
  "location": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "projects": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "statistics": [
    {}
  ],
  "volume": 0,
  "volume_unit_label": "string",
  "wells": [
    {
      "batch": 0,
      "col": 0,
      "row": 0,
      "sample": 0
    }
  ]
}

plate_create_update

object

Attributes for creating or updating a plate. On create, name and projects are required. Supplying wells replaces the plate's wells.

concentrationnumber
concentration_unit_labelstring
inventory_locationinteger

Id of the inventory location for the plate.

locationstring
namestring
projectsArray<integer>

Project ids the plate belongs to.

volumenumber
volume_unit_labelstring
wellsArray<object>

Wells to populate. Each well identifies its position by row+col or pos.

Show child attributes
batchinteger

Batch id to place in the well.

colinteger
posstring

Well position in letter-number form (e.g. "A1"), as an alternative to row/col.

rowinteger
Example
{
  "name": "Plate 001",
  "projects": [
    12
  ],
  "location": "Freezer A",
  "wells": [
    {
      "row": 0,
      "col": 0,
      "batch": 456
    }
  ]
}

project_object

object

A project in the vault. The list (index) and create responses contain only id and name; the show and update responses additionally include description and members.

descriptionstring

Project description (present in show/update responses).

idintegerrequired
membersArray<object>

Project members and their permissions (present in show/update responses).

Show child attributes
can_edit_databoolean
can_manage_projectboolean
idinteger

User id.

namestringrequired
Example
{
  "description": "string",
  "id": 0,
  "members": [
    {
      "can_edit_data": true,
      "can_manage_project": true,
      "id": 0
    }
  ],
  "name": "string"
}

project_create_update_public

object

Attributes for creating or updating a project.

descriptionstring

Project description.

membersArray<object>

Project members. On update this replaces the existing membership list. If omitted on create, the current user is added as a member.

Show child attributes
can_edit_databooleanfalse
can_manage_projectbooleanfalse
user_idintegerrequired

Id of an existing vault user.

namestringrequired

Project name (must be unique within the vault).

Example
{
  "name": "My project",
  "description": "Compounds from the 2026 screening campaign",
  "members": [
    {
      "user_id": 6021,
      "can_manage_project": true,
      "can_edit_data": true
    }
  ]
}

protocol_object

object

A protocol (assay definition) and its readout definitions, calculations, and runs.

calculationsArray<object>

Calculation definitions on the protocol.

categorystring

Value of the Category protocol field, echoed at top level when present.

classstringrequired
created_atstring<date-time>
data_setinteger

Id of the data set the protocol belongs to.

descriptionstring

Value of the Description protocol field, echoed at top level when present.

hit_definitionsArray<object>
idintegerrequired
modified_atstring<date-time>
namestringrequired
ontology_annotationsArray<object>
ownerstring

Full name of the protocol owner.

projectsArray<integer>

Project ids the protocol belongs to.

protocol_fieldsobject

Custom protocol field values, keyed by field name.

protocol_statisticsArray<object>
readout_definitionsArray<object>

The readout definitions of the protocol.

runsArray<object>

Runs of the protocol. Omitted when the request passes no_runs=true.

Example
{
  "calculations": [
    {}
  ],
  "category": "string",
  "class": "protocol",
  "created_at": "2024-01-15T09:30:00Z",
  "data_set": 0,
  "description": "string",
  "hit_definitions": [
    {}
  ],
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "ontology_annotations": [
    {}
  ],
  "owner": "string",
  "projects": [
    0
  ],
  "protocol_fields": {},
  "protocol_statistics": [
    {}
  ],
  "readout_definitions": [
    {}
  ],
  "runs": [
    {}
  ]
}

protocol_update

object

Attributes for updating a protocol's definition (not its readout definitions). Only the supplied fields are changed.

namestring
projectsArray<integer>

Project ids the protocol belongs to (replaces the existing set).

protocol_fieldsobject

Custom protocol field values, keyed by field name.

Example
{
  "name": "My Inhibition Screen",
  "projects": [
    12
  ],
  "protocol_fields": {
    "Category": "Biochemical"
  }
}

readout_row_query

object
asyncboolean

If true, do an asynchronous export. Use for large data sets.

batchesArray<integer>

Array of batch ids. Defaults to all batches.

created_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

created_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

data_setsArray<integer>

Array of public dataset ids. Defaults to all data sets.

include_control_statebooleanfalse

If true, include the control state of each readout.

modified_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

modified_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

moleculesArray<integer>

Array of molecule ids. Defaults to all molecules.

offsetinteger
only_idsbooleanfalse

If true, only return the ids of the readout rows.

page_sizeinteger50

Requested page size (maximum value 1000).

platesArray<integer>

Array of plate ids. Defaults to all plates.

projectsArray<integer>

Array of project ids. Defaults to all available projects.

protocolsArray<integer>

Array of protocol ids. Defaults to all protocols.

runsArray<integer>

Array of run ids. Defaults to all runs.

runs_afterstring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

runs_beforestring<date>

Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20". You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

typeArray<string>detail_rowbatch_run_aggregate_rowbatch_protocol_aggregate_rowmolecule_protocol_aggregate_row

Filter to specific readout row types. Defaults to all types.

Example
{
  "async": true,
  "batches": [
    0
  ],
  "created_after": "2024-01-15",
  "created_before": "2024-01-15",
  "data_sets": [
    0
  ],
  "include_control_state": false,
  "modified_after": "2024-01-15",
  "modified_before": "2024-01-15",
  "molecules": [
    0
  ],
  "offset": 0,
  "only_ids": false,
  "page_size": 50,
  "plates": [
    0
  ],
  "projects": [
    0
  ],
  "protocols": [
    0
  ],
  "runs": [
    0
  ],
  "runs_after": "2024-01-15",
  "runs_before": "2024-01-15",
  "type": [
    "detail_row"
  ]
}

readout_row

object
batchinteger

ID of the batch this readout row belongs to

classstring
created_atstring

Timestamp in ISO-8601 UTC

idinteger
modified_atstring

Timestamp in ISO-8601 UTC

moleculeinteger

ID of the molecule this readout row belongs to

protocolinteger

ID of the protocol this readout row belongs to

readoutsobject

Readout values keyed by readout definition ID

runinteger

ID of the run this readout row belongs to

typestringdetail_rowbatch_run_aggregate_rowbatch_protocol_aggregate_rowmolecule_protocol_aggregate_row
wellstring

Well position for plate-based data

Example
{
  "batch": 1,
  "class": "readout row",
  "created_at": "2024-01-02T03:04:05.000Z",
  "id": 1,
  "modified_at": "2024-01-02T03:04:05.000Z",
  "molecule": 1,
  "protocol": 1,
  "readouts": {},
  "run": 1,
  "type": "detail_row",
  "well": "string"
}

registration_form

object

A registration form configured in the vault.

allow_new_moleculesbooleanrequired

Whether the form permits registering new molecules.

classstringrequired
created_atstring<date-time>required
idintegerrequired
modified_atstring<date-time>required
namestringrequired
registration_systemobject

The registration system the form belongs to. Present only when the form is associated with a registration system.

Show child attributes
classstring
idinteger
registration_typestringrequired

The kind of entity this form registers.

Example
{
  "allow_new_molecules": true,
  "class": "registration form",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "registration_system": {
    "class": "registration system",
    "id": 0
  },
  "registration_type": "string"
}

public_registration_system

object

A registration system defined in the vault.

idintegerrequired
prefixstringrequired

The registration id prefix used by this system.

Example
{
  "id": 0,
  "prefix": "CDD"
}

run_object

object

A run of a protocol (a set of readout data collected on a date).

attached_filesArray<object>

Files attached to the run.

classstringrequired
conditionsstring

Value of the Conditions run field, echoed at top level for convenience.

created_atstring<date-time>
eln_entriesArray<object>

ELN entries associated with the run.

idintegerrequired
modified_atstring<date-time>
ontology_annotationsArray<object>
personstring

Value of the Person run field, echoed at top level for convenience.

placestring

Value of the Lab run field, echoed at top level for convenience.

plate_statisticsArray<object>

Per-plate statistics for the run. Only included in the show response.

projectobjectrequired
Show child attributes
idinteger
namestring
protocolintegerrequired

Id of the protocol the run belongs to.

run_datestring<date>required
run_fieldsobject

Custom run field values, keyed by field name.

source_filesArray<object>

Source files the run was imported from.

Example
{
  "attached_files": [
    {}
  ],
  "class": "run",
  "conditions": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "eln_entries": [
    {}
  ],
  "id": 0,
  "modified_at": "2024-01-15T09:30:00Z",
  "ontology_annotations": [
    {}
  ],
  "person": "string",
  "place": "string",
  "plate_statistics": [
    {}
  ],
  "project": {
    "id": 0,
    "name": "string"
  },
  "protocol": 0,
  "run_date": "2024-01-15",
  "run_fields": {},
  "source_files": [
    {}
  ]
}

run_update

object

Attributes for updating a run. Only the supplied fields are changed.

conditionsstring

Value for the Conditions run field (alternative to run_fields).

personstring

Value for the Person run field (alternative to run_fields).

placestring

Value for the Lab run field (alternative to run_fields).

project_idinteger

Move the run to this project (requires write access to the target project).

run_datestring<date>
run_fieldsobject

Custom run field values, keyed by field name.

Example
{
  "run_date": "2026-01-15T00:00:00.000Z",
  "run_fields": {
    "Person": "Jane Smith"
  }
}

saved_search_session

object

A saved search, including its full search criteria and display settings. Fields whose value is empty are omitted from the response.

display_criteriaobject

Display/column settings saved with the search.

Show child attributes
custom_displayed_header_idsArray<any>
displayed_header_idsArray<any>
header_group_orderArray<any>
image_sizestring
max_column_widthinteger
plot_scale_typestring
row_detail_levelstring
show_all_protocol_databoolean
show_dose_response_legendboolean
show_non_matching_readoutsboolean
executed_byArray<string>

Names of users who have run the search.

idintegerrequired

The saved search id.

last_api_run_atstring<date-time>
last_ui_run_atstring<date-time>
namestringrequired
ownerstring

The search owner's name.

projectsArray<object>

Projects the search is scoped to.

saved_search_session_idinteger
search_criteriaobjectrequired

The full criteria that define the search.

Show child attributes
collection_criteriaArray<object>
Show child attributes
collection_idinteger
junctionstringANDORXOR
not_inboolean
keyword_fieldstring
keywordsstring
molecule_criteriaArray<object>

Molecule property criteria.

protocol_criteriaArray<object>
Show child attributes
protocol_idinteger

Id of the protocol to filter on (provide this or data_set_id).

data_set_idinteger

Id of the data set to filter on (provide this or protocol_id).

run_criterionstringanyrecentrun_daterun_id

Which runs to consider.

run_idinteger

Run id to match (when run_criterion is run_id).

run_afterstring<date>

Include runs on/after this date (when run_criterion is run_date).

run_beforestring<date>

Include runs on/before this date (when run_criterion is run_date).

since_days_agointeger

Number of days back to include (when run_criterion is recent).

readout_definition_idinteger

Id of the readout definition to filter on.

operatorstring=!=<>≤≥containsdoes not containfrom

Comparison operator applied to readout_value.

readout_valuestring

Value to compare the readout against.

readout_value_maximumstring

Upper bound of a range (when operator is from).

calculation_error_typestring

Filter by calculation error type.

criterion_typestringdata set or protocolrun dateprotocol field

The kind of protocol criterion.

fieldstring

Protocol field name (when criterion_type is protocol field).

querystring

Protocol field search value (when criterion_type is protocol field).

protocol_condition_idsArray<integer>

Restrict to these protocol condition ids.

negatedbooleanfalse

If true, exclude rather than include matches.

junctionstringANDORAND

How to combine this criterion with the previous one (ignored for the first criterion).

sort_directionstringASCDESC
structurestring

The query structure (SMILES/MOL), when a structure search is saved.

structure_criterionobject

A structure-property filter object. Each property is filtered by an optional _minimum and/or _maximum bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same <property>_minimum / <property>_maximum convention.

Show child attributes
heavy_atom_count_minimuminteger
heavy_atom_count_maximuminteger
cd_molweight_minimumnumber
cd_molweight_maximumnumber
exact_mass_minimumnumber
exact_mass_maximumnumber
log_p_minimumnumber
log_p_maximumnumber
log_d_minimumnumber
log_d_maximumnumber
log_s_minimumnumber
log_s_maximumnumber
num_aromatic_rings_minimuminteger
num_aromatic_rings_maximuminteger
num_h_bond_acceptors_minimuminteger
num_h_bond_acceptors_maximuminteger
num_h_bond_donors_minimuminteger
num_h_bond_donors_maximuminteger
num_rotatable_bonds_minimuminteger
num_rotatable_bonds_maximuminteger
num_rule_of_5_violations_minimuminteger
num_rule_of_5_violations_maximuminteger
topological_polar_surface_area_minimumnumber
topological_polar_surface_area_maximumnumber
structure_registration_typestringstructurenucleotide_sequenceamino_acid_sequence
structure_search_typestring
structure_similarity_thresholdnumber
visualization_session_idinteger
Example
{
  "display_criteria": {
    "custom_displayed_header_ids": [],
    "displayed_header_ids": [],
    "header_group_order": [],
    "image_size": "string",
    "max_column_width": 0,
    "plot_scale_type": "string",
    "row_detail_level": "string",
    "show_all_protocol_data": true,
    "show_dose_response_legend": true,
    "show_non_matching_readouts": true
  },
  "executed_by": [
    "string"
  ],
  "id": 0,
  "last_api_run_at": "2024-01-15T09:30:00Z",
  "last_ui_run_at": "2024-01-15T09:30:00Z",
  "name": "string",
  "owner": "string",
  "projects": [
    {}
  ],
  "saved_search_session_id": 0,
  "search_criteria": {
    "collection_criteria": [
      {
        "collection_id": 0,
        "junction": "AND",
        "not_in": true
      }
    ],
    "keyword_field": "string",
    "keywords": "string",
    "molecule_criteria": [
      {}
    ],
    "protocol_criteria": [
      {
        "protocol_id": 0,
        "data_set_id": 0,
        "run_criterion": "any",
        "run_id": 0,
        "run_after": "2024-01-15",
        "run_before": "2024-01-15",
        "since_days_ago": 0,
        "readout_definition_id": 0,
        "operator": "=",
        "readout_value": "string",
        "readout_value_maximum": "string",
        "calculation_error_type": "string",
        "criterion_type": "data set or protocol",
        "field": "string",
        "query": "string",
        "protocol_condition_ids": [
          0
        ],
        "negated": false,
        "junction": "AND"
      }
    ],
    "sort_direction": "ASC",
    "structure": "string",
    "structure_criterion": {
      "heavy_atom_count_minimum": 0,
      "heavy_atom_count_maximum": 0,
      "cd_molweight_minimum": 0,
      "cd_molweight_maximum": 0,
      "exact_mass_minimum": 0,
      "exact_mass_maximum": 0,
      "log_p_minimum": 0,
      "log_p_maximum": 0,
      "log_d_minimum": 0,
      "log_d_maximum": 0,
      "log_s_minimum": 0,
      "log_s_maximum": 0,
      "num_aromatic_rings_minimum": 0,
      "num_aromatic_rings_maximum": 0,
      "num_h_bond_acceptors_minimum": 0,
      "num_h_bond_acceptors_maximum": 0,
      "num_h_bond_donors_minimum": 0,
      "num_h_bond_donors_maximum": 0,
      "num_rotatable_bonds_minimum": 0,
      "num_rotatable_bonds_maximum": 0,
      "num_rule_of_5_violations_minimum": 0,
      "num_rule_of_5_violations_maximum": 0,
      "topological_polar_surface_area_minimum": 0,
      "topological_polar_surface_area_maximum": 0
    },
    "structure_registration_type": "structure",
    "structure_search_type": "string",
    "structure_similarity_threshold": 0
  },
  "visualization_session_id": 0
}

slurp

object

A slurp is an asynchronous data import/processing job. After creation a slurp moves through processing and committing states until its data is committed to the vault.

ambiguous_eventsArray<object>

Ambiguous events raised during import. Only present when show_events=true.

ambiguous_events_countinteger

Number of ambiguous events. Only present when show_events=true.

api_urlstringrequired

Canonical API URL of this slurp.

classstringrequired
created_atstring<date-time>required
idintegerrequired
import_errorsinteger | Array<object>

When show_events=true, the array of import error events; otherwise the count of import errors.

import_errors_countinteger

Number of import errors. Only present when show_events=true.

import_warningsinteger

Count of import warnings. Present when show_events is not requested.

messagestring

Present when the slurp has unresolved import errors or warnings that must be resolved in the web application.

modified_atstring<date-time>required
queued_job_positioninteger

Position of the slurp's job in the queue. Present only while queued.

queued_slurp_positioninteger

Position of the slurp among queued slurps. Present only while queued.

records_committednumber

Number of records committed so far.

records_processednumber

Number of records processed so far.

statestringmappingqueued_for_processingprocessingprocessedqueued_for_committingcommittingcommittedcanceledrejectedinvalidrequired

Current state of the slurp.

suspicious_eventsArray<object>

Suspicious events raised during import. Only present when show_events=true.

suspicious_events_countinteger

Number of suspicious events. Only present when show_events=true.

total_recordsnumber

Total number of records in the imported file.

web_urlstring

Web application URL for resolving import errors/warnings. Accompanies message when present.

Example
{
  "ambiguous_events": [
    {}
  ],
  "ambiguous_events_count": 0,
  "api_url": "string",
  "class": "slurp",
  "created_at": "2024-01-15T09:30:00Z",
  "id": 0,
  "import_errors": 0,
  "import_errors_count": 0,
  "import_warnings": 0,
  "message": "string",
  "modified_at": "2024-01-15T09:30:00Z",
  "queued_job_position": 0,
  "queued_slurp_position": 0,
  "records_committed": 0,
  "records_processed": 0,
  "state": "mapping",
  "suspicious_events": [
    {}
  ],
  "suspicious_events_count": 0,
  "total_records": 0,
  "web_url": "string"
}

vault_status

object

Operational status of the vault: running imports (slurps), recalculating protocols, and overall application availability. Requires vault administrator access.

any_executing_batch_move_jobbooleanrequired

Whether any batch move job is currently executing.

any_locking_chemistry_slurpsbooleanrequired

Whether any running slurp is currently holding the chemistry lock (which blocks chemistry recalculation).

application_statusobjectrequired

Overall availability of the background processing services.

Show child attributes
calculators_availablebooleanrequired

Whether calculation processors are available.

downtime_expectedobject

Present only when scheduled downtime has been announced.

Show child attributes
endstring<date-time>

When the downtime is expected to end.

reasonstring

Human-readable explanation of the downtime.

startstring<date-time>

When the downtime is expected to start.

processors_availablebooleanrequired

Whether import/data processors are available.

max_executing_account_slurpsintegerrequired

Maximum number of slurps the account may run concurrently.

num_executing_account_slurpsintegerrequired

Number of slurps currently executing across the account.

recalculating_protocolsArray<object>required

Protocols whose data is currently being recalculated.

Show child attributes
idinteger
namestring
projectsArray<object>
Show child attributes
idinteger
namestring
slurpsArray<object>required

Slurps (imports) that are currently active in the vault.

Show child attributes
chemistry_lockingboolean

Whether this slurp is holding the chemistry lock.

idinteger
modified_atstring<date-time>
ownerobject
Show child attributes
emailstring
first_namestring
idinteger
last_namestring
projectobject
Show child attributes
idinteger
namestring
statestringqueued_for_processingprocessingprocessedqueued_for_committingcommitting

Current state of the slurp. Only active slurps are listed, so the state is one of the active states below (queued slurps appear here once they exceed the account's concurrent-processing limit).

Example
{
  "any_executing_batch_move_job": true,
  "any_locking_chemistry_slurps": true,
  "application_status": {
    "calculators_available": true,
    "downtime_expected": {
      "end": "2024-01-15T09:30:00Z",
      "reason": "string",
      "start": "2024-01-15T09:30:00Z"
    },
    "processors_available": true
  },
  "max_executing_account_slurps": 0,
  "num_executing_account_slurps": 0,
  "recalculating_protocols": [
    {
      "id": 0,
      "name": "string",
      "projects": [
        {
          "id": 0,
          "name": "string"
        }
      ]
    }
  ],
  "slurps": [
    {
      "chemistry_locking": true,
      "id": 0,
      "modified_at": "2024-01-15T09:30:00Z",
      "owner": {
        "email": "string",
        "first_name": "string",
        "id": 0,
        "last_name": "string"
      },
      "project": {
        "id": 0,
        "name": "string"
      },
      "state": "queued_for_processing"
    }
  ]
}

protocol_id

integer

Numeric identifier of the protocol

integer
Example
0

fit_parameter_constraint

object

A constraint for a fit parameter

modifierstring | null

The type of constraint. Valid values are: "=" (fixed), ">", ">=", "<", "<=", "from" (range), "best fit" (unconstrained, data series only).

valuenumber | null

The constraint value. Required when modifier is "=", ">", ">=", "<", or "<=".

rangeobject

Range constraint with min and max values. Used when modifier is "from".

Show child attributes
minnumber

The minimum value of the range

maxnumber

The maximum value of the range

Example
{
  "modifier": "=",
  "value": 0.5,
  "range": {
    "min": 0,
    "max": 100
  }
}

fit_parameters

object

Fit parameter constraints for curve fitting calculations. The available parameters depend on the calculation's equation_type:

  • Hill: min, max, slope
  • Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2
  • Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2
  • Linear: slope, y_intercept
  • Exponential Decay: c_0, c_min, k
  • Michaelis-Menten: b_max, k_d
object
Example
{
  "min": {
    "modifier": "=",
    "value": 0
  },
  "max": {
    "modifier": ">=",
    "value": 100
  }
}

minimum_activity

object

Minimum activity (inactivity) bounds for dose response calculations

lowernumber | null

The lower bound for the inactive range

uppernumber | null

The upper bound for the inactive range

Example
{
  "lower": 10,
  "upper": 90
}

calculation

object

A protocol calculation

idinteger

The unique identifier of the calculation

classstring

The type of calculation. Values include "dose response calculation", "custom calculation", "normalized calculation", etc.

inputsobject

The input readout definitions used by this calculation

outputsobject

The output readout definitions produced by this calculation

fit_parametersobject

Fit parameter constraints (only for dose response calculations)

minimum_activityobject

Minimum activity bounds (only for dose response calculations)

Show child attributes
lowernumber | null

The lower bound for the inactive range

uppernumber | null

The upper bound for the inactive range

Example
{
  "id": 12345,
  "class": "dose response calculation",
  "inputs": {},
  "outputs": {},
  "fit_parameters": {
    "min": {
      "modifier": "=",
      "value": 0
    },
    "max": {
      "modifier": ">=",
      "value": 100
    }
  },
  "minimum_activity": {
    "lower": 10,
    "upper": 90
  }
}

calculations_list

object

A list of calculations for a protocol

objectsArray<object>

The list of calculations

Show child attributes
idinteger

The unique identifier of the calculation

classstring

The type of calculation. Values include "dose response calculation", "custom calculation", "normalized calculation", etc.

inputsobject

The input readout definitions used by this calculation

outputsobject

The output readout definitions produced by this calculation

fit_parametersobject

Fit parameter constraints (only for dose response calculations)

minimum_activityobject

Minimum activity bounds (only for dose response calculations)

Show child attributes
lowernumber | null

The lower bound for the inactive range

uppernumber | null

The upper bound for the inactive range

countinteger

The total number of calculations

Example
{
  "objects": [
    {
      "id": 12345,
      "class": "dose response calculation",
      "inputs": {},
      "outputs": {},
      "fit_parameters": {
        "min": {
          "modifier": "=",
          "value": 0
        },
        "max": {
          "modifier": ">=",
          "value": 100
        }
      },
      "minimum_activity": {
        "lower": 10,
        "upper": 90
      }
    }
  ],
  "count": 5
}

dose_response_calculation_id

integer

Numeric identifier of the dose response calculation

integer
Example
0

calculation_update

object

Request body for updating a dose response calculation

fit_parametersobject

Fit parameter constraints for the calculation. Setting this to an empty object clears all constraints. The available parameters depend on the calculation's equation_type:

  • Hill: min, max, slope
  • Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2
  • Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2
  • Linear: slope, y_intercept
  • Exponential Decay: c_0, c_min, k
  • Michaelis-Menten: b_max, k_d
minimum_activityobject

Minimum activity (inactivity) bounds

Show child attributes
lowernumber | null

The lower bound for the inactive range

uppernumber | null

The upper bound for the inactive range

modifierstring

The modifier type. If not specified, it is inferred from the bounds (">", "<", or "from" for range).

Example
{
  "fit_parameters": {},
  "minimum_activity": {
    "lower": 10,
    "upper": 90,
    "modifier": "from"
  }
}

dose_response_data_series

object

A dose response data series representing curve data for a specific batch/run

idinteger

The unique identifier of the data series

fit_parametersobject

Fit parameter constraints specific to this data series

updated_atstring

Timestamp of last update in ISO-8601 UTC format

Example
{
  "id": 67890,
  "fit_parameters": {
    "min": {
      "modifier": "=",
      "value": 0
    },
    "max": {
      "modifier": ">=",
      "value": 100
    }
  },
  "updated_at": "2026-01-30T14:42:24.000Z"
}

dose_response_data_series_list

object

A list of data series for a calculation

objectsArray<object>

The list of data series

Show child attributes
idinteger

The unique identifier of the data series

fit_parametersobject

Fit parameter constraints specific to this data series

updated_atstring

Timestamp of last update in ISO-8601 UTC format

countinteger

The total number of data series

Example
{
  "objects": [
    {
      "id": 67890,
      "fit_parameters": {
        "min": {
          "modifier": "=",
          "value": 0
        },
        "max": {
          "modifier": ">=",
          "value": 100
        }
      },
      "updated_at": "2026-01-30T14:42:24.000Z"
    }
  ],
  "count": 10
}

dose_response_data_series_id

integer

Numeric identifier of the dose response data series

integer
Example
0

dose_response_data_series_update

object

Request body for updating a data series

fit_parametersobject

Fit parameter constraints for this data series. These override the calculation-level constraints for this specific curve. The available parameters depend on the calculation's equation_type:

  • Hill: min, max, slope
  • Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2
  • Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2
  • Linear: slope, y_intercept
  • Exponential Decay: c_0, c_min, k
  • Michaelis-Menten: b_max, k_d Data series support "best fit" modifier for unconstrained fitting.
Example
{
  "fit_parameters": {}
}

errors

object
errorsobject
Example
{
  "errors": {
    "first_name": "First name can't be blank"
  }
}
Built withSourcey