# CDD Vault API

> Collaborative Drug Discovery provides an API (Application Programming

## Public API

- [CDD API](/public.html): Collaborative Drug Discovery provides an API (Application Programming
- [List of vaults](/public.html#operation-vaults-get): GET /vaults — Return a list of accessible vaults
- [Retrieve all fields](/public.html#operation-vaults-vault-id-fields-get): GET /vaults/{vault_id}/fields — Get all the fields both internal and user defined
- [Get pick list values](/public.html#operation-vaults-vault-id-fields-field-id-pick-list-values-get): GET /vaults/{vault_id}/fields/{field_id}/pick_list_values — List the pick list values for a vault field definition.
- [Create a pick list value](/public.html#operation-vaults-vault-id-fields-field-id-pick-list-values-post): POST /vaults/{vault_id}/fields/{field_id}/pick_list_values — Create a pick list value on a field definition. Requires vault administrator access.
- [Get a pick list value](/public.html#operation-vaults-vault-id-fields-field-id-pick-list-values-id-get): GET /vaults/{vault_id}/fields/{field_id}/pick_list_values/{id} — Retrieve a single pick list value.
- [Update a pick list value](/public.html#operation-vaults-vault-id-fields-field-id-pick-list-values-id-put): PUT /vaults/{vault_id}/fields/{field_id}/pick_list_values/{id} — Update a pick list value. Requires vault administrator access.
- [Delete a pick list value](/public.html#operation-vaults-vault-id-fields-field-id-pick-list-values-id-delete): DELETE /vaults/{vault_id}/fields/{field_id}/pick_list_values/{id} — Delete a pick list value. Requires vault administrator access.
- [API usage in seconds](/public.html#operation-vaults-vault-id-api-executions-get): GET /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.
- [Get all batch move jobs](/public.html#operation-vaults-vault-id-batch-move-jobs-get): GET /vaults/{vault_id}/batch_move_jobs — Get all batch move jobs. Requires the user to be a vault administrator.
- [Create a new batch move job](/public.html#operation-vaults-vault-id-batch-move-jobs-post): POST /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.
- [Retrieve a single batch move job](/public.html#operation-vaults-vault-id-batch-move-jobs-job-id-get): GET /vaults/{vault_id}/batch_move_jobs/{job_id} — Retrieve a single batch move job. Requires the user to be a vault administrator.
- [Cancel a single batch move job](/public.html#operation-vaults-vault-id-batch-move-jobs-job-id-delete): DELETE /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.
- [Create a batch](/public.html#operation-vaults-vault-id-batches-post): POST /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.
- [Get multiple batches](/public.html#operation-vaults-vault-id-batches-query-post): POST /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.
- [Get a single batch](/public.html#operation-vaults-vault-id-batches-batch-id-get): GET /vaults/{vault_id}/batches/{batch_id} — Get the information about a single batch
- [Update a batch](/public.html#operation-vaults-vault-id-batches-batch-id-put): PUT /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.
- [Create a collection](/public.html#operation-vaults-vault-id-collections-post): POST /vaults/{vault_id}/collections — Create a collection, the name should be unique unless you want to overwrite an existing collection.
- [Get multiple collections](/public.html#operation-vaults-vault-id-collections-query-post): POST /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.
- [Get a single collection](/public.html#operation-vaults-vault-id-collections-collection-id-get): GET /vaults/{vault_id}/collections/{collection_id} — Get the information about a single collection
- [Update a collection](/public.html#operation-vaults-vault-id-collections-collection-id-put): PUT /vaults/{vault_id}/collections/{collection_id}
- [Delete a collection](/public.html#operation-vaults-vault-id-collections-collection-id-delete): DELETE /vaults/{vault_id}/collections/{collection_id} — Delete a collection. The molecules in the collection are not affected.
- [Get control layouts](/public.html#operation-vaults-vault-id-control-layouts-get): GET /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.
- [Create a control layout](/public.html#operation-vaults-vault-id-control-layouts-post): POST /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`.
- [Get a control layout](/public.html#operation-vaults-vault-id-control-layouts-id-get): GET /vaults/{vault_id}/control_layouts/{id} — Retrieve a single control layout.
- [Delete a control layout](/public.html#operation-vaults-vault-id-control-layouts-id-delete): DELETE /vaults/{vault_id}/control_layouts/{id} — Delete a control layout.
- [Get dataset](/public.html#operation-vaults-vault-id-data-sets-get): GET /vaults/{vault_id}/data_sets — List datasets
- [Create an ELN entry](/public.html#operation-vaults-vault-id-eln-entries-post): POST /vaults/{vault_id}/eln/entries — The body of the POST must contain a JSON structure specifying the desired ELN entry attributes.
- [Get all or some ELN entries](/public.html#operation-vaults-vault-id-eln-entries-query-post): POST /vaults/{vault_id}/eln/entries/query — Returns a summary of all available ELN entries for the Vault specified if async=false (default).
- [Update an ELN entry](/public.html#operation-vaults-vault-id-eln-entries-id-put): PUT /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.
- [Perform an ELN entry status action](/public.html#operation-vaults-vault-id-eln-entries-id-status-post): POST /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.
- [Get progress of an export](/public.html#operation-vaults-vault-id-export-progress-export-id-get): GET /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”
- [Check All Current Exports](/public.html#operation-vaults-vault-id-exports-get): GET /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.
- [Get the output of an export](/public.html#operation-vaults-vault-id-exports-export-id-get): GET /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.
- [Cancel Export](/public.html#operation-vaults-vault-id-exports-export-id-delete): DELETE /vaults/{vault_id}/exports/{export_id} — Cancels an export if possible
- [Attach a file to an object](/public.html#operation-vaults-vault-id-files-post): POST /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).
- [Retrieve a file](/public.html#operation-vaults-vault-id-files-file-id-get): GET /vaults/{vault_id}/files/{file_id} — Return a single file with the content base64 encoded.
- [Delete file](/public.html#operation-vaults-vault-id-files-file-id-delete): DELETE /vaults/{vault_id}/files/{file_id} — Delete a file
- [Get import parsers](/public.html#operation-vaults-vault-id-import-parsers-get): GET /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.
- [Get an import parser](/public.html#operation-vaults-vault-id-import-parsers-id-get): GET /vaults/{vault_id}/import_parsers/{id} — Retrieve a single import parser, including its full `template_json` configuration.
- [Retrieve a list of Sample Inventory Locations for a given Vault](/public.html#operation-vaults-vault-id-inventory-locations-get): GET /vaults/{vault_id}/inventory_locations — Returns a list of inventory locations within the specified vault.
- [Get inventory samples](/public.html#operation-vaults-vault-id-inventory-samples-get): GET /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.
- [Create an inventory sample](/public.html#operation-vaults-vault-id-inventory-samples-post): POST /vaults/{vault_id}/inventory_samples — Create an inventory sample for a batch.
- [Get an inventory sample](/public.html#operation-vaults-vault-id-inventory-samples-id-get): GET /vaults/{vault_id}/inventory_samples/{id} — Retrieve a single inventory sample.
- [Update an inventory sample](/public.html#operation-vaults-vault-id-inventory-samples-id-put): PUT /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.
- [Delete an inventory sample](/public.html#operation-vaults-vault-id-inventory-samples-id-delete): DELETE /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.
- [Retrieve all the mapping templates](/public.html#operation-vaults-vault-id-mapping-templates-get): GET /vaults/{vault_id}/mapping_templates — This will give you a summary of all the mapping templates.
- [Retrieve a single mapping template](/public.html#operation-vaults-vault-id-mapping-templates-mapping-template-id-get): GET /vaults/{vault_id}/mapping_templates/{mapping_template_id} — This will give you the details about this mapping template
- [Create a molecule](/public.html#operation-vaults-vault-id-molecules-post): POST /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`.
- [Get multiple molecules](/public.html#operation-vaults-vault-id-molecules-query-post): POST /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.
- [Get a molecule](/public.html#operation-vaults-vault-id-molecules-id-get): GET /vaults/{vault_id}/molecules/{id} — Retrieve a single molecule by id. For querying multiple molecules or searching by structure, use `POST /molecules/query`.
- [Update a molecule](/public.html#operation-vaults-vault-id-molecules-id-put): PUT /vaults/{vault_id}/molecules/{id} — Update a molecule. Only the supplied fields are changed; array fields (synonyms, projects, collections) replace the existing values.
- [Get a molecule image](/public.html#operation-vaults-vault-id-molecules-id-image-get): GET /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.
- [Get plates](/public.html#operation-vaults-vault-id-plates-get): GET /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.
- [Create a plate](/public.html#operation-vaults-vault-id-plates-post): POST /vaults/{vault_id}/plates — Create a plate. Requires write permission in the vault.
- [Get a plate](/public.html#operation-vaults-vault-id-plates-id-get): GET /vaults/{vault_id}/plates/{id} — Retrieve a single plate.
- [Update a plate](/public.html#operation-vaults-vault-id-plates-id-put): PUT /vaults/{vault_id}/plates/{id} — Update a plate. Requires write permission.
- [Delete a plate](/public.html#operation-vaults-vault-id-plates-id-delete): DELETE /vaults/{vault_id}/plates/{id} — Delete a plate. Requires write permission. A plate that has associated run data cannot be deleted.
- [Get projects](/public.html#operation-vaults-vault-id-projects-get): GET /vaults/{vault_id}/projects — List the projects accessible to the API key in the vault. Each entry contains the project `id` and `name`.
- [Create a project](/public.html#operation-vaults-vault-id-projects-post): POST /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`.
- [Get a project](/public.html#operation-vaults-vault-id-projects-id-get): GET /vaults/{vault_id}/projects/{id} — Retrieve a single project, including its `description` and `members`.
- [Update a project](/public.html#operation-vaults-vault-id-projects-id-put): PUT /vaults/{vault_id}/projects/{id} — Update a project. Requires permission to manage projects. Supplying `members` replaces the existing membership list.
- [Delete a project](/public.html#operation-vaults-vault-id-projects-id-delete): DELETE /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.
- [Get protocols](/public.html#operation-vaults-vault-id-protocols-get): GET /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.
- [Get a protocol](/public.html#operation-vaults-vault-id-protocols-id-get): GET /vaults/{vault_id}/protocols/{id} — Retrieve a single protocol. Pass `no_runs=true` to omit run data.
- [Update a protocol](/public.html#operation-vaults-vault-id-protocols-id-put): PUT /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.
- [Get protocol data](/public.html#operation-vaults-vault-id-protocols-protocol-id-data-get): GET /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.
- [Get dose-response plot](/public.html#operation-vaults-vault-id-batches-batch-id-protocols-id-plot-get): GET /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.
- [Get multiple readout rows](/public.html#operation-vaults-vault-id-readout-rows-query-post): POST /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.
- [Update existing row](/public.html#operation-vaults-vault-id-readout-rows-readout-row-id-put): PUT /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).
- [Delete a readout row](/public.html#operation-vaults-vault-id-readout-rows-readout-row-id-delete): DELETE /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.
- [Get registration forms](/public.html#operation-vaults-vault-id-registration-forms-get): GET /vaults/{vault_id}/registration_forms — List the registration forms configured in the vault.
- [Get a registration form](/public.html#operation-vaults-vault-id-registration-forms-id-get): GET /vaults/{vault_id}/registration_forms/{id} — Retrieve a single registration form.
- [Get registration systems](/public.html#operation-vaults-vault-id-registration-systems-get): GET /vaults/{vault_id}/registration_systems — List the registration systems defined in the vault.
- [Get a registration system](/public.html#operation-vaults-vault-id-registration-systems-id-get): GET /vaults/{vault_id}/registration_systems/{id} — Retrieve a single registration system.
- [Get runs](/public.html#operation-vaults-vault-id-runs-get): GET /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.
- [Delete runs by slurp](/public.html#operation-vaults-vault-id-runs-delete): DELETE /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}`.)
- [Get a run](/public.html#operation-vaults-vault-id-runs-id-get): GET /vaults/{vault_id}/runs/{id} — Retrieve a single run, including its plate statistics.
- [Update a run](/public.html#operation-vaults-vault-id-runs-id-put): PUT /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.
- [Delete a run](/public.html#operation-vaults-vault-id-runs-id-delete): DELETE /vaults/{vault_id}/runs/{id} — Delete a single run. Requires write permission.
- [List of all saved searches](/public.html#operation-vaults-vault-id-searches-get): GET /vaults/{vault_id}/searches — Return a list of accessible saved searches for the given vault.
- [Execute a given search](/public.html#operation-vaults-vault-id-searches-search-id-get): GET /vaults/{vault_id}/searches/{search_id} — Unlike other calls, saved searches can only be performed asynchronously.
- [Get slurps](/public.html#operation-vaults-vault-id-slurps-get): GET /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.
- [Create a slurp](/public.html#operation-vaults-vault-id-slurps-post): POST /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.
- [Get a slurp](/public.html#operation-vaults-vault-id-slurps-id-get): GET /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.
- [Get vault status](/public.html#operation-vaults-vault-id-status-get): GET /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.
- [List of users of a vault](/public.html#operation-vaults-vault-id-users-get): GET /vaults/{vault_id}/users — Returns a list of CDD Vault members.
- [List dose response calculations for a protocol](/public.html#operation-vaults-vault-id-protocols-protocol-id-dose-response-calculations-get): GET /vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations — Get all dose response calculations for a protocol.
- [Get a single dose response calculation](/public.html#operation-vaults-vault-id-protocols-protocol-id-dose-response-calculations-dose-response-calculation-id-get): GET /vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id} — Get the details of a single dose response calculation
- [Update a dose response calculation](/public.html#operation-vaults-vault-id-protocols-protocol-id-dose-response-calculations-dose-response-calculation-id-put): PUT /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.
- [List dose response data series for a dose response calculation](/public.html#operation-vaults-vault-id-protocols-protocol-id-dose-response-calculations-dose-response-calculation-id-dose-response-data-series-get): GET /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.
- [Get a single dose response data series](/public.html#operation-vaults-vault-id-protocols-protocol-id-dose-response-calculations-dose-response-calculation-id-dose-response-data-series-dose-response-data-series-id-get): GET /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
- [Update a dose response data series](/public.html#operation-vaults-vault-id-protocols-protocol-id-dose-response-calculations-dose-response-calculation-id-dose-response-data-series-dose-response-data-series-id-put): PUT /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.
- [Find bioisosteric replacements (hierarchical)](/public.html#operation-vaults-vault-id-ai-bioisosteres-post): POST /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.
- [Find bioisosteric replacements (flat list)](/public.html#operation-vaults-vault-id-ai-bioisosteres-flat-post): POST /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.
- [Fragment a chemical structure](/public.html#operation-vaults-vault-id-ai-bioisosteres-get-fragmentation-post): POST /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.
- [Find similar structures using Deep Learning](/public.html#operation-vaults-vault-id-ai-similarity-post): POST /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.